注册服务商托管的工具

服务端工具运行在模型提供商内部，不像普通的 AgentTool那样由 Agent 循环执行。想开放哪一项托管能力，就安装对应的提供商专属扩展:

from zett_agent.extensions.server_tools.google import GoogleServerToolExtension
from zett_agent.client import create_agent
from zett_agent.model import ServerToolDefinition

client = await create_agent(
    model,
    extensions=[
        GoogleServerToolExtension([
            "google_search",
            "url_context",
        ]),
    ],
)

每个扩展都会在 on_tool 期间调用 register_server_tool()。由此得到的定义作用域限于本次请求，并会传递到其后每一个 before-model 钩子以及最终的 ModelRequest。它们永远不会进入 Agent 的本地工具执行器。

选择与端点匹配的扩展

内置声明

扩展	默认类型	传输要求
GoogleServerToolExtension	google_search + url_context	Gemini GenerateContent；由 GoogleProvider 支持。
AnthropicServerToolExtension	web_search_20260318 + web_fetch_20260318	Anthropic Messages；由 AnthropicProvider 支持。
OpenRouterServerToolExtension	openrouter:web_search + openrouter:web_fetch	兼容 OpenRouter 的 Chat Completions 端点。
OpenAIServerToolExtension	web_search	OpenAI Responses API；而非 OpenAI Chat Completions。
DeepSeekServerToolExtension	web_search	DeepSeek Responses API；而非旧版的 Chat Completions。

OpenAIProvider 和 DeepSeekProvider 默认使用 Chat Completions。用 response=True构造任一适配器，即可改用它的 Responses 端点，并显式启用其托管工具:

model = OpenAIProvider(
    model="gpt-5",
    api_key=os.environ["OPENAI_API_KEY"],
    response=True,
)

Responses 适配器在每次请求时都会发送完整的历史记录。它会保留模型提供商的输出项，供之后的函数结果轮次使用，并把托管工具的启动/完成记录映射到通用的服务端工具事件生命周期中。可用的工具类型仍取决于所选的提供商端点与模型。

OpenAI 和 DeepSeek 没有单独发布 web_fetch类型。它们托管的网页搜索工作流会自行抓取相关页面。默认值有意使用官方文档中的类型，而不是发送一个自造的 fetch 区分标识。

允许协议演进

工具类型是开放的字符串，配置则是不透明的映射。因此新的提供商版本不需要更新 zett-agent 的枚举:

extension = AnthropicServerToolExtension(
    [
        ServerToolDefinition(
            "web_fetch_20260318",
            {
                "name": "web_fetch",
                "max_uses": 3,
                "allowed_domains": ["docs.python.org"],
            },
        ),
        ServerToolDefinition("code_execution_20260521"),
    ],
)

模型兼容性和字段校验仍由提供商负责。同一次请求中出现重复的类型时，会在网络 I/O 之前就被拒绝，否则它们的顺序会让当前生效的配置变得有歧义。

当所有工具都不需要配置时，直接传入它们的类型字符串:

extension = GoogleServerToolExtension([
    "google_search",
    "url_context",
    "code_execution",
])