hermes教程-Web 搜索提供者插件

plugins/web/my-backend/
├── __init__.py     # register() 入口点
├── provider.py     # WebSearchProvider 子类
└── plugin.yaml     # 清单，包含 kind: backend 和 provides_web_providers

## 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):
    """针对 My Backend HTTP API 的最小化仅搜索提供者。"""

    @property
    def name(self) -> str:
## 用于 web.search_backend / web.extract_backend / web.backend
## 配置键的稳定 ID。小写，无空格；允许连字符。
        return "my-backend"

    @property
    def display_name(self) -> str:
## 在 `hermes tools` 中显示的人类可读标签。默认为 `name`。
        return "My Backend"

    def is_available(self) -> bool:
## 廉价检查——环境变量存在，可选依赖可导入等。
## 不得进行网络调用（每次 `hermes tools` 渲染时运行）。
        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)}
## 响应形状是固定的——请参阅下面的“响应形状”。
        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:
    """插件入口点——在加载时调用一次。"""
    ctx.register_web_search_provider(MyBackendWebSearchProvider())

name: web-my-backend
version: 1.0.0
description: "My Backend 网络搜索——Bearer 认证 REST API"
author: Your Name
kind: backend
provides_web_providers:
  - my-backend
requires_env:
  - MY_BACKEND_API_KEY

{
    "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,    # 可选
            "error": str,        # 可选，仅在单个 URL 失败时出现
        },
        ...
    ],
}

{"success": False, "error": "人类可读的消息"}

## ~/.hermes/config.yaml
web:
  search_backend: "brave-free"     # 仅搜索，快速，免费 2k/月
  extract_backend: "firecrawl"     # 提取 + 爬取，付费配额

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