| name | web-search |
| description | Search the web for up-to-date information using a public search API. Use when: the user asks for current events, recent docs, prices, or any fact that may have changed since training. NOT for: looking up stable facts (just answer), reading a known URL (use web_fetch directly), or working with documents already in the workspace. |
| metadata | {"all_agents":{"emoji":"🔎","requires":{"bins":["curl"]}},"secrets":[{"name":"BRAVE_API_KEY","description":"Brave Search API subscription token","url":"https://api.search.brave.com/app/keys","required":false}]} |
Web Search
Use this skill when the user asks something whose answer depends on live or
recent information. Compose existing tools — there is no dedicated
web_search tool.
Decision tree
- Brave Search — preferred when
BRAVE_API_KEY is configured.
- DuckDuckGo HTML — fallback, no API key.
- Direct fetch — if the user already named a URL, skip search and call
web_fetch directly.
Brave Search (recommended)
The API requires the X-Subscription-Token header. The web_fetch tool
does not pass custom headers, so use run_command with curl:
curl -s -G "https://api.search.brave.com/res/v1/web/search" \
--data-urlencode "q=YOUR QUERY" \
--data-urlencode "count=5" \
-H "X-Subscription-Token: $BRAVE_API_KEY" \
-H "Accept: application/json" | jq '.web.results[] | {title, url, description}'
Read the value of BRAVE_API_KEY from the secret store. Either:
- export it in the shell first via
all-agents secrets export and source env.exported, OR
- pass it inline by reading
~/.all-agents/secrets/secrets.json (mode 0600).
DuckDuckGo (no key)
curl -sL "https://duckduckgo.com/html/?q=YOUR+QUERY" \
| grep -oE 'href="[^"]*"' | head -20
The HTML output is messy — extract the first 5–10 result URLs and pass
them to web_fetch for content.
After search
Always follow up: pick the 1–3 most relevant URLs, call web_fetch on
each, then answer. Cite the URL alongside the fact.
