Add search tool backed by the browser-use search API

[reformedot]

What

Adds a client-executed search tool to the async agent engine, backed by the browser-use search API (search.browser-use.com — a thin proxy in front of Parallel's Search API with browser-use auth + billing).

History: the tool was first ported from the Python DuckDuckGo Lite action, then swapped to the browser-use search API in this same PR (contract verified against the search service source).

How it differs from the existing web_search

	web_search (existing)	search (this PR)
Execution	Hosted — model provider runs it server-side	Client — the agent POSTs to the browser-use search API
Needs a capable model provider	Yes	No (works against any provider)

API integration

• POST {base}/search with {"query": …} and the X-Browser-Use-API-Key header — key read from the workspace's existing BROWSER_USE_API_KEY (fails fast with an actionable message when unset).
• Base URL overridable via BROWSER_USE_SEARCH_URL (e.g. a local dev instance, which runs as an open proxy — keyless requests are allowed there).
• 200 → {"results":[{title?, url, published_date?, content}]}: multi-line markdown content is whitespace-normalized; untitled results fall back to their URL; url-less results dropped; publication date appended to the title line.
• Errors mapped per the service's table (401 invalid key, 402 insufficient balance, 400/422/502/503 with a body snippet) and surfaced to the model as soft errors (Search failed: …).
• Output stays token-efficient: titles capped at 30 chars, descriptions at 125 (ellipsis within the cap); URLs kept intact.
• Serial scheduling (SEARCH_PARALLEL_SAFE = false) — preserves the scheduling tuning from 962a2bf/af4111c as a conservative default for a billed API call.

Architecture

• Handler follows the same trait stack (Approvable + Sandboxable + ToolRuntime) and conventions as the sibling tools; HTTP behind a SearchBackend seam (real reqwest impl + fakes in tests). No new dependencies.
• Registered in both default_registry and the production dispatcher (build_tool_dispatcher_with_cwd_and_goal_store), with a dispatcher membership test guarding the production tool set.

Tests

Deterministic suite (fixture JSON + fake backends, no network): response parsing (optional fields, url-less filtering, markdown normalization), status classification (401/402/4xx/5xx + 399/400 boundary), formatting (dates, URL fallback, truncation caps), soft-error surfacing, orchestrator/registry/dispatcher wiring, and the model-guidance description assertions. Plus an #[ignore]d live smoke (search_live_smoke) — verified end-to-end against a running search service instance with real Parallel results.

Verification

• cargo fmt --check ✓ · clippy: no new warnings ✓ · cargo test: 985 passed ✓ (2 pre-existing PTY shell_tests failures, identical on clean main) · uv run pytest ✓
• Live: BROWSER_USE_SEARCH_URL=http://localhost:8080 cargo test -p browser-use-agent --lib -- --ignored --nocapture search_live_smoke → 10 real results, correctly formatted.

Note: search.browser-use.com DNS does not resolve yet — until it's live, point the tool at an instance via BROWSER_USE_SEARCH_URL.

🤖 Generated with Claude Code

[cubic-dev-ai]

2 issues found across 6 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="crates/browser-use-agent/src/tools/registry.rs">

<violation number="1" location="crates/browser-use-agent/src/tools/registry.rs:1159">
P3: Broken intra-doc link: `[`web_search`](definitions::web_search)` in `search()`'s doc comment references `definitions::web_search` from within the same `definitions` module, resolving to a non-existent path. Should be `[`web_search`]` (same module) or use the full crate path.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

P3: Broken intra-doc link: [web_search](definitions::web_search) in search()'s doc comment references definitions::web_search from within the same definitions module, resolving to a non-existent path. Should be [web_search] (same module) or use the full crate path.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At crates/browser-use-agent/src/tools/registry.rs, line 1159:

<comment>Broken intra-doc link: `[`web_search`](definitions::web_search)` in `search()`'s doc comment references `definitions::web_search` from within the same `definitions` module, resolving to a non-existent path. Should be `[`web_search`]` (same module) or use the full crate path.</comment>

<file context>
@@ -1155,6 +1155,34 @@ to the single frame that proves the task succeeded."
     }
 
+    /// `search`: a LOCALLY-executed DuckDuckGo (Lite) web search. Unlike the
+    /// hosted [`web_search`](definitions::web_search), the client performs the
+    /// HTTP request itself and returns the parsed results as text. Ported from
+    /// the Python `search` action's description.
</file context>

Suggested change

	/// hosted [`web_search`](definitions::web_search), the client performs the
	/// hosted [`web_search`], the client performs the

[gregpr07]

DO NOT MERGE. This does not work well enough in practice and should not be merged in its current form.