feat(buzz-agent): expose provider-native web search tools
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
### **Motivation**
Buzz Desktop's default managed-agent runtime is `buzz-agent`. When it is configured with a direct Anthropic API key or an OpenRouter API key, provider-hosted web search is not exposed to the model.
**Observed on Windows with the same research prompt:**
- Anthropic Sonnet through **Buzz Agent** uses the local `buzz-dev-mcp` shell and `curl`.
- OpenRouter (tried with DeepSeek V4 Flash) through **Buzz Agent** does the same.
- Using native harness for Claude Code and Codex runtimes use their provider-native hosted web tools.
The distinction matters: `buzz-acp` is the relay/ACP bridge used with multiple runtimes; the missing capability is specifically in the built-in `buzz-agent` provider client. This may be intentional because hosted search has separate cost and policy implications, but users currently have no setting to allow it.
**Current source behavior:**
- Desktop defaults to `buzz-agent` and gives it `buzz-dev-mcp`: [runtime catalog](https://github.com/block/buzz/blob/main/desktop/src-tauri/src/managed_agents/discovery.rs).
- Anthropic tools are serialized only from MCP `ToolDef` values; no Anthropic `web_search_*` server tool is added: [`anthropic_body`](https://github.com/block/buzz/blob/main/crates/buzz-agent/src/llm.rs).
- OpenRouter requests likewise expose only function tools; no `openrouter:web_search` server tool is added.
- The response parsers do not preserve hosted-search result/citation structures such as Anthropic `server_tool_use` / `web_search_tool_result` or OpenRouter `url_citation` annotations.
An API key authenticates the request but does not enable hosted search by itself; the client must declare the provider's server tool.
### **Proposed solution**
Add an explicit per-agent setting such as **Allow provider-hosted web search**, preserving today's behavior when disabled.
When enabled, `buzz-agent` should:
- add the provider-specific hosted-search tool where supported (Anthropic `web_search_*`, OpenRouter `openrouter:web_search`, and OpenAI Responses `web_search`);
- let the model decide when to search;
- preserve citations and server-tool usage in the returned answer/history;
- handle provider-specific continuation states such as Anthropic `pause_turn`;
- expose a bounded maximum-use option and make additional search cost clear in the UI.
Unsupported providers/models should fail clearly or leave the tool unavailable rather than silently implying that an API key includes internet access.
### **Alternatives considered**
- Use Claude Code or Codex instead of Buzz Agent. This works, but does not help users choosing Buzz Agent specifically for BYOK/provider flexibility.
- Use `curl` through the local shell. This depends on local network policy and loses provider-hosted search controls and structured citations.
- Add a web-search MCP server. Viable, but adds separate configuration and credentials for a capability already offered by several configured providers.
- For OpenRouter, use the deprecated `:online` model variant/web plugin. The recommended interface is now `tools: [{"type":"openrouter:web_search"}]`.
**Additional context**
Provider documentation:
- [Anthropic web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)
- [OpenRouter web search server tool](https://openrouter.ai/docs/guides/features/server-tools/web-search)
Closest related issues, but different scope:
- #4515 documents connecting an external web-search/scraping MCP server.
- #4550 concerns MCP injection for preset/custom ACP runtimes.
- #4158 notes that evidence acquisition is an explicit backend capability for a proposed research agent.
No issue or PR specifically covering provider-native hosted search in `buzz-agent` was found after searching open and closed items for `web_search`, “native search”, `openrouter:web_search`, `server_tool_use`, and related terms.
Contributor guide
Research direction
Start with desktop/src-tauri/src/managed_agents/discovery.rs and crates/buzz-agent/src/llm.rs, then compare the linked Anthropic and OpenRouter tool specifications. Done means an explicit per-agent setting preserves disabled behavior while supporting provider-specific tools, continuation and citation handling, bounded usage and cost visibility, and clear unsupported-provider behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- api, backend, desktop
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100