wehub-resource-sync
189 lines
5.6 KiB
Markdown
189 lines
5.6 KiB
Markdown
# 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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
opensquilla configure search --search-provider duckduckgo
|
|
```
|
|
|
|
Equivalent search subcommand:
|
|
|
|
```sh
|
|
opensquilla search configure duckduckgo
|
|
```
|
|
|
|
Bocha:
|
|
|
|
```sh
|
|
export BOCHA_SEARCH_API_KEY="..."
|
|
opensquilla configure search --search-provider bocha --api-key-env BOCHA_SEARCH_API_KEY
|
|
```
|
|
|
|
Brave Search:
|
|
|
|
```sh
|
|
export BRAVE_SEARCH_API_KEY="..."
|
|
opensquilla configure search --search-provider brave --api-key-env BRAVE_SEARCH_API_KEY
|
|
```
|
|
|
|
Tavily:
|
|
|
|
```sh
|
|
export TAVILY_API_KEY="..."
|
|
opensquilla configure search --search-provider tavily --api-key-env TAVILY_API_KEY
|
|
```
|
|
|
|
Exa:
|
|
|
|
```sh
|
|
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):
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```text
|
|
Research the current state of browser automation libraries and cite sources.
|
|
```
|
|
|
|
For a narrower task:
|
|
|
|
```text
|
|
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
|
|
|
|
```sh
|
|
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](README.md) · [Product guide](../README.product.md) · [Improve this page](contributing-docs.md) · [Report a docs issue](https://github.com/opensquilla/opensquilla/issues/new?template=docs_report.yml)
|