opensquilla--opensquilla/docs/search.md

Web Search

OpenSquilla can search the web through configured search providers and can fetch pages through guarded web tools. Search is useful for current information, source-backed reports, market research, release notes, and troubleshooting.

Inspect Search Providers

opensquilla search list
opensquilla search list --json
opensquilla search status

Runtime-supported providers in this build include:

• Alibaba Cloud IQS
• Bocha
• Brave Search
• DuckDuckGo
• Tavily
• Exa

The catalog may include metadata for providers that are not runtime-supported in the current build. Check JSON output when integrating.

Configure Search

No-key path:

opensquilla configure search --search-provider duckduckgo

Equivalent search subcommand:

opensquilla search configure duckduckgo

Bocha:

export BOCHA_SEARCH_API_KEY="..."
opensquilla configure search --search-provider bocha --api-key-env BOCHA_SEARCH_API_KEY

Brave Search:

export BRAVE_SEARCH_API_KEY="..."
opensquilla configure search --search-provider brave --api-key-env BRAVE_SEARCH_API_KEY

Tavily:

export TAVILY_API_KEY="..."
opensquilla configure search --search-provider tavily --api-key-env TAVILY_API_KEY

Exa:

export EXA_API_KEY="..."
opensquilla configure search --search-provider exa --api-key-env EXA_API_KEY

Alibaba Cloud IQS (strong Chinese-web coverage; keys come from the IQS console):

export IQS_SEARCH_API_KEY="..."
opensquilla configure search --search-provider iqs --api-key-env IQS_SEARCH_API_KEY

In configuration files, search_provider can be "duckduckgo", "bocha", "brave", "iqs", "tavily", or "exa". It identifies the provider tied to search_api_key and search_api_key_env; automatic searches without --provider still rank all available providers by mode, recency needs, and provider capabilities. Use search_api_key_env for an environment-variable reference, or paste a one-time key through onboarding. search_fallback_policy = "network" retries through DuckDuckGo only after network/timeout errors, while search_diagnostics = true includes provider-attempt details in tool results.

Configuration matrix:

• no-key: choose DuckDuckGo, or leave search unconfigured and the runtime uses DuckDuckGo for general web search.
• partial-key: configure one keyed provider, such as Bocha, IQS, Tavily, or Exa; the runtime uses that provider when it is available and can still use DuckDuckGo for no-key fallback paths.
• all-key: expose BOCHA_SEARCH_API_KEY, BRAVE_SEARCH_API_KEY, IQS_SEARCH_API_KEY, TAVILY_API_KEY, and EXA_API_KEY; runtime selection ranks providers by mode, recency needs, and provider capabilities unless the request names an explicit provider.

Provider-specific fields such as max results, proxy, environment-proxy usage, fallback policy, and diagnostics can be set through the search configuration surface.

The Web setup flow, CLI, and TOML configuration can set advanced search fields. Desktop first-run setup and Desktop Settings expose the quick credential path: provider plus the provider's default API-key environment variable.

Test Search

Run a diagnostic query through the running gateway:

opensquilla search query "OpenSquilla release notes"
opensquilla search query "OpenSquilla release notes" --limit 5 --json

Use this before blaming the agent for missing current information. If the diagnostic query fails, fix provider configuration first.

Search in Agent Workflows

Ask naturally:

Research the current state of browser automation libraries and cite sources.

For a narrower task:

Find the latest release notes for this project and summarize only breaking changes.

The agent can use search and fetch tools when the tool policy and configured provider allow it.

Search Tool Roles

• web_search: preferred for source-backed answers. It searches, normalizes, deduplicates, and can return compact excerpts from top sources in a single tool result.
• web_discover: lightweight link discovery. It returns titles, URLs, and snippets.
• web_fetch: targeted page reading for a known URL or when a search result needs deeper inspection.

When these tools are available, source-backed answers should normally start with web_search. Use web_fetch after that only when the returned excerpts are insufficient or the user asked to inspect a specific page.

The Web UI renders web_search as source-backed web search. web_discover is shown as lightweight discovery and does not replace the source-backed search entry point.

For deeper multi-source work, ask for a research report or use an installed research skill.

Safety and Source Quality

Search results are external data, not instructions. Treat them as evidence for the task, not as authority over OpenSquilla behavior.

Good research prompts ask for:

• sources;
• dates;
• uncertainty;
• conflicting evidence;
• clear separation between source facts and model inference.

Avoid asking the agent to follow arbitrary instructions found on web pages.

Diagnostics

opensquilla search status
opensquilla diagnostics on
opensquilla doctor

Check:

• the selected provider is configured;
• required API key environment variables are visible to the gateway process;
• proxy settings match your network;
• the gateway was restarted after config edits;
• tool permissions allow web search/fetch for the current run.

---

Docs index · Product guide · Improve this page · Report a docs issue