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.tsxindex 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.pyindex 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 variable2. "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.pyindex 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 -> nonezhipu_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 WebSearchTooltools.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 FetchWebContentTooldiff --git a/src/xagent/core/tools/adapters/vibe/brave_web_search.py b/src/xagent/core/tools/adapters/vibe/brave_web_search.pynew file mode 100644index 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.pyindex 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.valueif 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.pynew file mode 100644index 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_proxydiff --git a/src/xagent/web/init_tool_configs.py b/src/xagent/web/init_tool_configs.pyindex 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.pyindex 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.pyindex 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.pyindex 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 namesassert "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.pynew file mode 100644index 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.pyindex 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 Pathfrom xagent.core.tools.adapters.vibe.base import ToolCategory+from xagent.core.tools.adapters.vibe.brave_web_search import BraveWebSearchToolfrom xagent.core.tools.adapters.vibe.download_web_asset import DownloadWebAssetToolfrom xagent.core.tools.adapters.vibe.exa_web_search import ExaWebSearchToolfrom 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(),