feat(websearch): 新增Exa搜索提供商，支持 Tavily/Exa API Base URL 可配置，补充搜索工具相关文档

astrbot/core/astr_agent_hooks.py

@@ -9,6 +9,7 @@
 from astrbot.core.astr_agent_context import AstrAgentContext
 from astrbot.core.pipeline.context_utils import call_event_hook
 from astrbot.core.star.star_handler import EventType
+from astrbot.core.utils.web_search_utils import WEB_SEARCH_REFERENCE_TOOLS
 
 
 class MainAgentHooks(BaseAgentRunHooks[AstrAgentContext]):
@@ -74,13 +75,7 @@ async def on_tool_end(
         platform_name = run_context.context.event.get_platform_name()
         if (
             platform_name == "webchat"
-            and tool.name
-            in [
-                "web_search_baidu",
-                "web_search_tavily",
-                "web_search_bocha",
-                "web_search_brave",
-            ]
+            and tool.name in WEB_SEARCH_REFERENCE_TOOLS
             and len(run_context.messages) > 0
             and tool_result
             and len(tool_result.content)

astrbot/core/astr_main_agent.py

@@ -85,6 +85,9 @@
     BaiduWebSearchTool,
     BochaWebSearchTool,
     BraveWebSearchTool,
+    ExaExtractWebPageTool,
+    ExaFindSimilarTool,
+    ExaWebSearchTool,
     FirecrawlExtractWebPageTool,
     FirecrawlWebSearchTool,
     TavilyExtractWebPageTool,
@@ -1116,6 +1119,10 @@ async def _apply_web_search_tools(
         req.func_tool.add_tool(tool_mgr.get_builtin_tool(FirecrawlExtractWebPageTool))
     elif provider == "baidu_ai_search":
         req.func_tool.add_tool(tool_mgr.get_builtin_tool(BaiduWebSearchTool))
+    elif provider == "exa":
+        req.func_tool.add_tool(tool_mgr.get_builtin_tool(ExaWebSearchTool))
+        req.func_tool.add_tool(tool_mgr.get_builtin_tool(ExaExtractWebPageTool))
+        req.func_tool.add_tool(tool_mgr.get_builtin_tool(ExaFindSimilarTool))
 
 
 def _get_compress_provider(

astrbot/core/config/default.py

@@ -108,9 +108,12 @@
         "web_search": False,
         "websearch_provider": "tavily",
         "websearch_tavily_key": [],
+        "websearch_tavily_base_url": "https://api.tavily.com",
         "websearch_bocha_key": [],
         "websearch_brave_key": [],
         "websearch_baidu_app_builder_key": "",
+        "websearch_exa_key": [],
+        "websearch_exa_base_url": "https://api.exa.ai",
         "web_search_link": False,
         "display_reasoning_text": False,
         "identifier": False,
@@ -3190,6 +3193,7 @@
                             "baidu_ai_search",
                             "bocha",
                             "brave",
+                            "exa",
                             "firecrawl",
                         ],
                         "condition": {
@@ -3244,6 +3248,34 @@
                             "provider_settings.websearch_provider": "baidu_ai_search",
                         },
                     },
+                    "provider_settings.websearch_tavily_base_url": {
+                        "description": "Tavily API Base URL",
+                        "type": "string",
+                        "hint": "默认为 https://api.tavily.com，可改为代理地址。",
+                        "condition": {
+                            "provider_settings.websearch_provider": "tavily",
+                            "provider_settings.web_search": True,
+                        },
+                    },
+                    "provider_settings.websearch_exa_key": {
+                        "description": "Exa API Key",
+                        "type": "list",
+                        "items": {"type": "string"},
+                        "hint": "可添加多个 Key 进行轮询。",
+                        "condition": {
+                            "provider_settings.websearch_provider": "exa",
+                            "provider_settings.web_search": True,
+                        },
+                    },
+                    "provider_settings.websearch_exa_base_url": {
+                        "description": "Exa API Base URL",
+                        "type": "string",
+                        "hint": "默认为 https://api.exa.ai，可改为代理地址。",
+                        "condition": {
+                            "provider_settings.websearch_provider": "exa",
+                            "provider_settings.web_search": True,
+                        },
+                    },
                     "provider_settings.web_search_link": {
                         "description": "显示来源引用",
                         "type": "bool",

astrbot/core/knowledge_base/kb_helper.py

@@ -613,12 +613,18 @@ async def upload_from_url(
                 "Error: Tavily API key is not configured in provider_settings."
             )
 
+        tavily_base_url = config.get("provider_settings", {}).get(
+            "websearch_tavily_base_url", "https://api.tavily.com"
+        )
+
         # 阶段1: 从 URL 提取内容
         if progress_callback:
             await progress_callback("extracting", 0, 100)
 
         try:
-            text_content = await extract_text_from_url(url, tavily_keys)
+            text_content = await extract_text_from_url(
+                url, tavily_keys, tavily_base_url
+            )
         except Exception as e:
             logger.error(f"Failed to extract content from URL {url}: {e}")
             raise OSError(f"Failed to extract content from URL {url}: {e}") from e

astrbot/core/knowledge_base/parsers/url_parser.py

@@ -2,23 +2,34 @@
 
 import aiohttp
 
+from astrbot.core.utils.web_search_utils import normalize_web_search_base_url
+
 
 class URLExtractor:
     """URL 内容提取器，封装了 Tavily API 调用和密钥管理"""
 
-    def __init__(self, tavily_keys: list[str]) -> None:
+    def __init__(
+        self, tavily_keys: list[str], tavily_base_url: str = "https://api.tavily.com"
+    ) -> None:
         """
         初始化 URL 提取器
 
         Args:
             tavily_keys: Tavily API 密钥列表
+            tavily_base_url: Tavily API 基础 URL
         """
         if not tavily_keys:
             raise ValueError("Error: Tavily API keys are not configured.")
 
         self.tavily_keys = tavily_keys
         self.tavily_key_index = 0
         self.tavily_key_lock = asyncio.Lock()
+        self.tavily_base_url = normalize_web_search_base_url(
+            tavily_base_url,
+            default="https://api.tavily.com",
+            provider_name="Tavily",
+            disallowed_path_suffixes=("search", "extract"),
+        )
 
     async def _get_tavily_key(self) -> str:
         """并发安全的从列表中获取并轮换Tavily API密钥。"""
@@ -47,7 +58,7 @@ async def extract_text_from_url(self, url: str) -> str:
             raise ValueError("Error: url must be a non-empty string.")
 
         tavily_key = await self._get_tavily_key()
-        api_url = "https://api.tavily.com/extract"
+        api_url = f"{self.tavily_base_url}/extract"
         headers = {
             "Authorization": f"Bearer {tavily_key}",
             "Content-Type": "application/json",
@@ -69,7 +80,10 @@ async def extract_text_from_url(self, url: str) -> str:
                     if response.status != 200:
                         reason = await response.text()
                         raise OSError(
-                            f"Tavily web extraction failed: {reason}, status: {response.status}"
+                            f"Tavily web extraction failed for URL {api_url}: "
+                            f"{reason}, status: {response.status}. If you configured "
+                            "a Tavily API Base URL, make sure it is a base URL or "
+                            "proxy prefix rather than a specific endpoint path."
                         )
 
                     data = await response.json()
@@ -88,16 +102,19 @@ async def extract_text_from_url(self, url: str) -> str:
 
 
 # 为了向后兼容，提供一个简单的函数接口
-async def extract_text_from_url(url: str, tavily_keys: list[str]) -> str:
+async def extract_text_from_url(
+    url: str, tavily_keys: list[str], tavily_base_url: str = "https://api.tavily.com"
+) -> str:
     """
     简单的函数接口，用于从 URL 提取文本内容
 
     Args:
         url: 要提取内容的网页 URL
         tavily_keys: Tavily API 密钥列表
+        tavily_base_url: Tavily API 基础 URL
 
     Returns:
         提取的文本内容
     """
-    extractor = URLExtractor(tavily_keys)
+    extractor = URLExtractor(tavily_keys, tavily_base_url)
     return await extractor.extract_text_from_url(url)