构建 Web 搜索提供商插件

Web 搜索提供商插件注册一个后端，用于处理 web_search、web_extract 以及（可选的）深度爬取工具调用。内置提供商——Firecrawl、SearXNG、Tavily、Exa、Parallel、Brave Search（免费层）、xAI 和 DDGS——均作为插件位于 plugins/web/<name>/ 下。你可以通过在它们旁边放置一个目录来添加新的提供商，或覆盖 bundled 的提供商。

提示

Web 搜索是 Hermes 支持的几种后端插件之一。其他插件（拥有各自的抽象基类 ABC）包括图像生成提供商插件、视频生成提供商插件、记忆提供商插件、上下文引擎插件和模型提供商插件。通用的工具/hook/CLI 插件请参阅构建 Hermes 插件。

发现机制的工作原理

Hermes 会在以下三个位置扫描 Web 搜索后端：

Bundled（内置） — <repo>/plugins/web/<name>/（随 kind: backend 自动加载，始终可用）
User（用户） — ~/.hermes/plugins/web/<name>/（通过 plugins.enabled 或 hermes plugins enable <name> 选择启用）
Pip — 声明了 hermes_agent.plugins 入口点的包

每个插件的 register(ctx) 函数都会调用 ctx.register_web_search_provider(...)——这会将实例放入 agent/web_search_registry.py 中的注册表。每种能力的活动提供商由配置决定：

能力	配置键	回退至
`web_search`	`web.search_backend`	`web.backend`
`web_extract`	`web.extract_backend`	`web.backend`
`web_extract` 内的深度爬取模式	`web.extract_backend`	`web.backend`

当两个键均未设置时，Hermes 会根据环境中存在的 API 密钥/URL 自动检测后端。hermes tools 会引导用户进行选择。

目录结构

plugins/web/my-backend/
├── __init__.py     # register() entry point
├── provider.py     # WebSearchProvider subclass
└── plugin.yaml     # Manifest with kind: backend and provides_web_providers

brave_free/ 和 ddgs/ 是代码库中最小的参考示例——brave_free 是一个需要 API 密钥且仅支持搜索的提供商，ddgs 是一个无需密钥且会懒安装其 SDK 的提供商。

WebSearchProvider 抽象基类 (ABC)

继承 agent.web_search_provider.WebSearchProvider。唯一必需的成员是 name、is_available()，以及你实现的 search() 或 extract() 中的任意一个。（深度爬取不是一个单独的方法——它是 extract() 的一种模式。）

# plugins/web/my-backend/provider.py
from __future__ import annotations

import os
from typing import Any, Dict, List

from agent.web_search_provider import WebSearchProvider


class MyBackendWebSearchProvider(WebSearchProvider):
    """Minimal search-only provider against the My Backend HTTP API."""

    @property
    def name(self) -> str:
        # Stable id used in web.search_backend / web.extract_backend / web.backend
        # config keys. Lowercase, no spaces; hyphens permitted.
        return "my-backend"

    @property
    def display_name(self) -> str:
        # Human label shown in `hermes tools`. Defaults to `name`.
        return "My Backend"

    def is_available(self) -> bool:
        # Cheap check — env var present, optional dep importable, etc.
        # MUST NOT make network calls (runs on every `hermes tools` paint).
        return bool(os.getenv("MY_BACKEND_API_KEY", "").strip())

    def supports_search(self) -> bool:
        return True

    def supports_extract(self) -> bool:
        return False

    def search(self, query: str, limit: int = 5) -> Dict[str, Any]:
        import httpx

        api_key = os.environ["MY_BACKEND_API_KEY"]
        try:
            resp = httpx.get(
                "https://api.example.com/search",
                params={"q": query, "count": max(1, min(int(limit), 20))},
                headers={"Authorization": f"Bearer {api_key}"},
                timeout=15,
            )
            resp.raise_for_status()
            data = resp.json()
        except httpx.HTTPError as exc:
            return {"success": False, "error": str(exc)}

        # Response shape is fixed — see "Response shape" below.
        return {
            "success": True,
            "data": {
                "web": [
                    {
                        "title": item.get("title", ""),
                        "url": item.get("url", ""),
                        "description": item.get("snippet", ""),
                        "position": idx + 1,
                    }
                    for idx, item in enumerate(data.get("results", []))
                ],
            },
        }

# plugins/web/my-backend/__init__.py
from plugins.web.my_backend.provider import MyBackendWebSearchProvider


def register(ctx) -> None:
    """Plugin entry point — called once at load time."""
    ctx.register_web_search_provider(MyBackendWebSearchProvider())

plugin.yaml

name: web-my-backend
version: 1.0.0
description: "My Backend web search — Bearer-auth REST API"
author: Your Name
kind: backend
provides_web_providers:
  - my-backend
requires_env:
  - MY_BACKEND_API_KEY

键	用途
`kind: backend`	将插件路由到后端加载路径
`provides_web_providers`	此插件注册的提供商 `name` 列表——加载器使用它在 `register()` 运行之前在 `hermes tools` 中宣传该插件
`requires_env`	在 `hermes plugins install` 期间交互式提示凭证（参见构建 Hermes 插件了解丰富格式）

ABC 参考

完整契约位于 agent/web_search_provider.py。你可以重写的方法：

成员	必需	默认值	用途
`name`	✅	—	在 `web.*_backend` 配置中使用的稳定 ID
`display_name`	—	`name`	在 `hermes tools` 中显示的标签
`is_available()`	✅	—	轻量级的可用性检查——环境变量、可选依赖
`supports_search()`	—	`True`	`web_search` 路由的能力标志
`supports_extract()`	—	`False`	`web_extract` 路由的能力标志
`search(query, limit)`	条件性	抛出异常	当 `supports_search()` 返回 `True` 时为必需
`extract(urls, **kwargs)`	条件性	抛出异常	当 `supports_extract()` 返回 `True` 时为必需

提供商可以从单个类中宣传多种能力——Firecrawl、Tavily、Exa 和 Parallel 都同时实现了搜索和提取。Brave Search 和 DDGS 仅支持搜索；SearXNG 仅支持搜索，并有文档记录的“与提取提供商配对”工作流。

响应结构

工具包装器期望一个固定的信封结构，以便无需在后端之间进行转换。

搜索成功：

{
    "success": True,
    "data": {
        "web": [
            {"title": str, "url": str, "description": str, "position": int},
            ...
        ],
    },
}

提取成功：

{
    "success": True,
    "data": [
        {
            "url": str,
            "title": str,
            "content": str,
            "raw_content": str,
            "metadata": dict,    # optional
            "error": str,        # optional, only on per-URL failure
        },
        ...
    ],
}

任一能力，失败时：

{"success": False, "error": "human-readable message"}

search() 和 extract() 都可以是 async def——调度程序通过 inspect.iscoroutinefunction 检测协程函数并相应地 await。执行阻塞 I/O（HTTP、SDK 调用）的同步实现对于小型后端来说是可以接受的；调度程序会处理线程问题。

能力标志

Hermes 根据 supports_* 标志将调用路由到正确的提供商。常见的多提供商设置：

# ~/.hermes/config.yaml
web:
  search_backend: "brave-free"     # search-only, fast, free 2k/mo
  extract_backend: "firecrawl"     # extract + crawl, paid quota

当未设置 web.search_backend 或 web.extract_backend 时，两者都会回退到 web.backend。当后者也未设置时，Hermes 会根据环境变量的存在情况，选择第一个支持所请求能力的可用提供商。

如果你的提供商仅支持一种能力，请将其他标志保留为默认值（False），注册表将针对该工具跳过这些能力——当用户仅使用 X 进行搜索并要求代理执行提取时，不会看到误导性的“provider X failed”错误。

Hermes 如何将其接入工具

web_search 和 web_extract 工具位于 tools/web_tools.py 中。在调用时，它们会：

读取相关的配置键（web_search 对应 web.search_backend，web_extract 对应 web.extract_backend）
向注册表请求具有该 name 的提供商
检查 is_available() 和匹配的 supports_*() 标志
分派到 search() / extract()（深度爬取作为 extract() 内部的一种模式运行），如果方法是协程则进行 await
对响应信封进行 JSON 序列化并将其返回给 LLM

错误会作为工具结果呈现；由 LLM 决定如何解释这些错误。如果没有注册提供商（或者所有可用的提供商都未通过能力检查），工具将返回一个指向 hermes tools 的帮助性错误。

懒安装可选依赖项

如果你的提供商封装了第三方 SDK（例如 DDGS 使用 ddgs 包），不要在模块顶层 import 它。请在 is_available() 或 search() 中使用 tools.lazy_deps.ensure(...) —— Hermes 将在首次使用时安装该包，并受 security.allow_lazy_installs 控制。有关安全模型，请参阅构建 Hermes 插件 → 懒安装。

参考实现

plugins/web/brave_free/ — 小型、需 API 密钥、仅支持搜索的 HTTP 提供商。良好的起始模板。
plugins/web/ddgs/ — 无需密钥且懒安装其 SDK 的提供商。对于封装 Python 包的后端而言，这是一种有用的模式。
plugins/web/firecrawl/ — 功能完整的多能力提供商（搜索 + 提取 + 爬取），支持多种格式模式。
plugins/web/searxng/ — 自托管、通过 URL 配置且无需认证的后端。
plugins/web/xai/ — 通过 Grok 的服务端 web_search 工具实现的基于 LLM 的搜索。展示了如何复用现有的 OAuth/环境变量凭据表面（tools/xai_http.py）而无需添加新的环境变量，以及如何编写遵守无网络契约的低成本 is_available()。

通过 pip 分发

# pyproject.toml
[project.entry-points."hermes_agent.plugins"]
my-backend-web = "my_backend_web_package"

my_backend_web_package 必须暴露一个顶层的 register 函数。完整设置请参阅通用插件指南中的通过 pip 分发。

网页搜索 — 面向用户的功能文档和各后端配置
插件概览 — 所有插件类型一览
构建 Hermes 插件 — 通用工具/hooks/斜杠命令指南

发现机制的工作原理​

目录结构​

WebSearchProvider 抽象基类 (ABC)​

plugin.yaml​

ABC 参考​

响应结构​

能力标志​

Hermes 如何将其接入工具​

懒安装可选依赖项​

参考实现​

通过 pip 分发​

相关页面​