Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

feat(tools): add Brave Search as a web search provider (toby) (#3801)

OliverBryant15c4ce540f01
diff --git a/frontend/src/app/tools/page.tsx b/frontend/src/app/tools/page.tsx
index 2bdd4a022..ce34765e0 100644
--- a/frontend/src/app/tools/page.tsx
+++ b/frontend/src/app/tools/page.tsx
@@ -868,6 +868,7 @@ function ToolsPageContent() {
if (tool.name === 'web_search') {
const description = tool.description.toLowerCase()
if (description.includes('tavily')) return 'tavily_web_search'
+ if (description.includes('brave')) return 'brave_web_search'
return 'web_search'
}
@@ -899,6 +900,9 @@ function ToolsPageContent() {
if (toolName === 'tavily_web_search') {
return 'Configure Tavily credentials to enable web search without Google setup.'
}
+ if (toolName === 'brave_web_search') {
+ return 'Configure Brave Search credentials to enable web search without Google setup.'
+ }
if (toolName === 'web_search') {
return 'Configure Google Search credentials to enable the web search runtime tool.'
}
diff --git a/src/xagent/config.py b/src/xagent/config.py
index d915ff86b..7a19aa470 100644
--- a/src/xagent/config.py
+++ b/src/xagent/config.py
@@ -220,6 +220,7 @@ SANDBOX_WORKSPACE_VOLUME_ROOT = "XAGENT_SANDBOX_WORKSPACE_VOLUME_ROOT"
SANDBOX_WORKER_ID = "XAGENT_SANDBOX_WORKER_ID"
TASK_RUNTIME_SECRETS_TTL_SECONDS = "XAGENT_TASK_RUNTIME_SECRETS_TTL_SECONDS"
WEB_SEARCH_PROVIDER = "XAGENT_WEB_SEARCH_PROVIDER"
+BRAVE_SEARCH_ENDPOINT = "XAGENT_BRAVE_SEARCH_ENDPOINT"
WEB_CRAWL_TLS_IMPERSONATE = "XAGENT_WEB_CRAWL_TLS_IMPERSONATE"
TOOL_PARALLEL_ENABLED = "XAGENT_TOOL_PARALLEL_ENABLED"
TOOL_MAX_CONCURRENCY = "XAGENT_TOOL_MAX_CONCURRENCY"
@@ -357,7 +358,11 @@ TOOL_MAX_FIELD_COUNT = "XAGENT_TOOL_MAX_FIELD_COUNT"
MAX_TRACE_PAYLOAD_BYTES = "XAGENT_MAX_TRACE_PAYLOAD_BYTES"
INLINE_FILE_DELIVERY_MAX_BYTES = "XAGENT_INLINE_FILE_DELIVERY_MAX_BYTES"
-WEB_SEARCH_PROVIDERS = {"auto", "google", "tavily", "exa", "zhipu"}
+WEB_SEARCH_PROVIDERS = {"auto", "google", "tavily", "exa", "zhipu", "brave"}
+BRAVE_SEARCH_ENDPOINTS = {"web", "llm_context"}
+# Returned by get_web_search_provider() for an unrecognised, non-empty value:
+# no web search tool is registered (fail closed).
+WEB_SEARCH_PROVIDER_INVALID = "invalid"
def get_agent_runtime() -> Literal["v1", "v2"]:
@@ -4599,18 +4604,40 @@ def get_web_search_provider() -> str:
1. XAGENT_WEB_SEARCH_PROVIDER environment variable
2. "auto"
- Valid values are: auto, google, tavily, exa, zhipu.
+ Valid values are: auto, google, tavily, exa, zhipu, brave.
+
+ An unset or empty value means "auto". An unrecognised value fails closed:
+ ``WEB_SEARCH_PROVIDER_INVALID`` is returned and no search tool is
+ registered, so a deployment that pins a provider (for example for data
+ retention reasons) never silently searches through another one.
"""
- provider = (os.getenv(WEB_SEARCH_PROVIDER) or "auto").strip().lower()
+ provider = (os.getenv(WEB_SEARCH_PROVIDER) or "").strip().lower()
+ if not provider:
+ return "auto"
if provider in WEB_SEARCH_PROVIDERS:
return provider
- logger.warning(
- "Invalid %s value: %r. Falling back to 'auto'.",
+ logger.error(
+ "Unrecognised %s value; web search is disabled. Valid values: %s.",
WEB_SEARCH_PROVIDER,
- provider,
+ ", ".join(sorted(WEB_SEARCH_PROVIDERS)),
)
- return "auto"
+ return WEB_SEARCH_PROVIDER_INVALID
+
+
+def get_brave_search_endpoint() -> str:
+ """Get the Brave Search endpoint: "web" (default) or "llm_context"."""
+ endpoint = (os.getenv(BRAVE_SEARCH_ENDPOINT) or "").strip().lower()
+ if not endpoint:
+ return "web"
+ if endpoint in BRAVE_SEARCH_ENDPOINTS:
+ return endpoint
+ logger.warning(
+ "Invalid %s value. Falling back to 'web'. Valid values: %s.",
+ BRAVE_SEARCH_ENDPOINT,
+ ", ".join(sorted(BRAVE_SEARCH_ENDPOINTS)),
+ )
+ return "web"
def get_web_crawl_tls_impersonate() -> str | None:
diff --git a/src/xagent/core/tools/adapters/vibe/basic_tools.py b/src/xagent/core/tools/adapters/vibe/basic_tools.py
index 847f2214f..9c2743bc1 100644
--- a/src/xagent/core/tools/adapters/vibe/basic_tools.py
+++ b/src/xagent/core/tools/adapters/vibe/basic_tools.py
@@ -32,13 +32,14 @@ async def create_web_tools(config: "BaseToolConfig") -> List[Any]:
logger.warning("Skipping %s: stored credential is unreadable", tool_name)
return [None for _ in fields]
- # Web search tool preference in auto mode: Zhipu -> Tavily -> Exa -> Google -> none
+ # Web search tool preference in auto mode: Zhipu -> Tavily -> Exa -> Google -> Brave -> none
zhipu_api_key, zhipu_base_url = credentials(
"zhipu_web_search", "api_key", "base_url"
)
(tavily_api_key,) = credentials("tavily_web_search", "api_key")
google_api_key, google_cse_id = credentials("web_search", "api_key", "cse_id")
(exa_api_key,) = credentials("exa_web_search", "api_key")
+ (brave_api_key,) = credentials("brave_web_search", "api_key")
provider = get_web_search_provider()
if provider in ("auto", "zhipu") and zhipu_api_key:
@@ -57,6 +58,10 @@ async def create_web_tools(config: "BaseToolConfig") -> List[Any]:
from .web_search import WebSearchTool
tools.append(WebSearchTool(api_key=google_api_key, cse_id=google_cse_id))
+ elif provider in ("auto", "brave") and brave_api_key:
+ from .brave_web_search import BraveWebSearchTool
+
+ tools.append(BraveWebSearchTool(api_key=brave_api_key))
from .fetch_web_content import FetchWebContentTool
diff --git a/src/xagent/core/tools/adapters/vibe/brave_web_search.py b/src/xagent/core/tools/adapters/vibe/brave_web_search.py
new file mode 100644
index 000000000..9d2b282f0
--- /dev/null
+++ b/src/xagent/core/tools/adapters/vibe/brave_web_search.py
@@ -0,0 +1,82 @@
+"""
+Brave Web Search Tool for xagent
+Framework wrapper around the Brave Search API.
+"""
+
+from typing import Any, Dict, List, Mapping, Type
+
+from pydantic import BaseModel, Field
+
+from ...core.brave_web_search import BraveWebSearchCore
+from .base import AbstractBaseTool, ToolCategory, ToolVisibility
+
+
+class BraveWebSearchArgs(BaseModel):
+ query: str = Field(
+ description="The search query string (max 600 characters and 75 words)"
+ )
+ num_results: int = Field(
+ default=5, description="Number of results to return (max 20)"
+ )
+ include_content: bool = Field(
+ default=False,
+ description=(
+ "Also include page content for each result. Defaults to false; "
+ "prefer fetch_web_content for reading one selected URL."
+ ),
+ )
+
+
+class BraveWebSearchResult(BaseModel):
+ results: List[Dict[str, str]] = Field(
+ description="Search results with title, link, snippet, and optional content"
+ )
+
+
+class BraveWebSearchTool(AbstractBaseTool):
+ """Framework wrapper for the Brave web search tool."""
+
+ category = ToolCategory.WEB_TOOLS
+ read_only = True # read-only HTTP search ⇒ concurrency-safe
+
+ def __init__(self, api_key: str | None = None) -> None:
+ self._visibility = ToolVisibility.PUBLIC
+ self._api_key = api_key
+
+ @property
+ def name(self) -> str:
+ return "web_search"
+
+ @property
+ def description(self) -> str:
+ return (
+ "Search the web for information using Brave Search. "
+ "Returns lightweight results with titles, links, and snippets by default. "
+ "Set include_content=true only when every result needs page content; "
+ "otherwise use fetch_web_content to read one selected URL."
+ )
+
+ @property
+ def tags(self) -> list[str]:
+ return ["search", "web", "information", "research", "brave"]
+
+ def args_type(self) -> Type[BaseModel]:
+ return BraveWebSearchArgs
+
+ def return_type(self) -> Type[BaseModel]:
+ return BraveWebSearchResult
+
+ def run_json_sync(self, args: Mapping[str, Any]) -> Any:
+ raise NotImplementedError("BraveWebSearchTool only supports async execution.")
+
+ async def run_json_async(self, args: Mapping[str, Any]) -> Any:
+ search_args = BraveWebSearchArgs.model_validate(args)
+ searcher = BraveWebSearchCore(api_key=self._api_key)
+
+ results = await searcher.search(
+ query=search_args.query,
+ max_results=search_args.num_results,
+ include_content=search_args.include_content,
+ )
+
+ return BraveWebSearchResult(results=results).model_dump()
diff --git a/src/xagent/core/tools/adapters/vibe/categories.py b/src/xagent/core/tools/adapters/vibe/categories.py
index 2a98ded50..aa26561c7 100644
--- a/src/xagent/core/tools/adapters/vibe/categories.py
+++ b/src/xagent/core/tools/adapters/vibe/categories.py
@@ -36,6 +36,7 @@ def configurable_tool_category(tool_name: str) -> str:
"tavily_web_search",
"zhipu_web_search",
"exa_web_search",
+ "brave_web_search",
}:
return ToolCategory.WEB_TOOLS.value
if tool_name == "sql_query":
diff --git a/src/xagent/core/tools/core/brave_web_search.py b/src/xagent/core/tools/core/brave_web_search.py
new file mode 100644
index 000000000..f0f90374f
--- /dev/null
+++ b/src/xagent/core/tools/core/brave_web_search.py
@@ -0,0 +1,256 @@
+"""
+Brave Web Search Tool
+Standalone web search functionality using the Brave Search API.
+
+Two endpoints are supported, chosen by ``XAGENT_BRAVE_SEARCH_ENDPOINT``:
+
+* ``web``: ``GET /res/v1/web/search`` (titles, links and descriptions).
+* ``llm_context``: ``POST /res/v1/llm/context`` (extracted page snippets).
+ The query travels in the JSON body, not in the URL.
+
+Privacy: the search query is never logged, and no error message is built from
+the text of an ``httpx`` exception, because that text contains the request URL
+(which carries the query on the ``web`` endpoint).
+"""
+
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from ....config import get_brave_search_endpoint
+from .web_content import WebContentFetcher
+
+logger = logging.getLogger(__name__)
+
+BRAVE_WEB_SEARCH_URL = "https://api.search.brave.com/res/v1/web/search"
+BRAVE_LLM_CONTEXT_URL = "https://api.search.brave.com/res/v1/llm/context"
+
+# Brave's documented limits for the ``q`` parameter.
+MAX_QUERY_CHARS = 600
+MAX_QUERY_WORDS = 75
+
+MAX_RESULTS = 20
+SNIPPET_MAX_CHARS = 500
+CONTENT_MAX_CHARS = 8192
+LLM_CONTEXT_MAX_TOKENS = 8192
+
+
+class _DropBraveRequestLogs(logging.Filter):
+ """Drop httpx's per-request INFO line for Brave calls.
+
+ httpx logs ``HTTP Request: GET <full url>``; on the ``web`` endpoint the URL
+ carries the search query.
+ """
+
+ def filter(self, record: logging.LogRecord) -> bool:
+ try:
+ return "api.search.brave.com" not in record.getMessage()
+ except Exception:
+ return True
+
+
+_httpx_filter_installed = False
+
+
+def _install_httpx_log_filter() -> None:
+ global _httpx_filter_installed
+ if not _httpx_filter_installed:
+ logging.getLogger("httpx").addFilter(_DropBraveRequestLogs())
+ _httpx_filter_installed = True
+
+
+class BraveWebSearchCore:
+ """Pure Brave web search tool without framework dependencies."""
+
+ def __init__(self, api_key: str | None = None) -> None:
+ self._api_key = api_key
+ _install_httpx_log_filter()
+
+ async def search(
+ self,
+ query: str,
+ max_results: int = 5,
+ include_content: bool = False,
+ ) -> List[Dict[str, str]]:
+ """
+ Search the web using the Brave Search API.
+
+ Args:
+ query: The search query string (max 600 characters and 75 words)
+ max_results: Number of results to return (max 20)
+ include_content: Whether to include page content for each result
+
+ Returns:
+ List of search results with title, link, snippet and optionally content
+ """
+ return await self._search_redacted(query, max_results, include_content)
+
+ async def _search_redacted(
+ self,
+ query: str,
+ max_results: int = 5,
+ include_content: bool = False,
+ ) -> List[Dict[str, str]]:
+ """Run the search for the query that is actually sent to Brave.
+
+ All request logic lives here so a shared pre-send step (query
+ redaction, audit) can wrap ``search`` with a single call. The length
+ check applies to the text that goes on the wire.
+ """
+ self._validate_query(query)
+
+ api_key = self._api_key or os.getenv("BRAVE_SEARCH_API_KEY")
+ if not api_key:
+ raise ValueError(
+ "Missing required environment variable BRAVE_SEARCH_API_KEY. "
+ "Get one at https://brave.com/search/api/"
+ )
+
+ max_results = min(max(1, max_results), MAX_RESULTS)
+ endpoint = get_brave_search_endpoint()
+ logger.info(
+ "Brave web search endpoint=%s max_results=%s include_content=%s",
+ endpoint,
+ max_results,
+ include_content,
+ )
+
+ proxy_url = self._get_proxy_url()
+ if proxy_url:
+ # Do not log the URL: it can carry proxy credentials.
+ logger.info("Using proxy for Brave web search")
+
+ headers = {
+ "X-Subscription-Token": api_key,
+ "Accept": "application/json",
+ }
+ client_kwargs: Dict[str, Any] = {}
+ if proxy_url:
+ client_kwargs["proxy"] = proxy_url
+
+ try:
+ async with httpx.AsyncClient(**client_kwargs) as client:
+ if endpoint == "llm_context":
+ response = await client.post(
+ BRAVE_LLM_CONTEXT_URL,
+ json={
+ "q": query,
+ "count": max_results,
+ "maximum_number_of_tokens": LLM_CONTEXT_MAX_TOKENS,
+ },
+ headers=headers,
+ timeout=30,
+ )
+ else:
+ response = await client.get(
+ BRAVE_WEB_SEARCH_URL,
+ params={
+ "q": query,
+ "count": max_results,
+ "text_decorations": "false",
+ },
+ headers=headers,
+ timeout=30,
+ )
+ except httpx.RequestError as e:
+ # type(e).__name__ only: str(e) can contain the request URL.
+ logger.error("Network error during Brave search: %s", type(e).__name__)
+ raise ValueError(
+ f"Network error during Brave search ({type(e).__name__})"
+ ) from None
+
+ self._raise_for_status(response.status_code)
+
+ try:
+ data = response.json()
+ except ValueError:
+ logger.error("Brave search returned a non-JSON body")
+ raise ValueError("Brave search returned an invalid response body") from None
+
+ if endpoint == "llm_context":
+ results = self._normalize_llm_context(data, include_content)
+ else:
+ results = await self._normalize_web(data, include_content, proxy_url)
+ logger.info("Brave search returned %d results", len(results))
+ return results
+
+ @staticmethod
+ def _validate_query(query: str) -> None:
+ if len(query) > MAX_QUERY_CHARS:
+ raise ValueError(
+ f"Brave search query is too long: the limit is "
+ f"{MAX_QUERY_CHARS} characters."
+ )
+ if len(query.split()) > MAX_QUERY_WORDS:
+ raise ValueError(
+ f"Brave search query has too many words: the limit is "
+ f"{MAX_QUERY_WORDS} words."
+ )
+
+ @staticmethod
+ def _raise_for_status(status: int) -> None:
+ if status in {401, 403}:
+ raise ValueError(
+ f"Brave Search API auth failed ({status}). "
+ "Please check BRAVE_SEARCH_API_KEY."
+ )
+ if status == 429:
+ raise ValueError(
+ "Brave Search API rate limit or quota exceeded (429). "
+ "Please retry later."
+ )
+ if status >= 400:
+ logger.error("Brave Search API HTTP error: %s", status)
+ raise ValueError(f"Brave Search API HTTP error ({status})")
+
+ @staticmethod
+ def _normalize_llm_context(
+ data: Dict[str, Any], include_content: bool
+ ) -> List[Dict[str, str]]:
+ """Map ``grounding.generic[]`` to xagent's standard result format."""
+ results: List[Dict[str, str]] = []
+ grounding = data.get("grounding") if isinstance(data, dict) else None
+ generic = grounding.get("generic") if isinstance(grounding, dict) else None
+ for item in generic or []:
+ snippets = [s for s in (item.get("snippets") or []) if isinstance(s, str)]
+ result: Dict[str, str] = {
+ "title": item.get("title") or "",
+ "link": item.get("url") or "",
+ "snippet": (snippets[0] if snippets else "")[:SNIPPET_MAX_CHARS],
+ }
+ if include_content:
+ result["content"] = "\n\n".join(snippets)[:CONTENT_MAX_CHARS]
+ results.append(result)
+ return results
+
+ async def _normalize_web(
+ self,
+ data: Dict[str, Any],
+ include_content: bool,
+ proxy_url: Optional[str],
+ ) -> List[Dict[str, str]]:
+ """Map ``web.results[]`` to xagent's standard result format."""
+ results: List[Dict[str, str]] = []
+ web = data.get("web") if isinstance(data, dict) else None
+ items = web.get("results") if isinstance(web, dict) else None
+ for item in items or []:
+ result: Dict[str, str] = {
+ "title": item.get("title") or "",
+ "link": item.get("url") or "",
+ "snippet": item.get("description") or "",
+ }
+ if include_content:
+ result["content"] = await WebContentFetcher(
+ proxy_url=proxy_url
+ ).fetch_text(result["link"])
+ results.append(result)
+ return results
+
+ @staticmethod
+ def _get_proxy_url() -> Optional[str]:
+ """Get proxy URL from environment variables."""
+ https_proxy = os.getenv("HTTPS_PROXY") or os.getenv("https_proxy")
+ http_proxy = os.getenv("HTTP_PROXY") or os.getenv("http_proxy")
+ return https_proxy or http_proxy
diff --git a/src/xagent/web/init_tool_configs.py b/src/xagent/web/init_tool_configs.py
index 10e73aa34..c9c4a1b3a 100644
--- a/src/xagent/web/init_tool_configs.py
+++ b/src/xagent/web/init_tool_configs.py
@@ -63,6 +63,20 @@ def get_default_tool_configs() -> list[Dict[str, Any]]:
},
"dependencies": ["tavily_api_key"],
},
+ {
+ "tool_name": "brave_web_search",
+ "tool_type": "builtin",
+ "category": "search",
+ "display_name": "Brave 网络搜索",
+ "description": "使用 Brave Search API 进行网络搜索,无需 Google 账号",
+ "enabled": True,
+ "requires_configuration": True,
+ "config": {
+ "provider": "brave",
+ "api_key_env": "BRAVE_SEARCH_API_KEY",
+ },
+ "dependencies": ["brave_api_key"],
+ },
{
"tool_name": "exa_web_search",
"tool_type": "builtin",
diff --git a/src/xagent/web/services/tool_credentials.py b/src/xagent/web/services/tool_credentials.py
index 29199721d..64dc2b825 100644
--- a/src/xagent/web/services/tool_credentials.py
+++ b/src/xagent/web/services/tool_credentials.py
@@ -150,6 +150,14 @@ TOOL_CREDENTIAL_SPECS: dict[str, dict[str, ToolFieldSpec]] = {
"label": "API Key",
}
},
+ "brave_web_search": {
+ "api_key": {
+ "secret": True,
+ "env": ["BRAVE_SEARCH_API_KEY"],
+ "required": True,
+ "label": "API Key",
+ }
+ },
"web_search": {
"api_key": {
"secret": True,
diff --git a/tests/core/test_config.py b/tests/core/test_config.py
index 8c83be5eb..7b6348f07 100644
--- a/tests/core/test_config.py
+++ b/tests/core/test_config.py
@@ -125,6 +125,7 @@ from xagent.config import (
WEB_CRAWL_TLS_IMPERSONATE,
WEB_DIR,
WEB_SEARCH_PROVIDER,
+ WEB_SEARCH_PROVIDERS,
XROUTER_EXCLUDED_MODELS,
ExternalUploadsDirConfigurationError,
format_file_size,
@@ -135,6 +136,7 @@ from xagent.config import (
get_background_job_stale_seconds,
get_background_job_sweep_interval_seconds,
get_background_job_visibility_timeout_seconds,
+ get_brave_search_endpoint,
get_browser_cua_driver_command,
get_browser_cua_driver_max_elements,
get_browser_cua_driver_socket,
@@ -1024,10 +1026,36 @@ class TestGetWebSearchProvider:
monkeypatch.setenv(WEB_SEARCH_PROVIDER, " Google ")
assert get_web_search_provider() == "google"
- def test_invalid_web_search_provider_falls_back_to_auto(self, monkeypatch):
- monkeypatch.setenv(WEB_SEARCH_PROVIDER, "bing")
+ def test_brave_web_search_provider(self, monkeypatch):
+ monkeypatch.setenv(WEB_SEARCH_PROVIDER, "Brave")
+ assert get_web_search_provider() == "brave"
+
+ def test_empty_web_search_provider_means_auto(self, monkeypatch):
+ monkeypatch.setenv(WEB_SEARCH_PROVIDER, " ")
assert get_web_search_provider() == "auto"
+ def test_invalid_web_search_provider_fails_closed(self, monkeypatch, caplog):
+ monkeypatch.setenv(WEB_SEARCH_PROVIDER, "bing")
+ with caplog.at_level("ERROR"):
+ provider = get_web_search_provider()
+ assert provider not in WEB_SEARCH_PROVIDERS
+ assert provider != "auto"
+ assert WEB_SEARCH_PROVIDER in caplog.text
+
+
+class TestGetBraveSearchEndpoint:
+ def test_default_and_values(self, monkeypatch):
+ monkeypatch.delenv("XAGENT_BRAVE_SEARCH_ENDPOINT", raising=False)
+ assert get_brave_search_endpoint() == "web"
+ monkeypatch.setenv("XAGENT_BRAVE_SEARCH_ENDPOINT", " LLM_Context ")
+ assert get_brave_search_endpoint() == "llm_context"
+
+ def test_unknown_value_uses_web_and_warns(self, monkeypatch, caplog):
+ monkeypatch.setenv("XAGENT_BRAVE_SEARCH_ENDPOINT", "bogus")
+ with caplog.at_level("WARNING"):
+ assert get_brave_search_endpoint() == "web"
+ assert "XAGENT_BRAVE_SEARCH_ENDPOINT" in caplog.text
+
class TestGetWebCrawlTlsImpersonate:
"""Test get_web_crawl_tls_impersonate() function."""
diff --git a/tests/core/tools/adapters/vibe/test_basic_tools_web_search_provider.py b/tests/core/tools/adapters/vibe/test_basic_tools_web_search_provider.py
index a42b27b45..6eb6451f0 100644
--- a/tests/core/tools/adapters/vibe/test_basic_tools_web_search_provider.py
+++ b/tests/core/tools/adapters/vibe/test_basic_tools_web_search_provider.py
@@ -193,3 +193,79 @@ async def test_basic_tools_include_web_asset_download_with_workspace(
names = _tool_names(tools)
assert "fetch_web_content" in names
assert "download_web_asset" in names
+
+
+_ALL_SEARCH_CREDENTIALS = {
+ "zhipu_web_search": {"api_key": "zhipu-key"},
+ "tavily_web_search": {"api_key": "tavily-key"},
+ "exa_web_search": {"api_key": "exa-key"},
+ "web_search": {"api_key": "google-key", "cse_id": "google-cse-id"},
+ "brave_web_search": {"api_key": "brave-key"},
+}
+
+
+async def _search_tool_class(credentials, provider=None, monkeypatch=None):
+ if provider is None:
+ monkeypatch.delenv("XAGENT_WEB_SEARCH_PROVIDER", raising=False)
+ else:
+ monkeypatch.setenv("XAGENT_WEB_SEARCH_PROVIDER", provider)
+ tools = await create_web_tools(
+ ToolConfig({"workspace": None, "tool_credentials": credentials})
+ )
+ search = [
+ t for t in tools if t.name == "web_search" or t.name.endswith("_web_search")
+ ]
+ assert len(search) <= 1
+ return search[0].__class__.__name__ if search else None
+
+
+async def test_explicit_brave_provider_uses_brave(monkeypatch):
+ assert (
+ await _search_tool_class(_ALL_SEARCH_CREDENTIALS, "brave", monkeypatch)
+ == "BraveWebSearchTool"
+ )
+
+
+async def test_explicit_brave_provider_without_key_adds_no_search_tool(monkeypatch):
+ credentials = {
+ k: v for k, v in _ALL_SEARCH_CREDENTIALS.items() if k != "brave_web_search"
+ }
+ assert await _search_tool_class(credentials, "brave", monkeypatch) is None
+
+
+ "present,expected",
+ [
+ (["brave_web_search"], "BraveWebSearchTool"),
+ (["web_search", "brave_web_search"], "WebSearchTool"),
+ (["exa_web_search", "web_search", "brave_web_search"], "ExaWebSearchTool"),
+ (
+ ["tavily_web_search", "exa_web_search", "web_search", "brave_web_search"],
+ "TavilyWebSearchTool",
+ ),
+ (list(_ALL_SEARCH_CREDENTIALS), "ZhipuWebSearchTool"),
+ ],
+)
+async def test_auto_order_keeps_brave_last(monkeypatch, present, expected):
+ credentials = {k: _ALL_SEARCH_CREDENTIALS[k] for k in present}
+ assert await _search_tool_class(credentials, None, monkeypatch) == expected
+
+
[email protected]("value", ["bing", "braave", "Brave Search"])
+async def test_unknown_provider_registers_no_search_tool(monkeypatch, caplog, value):
+ with caplog.at_level("ERROR"):
+ cls = await _search_tool_class(_ALL_SEARCH_CREDENTIALS, value, monkeypatch)
+ assert cls is None
+ assert "XAGENT_WEB_SEARCH_PROVIDER" in caplog.text
+
+
+async def test_empty_provider_value_means_auto(monkeypatch):
+ assert (
+ await _search_tool_class(_ALL_SEARCH_CREDENTIALS, " ", monkeypatch)
+ == "ZhipuWebSearchTool"
+ )
diff --git a/tests/core/tools/core/test_brave_web_search.py b/tests/core/tools/core/test_brave_web_search.py
new file mode 100644
index 000000000..77d2c7788
--- /dev/null
+++ b/tests/core/tools/core/test_brave_web_search.py
@@ -0,0 +1,290 @@
+"""Tests for BraveWebSearchCore. All HTTP goes through httpx.MockTransport."""
+
+import json
+import logging
+import traceback
+from typing import Any, Callable
+
+import httpx
+import pytest
+
+from xagent.core.tools.core import brave_web_search as mod
+from xagent.core.tools.core.brave_web_search import BraveWebSearchCore
+
+API_KEY = "test-brave-key-0000"
+QUERY = "[email protected] quarterly forecast"
+
+
[email protected](params=["httpx_warning", "httpx_notset"])
+def httpx_log_level(request):
+ """Run leak tests with httpx's own logger both quiet and fully verbose."""
+ lg = logging.getLogger("httpx")
+ saved = lg.level
+ lg.setLevel(logging.WARNING if request.param == "httpx_warning" else logging.NOTSET)
+ yield request.param
+ lg.setLevel(saved)
+
+
+def transport(monkeypatch):
+ """Route the core's httpx.AsyncClient through a MockTransport."""
+ state: dict[str, Any] = {"requests": [], "handler": None}
+
+ def install(handler: Callable[[httpx.Request], httpx.Response]) -> list:
+ def wrapped(request: httpx.Request) -> httpx.Response:
+ state["requests"].append(request)
+ return handler(request)
+
+ real = httpx.AsyncClient
+
+ def factory(**kwargs: Any) -> httpx.AsyncClient:
+ return real(transport=httpx.MockTransport(wrapped), **kwargs)
+
+ monkeypatch.setattr(mod.httpx, "AsyncClient", factory)
+ return state["requests"]
+
+ return install
+
+
+WEB_BODY = {
+ "web": {
+ "results": [
+ {"title": "T1", "url": "https://a.example/1", "description": "D1"},
+ {"title": "T2", "url": "https://a.example/2", "description": "D2"},
+ ]
+ }
+}
+CTX_BODY = {
+ "grounding": {
+ "generic": [
+ {
+ "url": "https://c.example/1",
+ "title": "C1",
+ "snippets": ["first " + "x" * 600, "second"],
+ },
+ {"url": "https://c.example/2", "title": "C2", "snippets": []},
+ ]
+ },
+ "sources": {},
+}
+
+
+async def test_web_endpoint_request_and_mapping(transport, monkeypatch):
+ monkeypatch.delenv("XAGENT_BRAVE_SEARCH_ENDPOINT", raising=False)
+ requests = transport(lambda r: httpx.Response(200, json=WEB_BODY))
+
+ results = await BraveWebSearchCore(api_key=API_KEY).search(QUERY, max_results=50)
+
+ assert results == [
+ {"title": "T1", "link": "https://a.example/1", "snippet": "D1"},
+ {"title": "T2", "link": "https://a.example/2", "snippet": "D2"},
+ ]
+ (req,) = requests
+ assert req.method == "GET"
+ assert req.url.host == "api.search.brave.com"
+ assert req.url.path == "/res/v1/web/search"
+ assert req.headers["X-Subscription-Token"] == API_KEY
+ assert req.url.params["q"] == QUERY
+ assert req.url.params["count"] == "20"
+ assert req.url.params["text_decorations"] == "false"
+
+
+async def test_web_endpoint_include_content_fetches_pages(transport, monkeypatch):
+ transport(lambda r: httpx.Response(200, json=WEB_BODY))
+ fetched: list[str] = []
+
+ class FakeFetcher:
+ def __init__(self, proxy_url=None):
+ pass
+
+ async def fetch_text(self, url: str) -> str:
+ fetched.append(url)
+ return f"page:{url}"
+
+ monkeypatch.setattr(mod, "WebContentFetcher", FakeFetcher)
+ results = await BraveWebSearchCore(api_key=API_KEY).search(
+ QUERY, include_content=True
+ )
+ assert [r["content"] for r in results] == [
+ "page:https://a.example/1",
+ "page:https://a.example/2",
+ ]
+ assert fetched == ["https://a.example/1", "https://a.example/2"]
+
+
+async def test_llm_context_endpoint_request_and_mapping(transport, monkeypatch):
+ monkeypatch.setenv("XAGENT_BRAVE_SEARCH_ENDPOINT", "llm_context")
+ requests = transport(lambda r: httpx.Response(200, json=CTX_BODY))
+
+ results = await BraveWebSearchCore(api_key=API_KEY).search(
+ QUERY, max_results=3, include_content=True
+ )
+
+ (req,) = requests
+ assert req.method == "POST"
+ assert req.url.path == "/res/v1/llm/context"
+ assert req.url.query == b"" # the query stays out of the URL
+ assert req.headers["X-Subscription-Token"] == API_KEY
+ assert json.loads(req.content) == {
+ "q": QUERY,
+ "count": 3,
+ "maximum_number_of_tokens": 8192,
+ }
+ assert results[0]["title"] == "C1"
+ assert results[0]["link"] == "https://c.example/1"
+ assert results[0]["snippet"] == ("first " + "x" * 600)[:500]
+ assert results[0]["content"] == ("first " + "x" * 600) + "\n\nsecond"
+ assert results[1] == {
+ "title": "C2",
+ "link": "https://c.example/2",
+ "snippet": "",
+ "content": "",
+ }
+
+
+async def test_llm_context_content_is_bounded(transport, monkeypatch):
+ monkeypatch.setenv("XAGENT_BRAVE_SEARCH_ENDPOINT", "llm_context")
+ body = {
+ "grounding": {
+ "generic": [
+ {"url": "https://c.example/1", "title": "C", "snippets": ["y" * 9000]}
+ ]
+ }
+ }
+ transport(lambda r: httpx.Response(200, json=body))
+ (result,) = await BraveWebSearchCore(api_key=API_KEY).search(
+ QUERY, include_content=True
+ )
+ assert len(result["content"]) == 8192
+
+
+async def test_llm_context_without_include_content_has_no_content(
+ transport, monkeypatch
+):
+ monkeypatch.setenv("XAGENT_BRAVE_SEARCH_ENDPOINT", "llm_context")
+ transport(lambda r: httpx.Response(200, json=CTX_BODY))
+ results = await BraveWebSearchCore(api_key=API_KEY).search(QUERY)
+ assert all("content" not in r for r in results)
+
+
+async def test_unknown_endpoint_uses_web(transport, monkeypatch, caplog):
+ monkeypatch.setenv("XAGENT_BRAVE_SEARCH_ENDPOINT", "bogus")
+ requests = transport(lambda r: httpx.Response(200, json=WEB_BODY))
+ with caplog.at_level(logging.WARNING):
+ await BraveWebSearchCore(api_key=API_KEY).search(QUERY)
+ assert requests[0].url.path == "/res/v1/web/search"
+ assert "XAGENT_BRAVE_SEARCH_ENDPOINT" in caplog.text
+
+
[email protected]("endpoint", ["web", "llm_context"])
[email protected]("status", [401, 403])
+async def test_auth_failures(transport, monkeypatch, endpoint, status):
+ monkeypatch.setenv("XAGENT_BRAVE_SEARCH_ENDPOINT", endpoint)
+ transport(lambda r: httpx.Response(status, json={"error": "nope"}))
+ with pytest.raises(ValueError, match=f"auth failed \\({status}\\)"):
+ await BraveWebSearchCore(api_key=API_KEY).search(QUERY)
+
+
[email protected]("endpoint", ["web", "llm_context"])
+async def test_rate_limit(transport, monkeypatch, endpoint):
+ monkeypatch.setenv("XAGENT_BRAVE_SEARCH_ENDPOINT", endpoint)
+ transport(lambda r: httpx.Response(429))
+ with pytest.raises(ValueError, match="rate limit.*\\(429\\)"):
+ await BraveWebSearchCore(api_key=API_KEY).search(QUERY)
+
+
+async def test_missing_key_raises(monkeypatch):
+ monkeypatch.delenv("BRAVE_SEARCH_API_KEY", raising=False)
+ with pytest.raises(ValueError, match="BRAVE_SEARCH_API_KEY"):
+ await BraveWebSearchCore().search(QUERY)
+
+
+async def test_env_key_fallback(transport, monkeypatch):
+ monkeypatch.setenv("BRAVE_SEARCH_API_KEY", "env-key")
+ requests = transport(lambda r: httpx.Response(200, json=WEB_BODY))
+ await BraveWebSearchCore().search(QUERY)
+ assert requests[0].headers["X-Subscription-Token"] == "env-key"
+
+
[email protected]("endpoint", ["web", "llm_context"])
+async def test_query_limits_raise_without_request(transport, monkeypatch, endpoint):
+ monkeypatch.setenv("XAGENT_BRAVE_SEARCH_ENDPOINT", endpoint)
+ requests = transport(lambda r: httpx.Response(200, json=WEB_BODY))
+ core = BraveWebSearchCore(api_key=API_KEY)
+
+ with pytest.raises(ValueError, match="600 characters"):
+ await core.search("a" * 601)
+ with pytest.raises(ValueError, match="75 words"):
+ await core.search(" ".join(["w"] * 76))
+ assert requests == []
+
+ # Exactly at the limits is accepted.
+ await core.search("a" * 600)
+ await core.search(" ".join(["w"] * 75))
+ assert len(requests) == 2
+
+
[email protected]("endpoint", ["web", "llm_context"])
[email protected]("status", [400, 429, 500])
[email protected]("failure", ["status", "network"])
+async def test_errors_never_leak_key_url_or_query(
+ transport, monkeypatch, caplog, httpx_log_level, endpoint, status, failure
+):
+ monkeypatch.setenv("XAGENT_BRAVE_SEARCH_ENDPOINT", endpoint)
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ if failure == "network":
+ # httpx puts the request in the exception; its text carries the URL.
+ raise httpx.ConnectError(f"connect failed for {request.url}")
+ return httpx.Response(status, text=f"echo {request.url} {API_KEY}")
+
+ transport(handler)
+ with caplog.at_level(logging.DEBUG):
+ with pytest.raises(ValueError) as exc_info:
+ await BraveWebSearchCore(api_key=API_KEY).search(QUERY)
+
+ err = exc_info.value
+ rendered = "".join(traceback.format_exception(err))
+ logged = caplog.text + "".join(r.getMessage() for r in caplog.records)
+ for text in (str(err), rendered, logged):
+ assert API_KEY not in text
+ assert "api.search.brave.com" not in text
+ assert "forecast" not in text
+ assert "jane.doe" not in text
+ assert "jane.doe%40example.com" not in text
+ assert err.__cause__ is None
+ assert err.__context__ is None or err.__suppress_context__
+ if failure == "status" and status not in {429}:
+ assert str(status) in str(err)
+
+
+async def test_success_does_not_log_query(
+ transport, monkeypatch, caplog, httpx_log_level
+):
+ monkeypatch.delenv("XAGENT_BRAVE_SEARCH_ENDPOINT", raising=False)
+ transport(lambda r: httpx.Response(200, json=WEB_BODY))
+ with caplog.at_level(logging.DEBUG):
+ await BraveWebSearchCore(api_key=API_KEY).search(QUERY)
+ assert "forecast" not in caplog.text
+ assert "jane.doe" not in caplog.text
+ assert API_KEY not in caplog.text
+
+
+async def test_non_json_body_raises_clean_error(transport):
+ transport(lambda r: httpx.Response(200, text="<html>"))
+ with pytest.raises(ValueError, match="invalid response body"):
+ await BraveWebSearchCore(api_key=API_KEY).search(QUERY)
diff --git a/tests/core/tools/test_web_tool_categories.py b/tests/core/tools/test_web_tool_categories.py
index 755105009..48b0f38f2 100644
--- a/tests/core/tools/test_web_tool_categories.py
+++ b/tests/core/tools/test_web_tool_categories.py
@@ -3,6 +3,7 @@
from pathlib import Path
from xagent.core.tools.adapters.vibe.base import ToolCategory
+from xagent.core.tools.adapters.vibe.brave_web_search import BraveWebSearchTool
from xagent.core.tools.adapters.vibe.download_web_asset import DownloadWebAssetTool
from xagent.core.tools.adapters.vibe.exa_web_search import ExaWebSearchTool
from xagent.core.tools.adapters.vibe.fetch_web_content import FetchWebContentTool
@@ -17,6 +18,7 @@ def test_web_research_tools_share_web_search_category(tmp_path: Path) -> None:
tools = [
WebSearchTool(),
TavilyWebSearchTool(),
+ BraveWebSearchTool(),
ExaWebSearchTool(),
ZhipuWebSearchTool(),
FetchWebContentTool(),