服务端工具

由 OpenRouter 运营、模型可在请求期间调用的工具

服务端工具是由 OpenRouter 运营、任何模型都可以在请求期间调用的专用工具。当模型决定使用服务端工具时，OpenRouter 会在服务端执行它并将结果返回给模型，因此无需客户端实现。

服务端工具 vs 插件 vs 用户自定义工具

服务端工具是模型在一次请求中可以调用零次或多次的工具。OpenRouter 透明地处理执行。

插件通过注入或修改请求或响应来添加功能（例如响应修复、PDF 解析）。启用后始终运行一次。

用户自定义工具是标准的函数调用工具：模型建议一次调用，由你的应用执行。

可用的服务端工具

服务端工具如何工作

1. 在 API 请求的 tools 数组中包含一个或多个服务端工具。
2. 模型根据用户的提示词决定是否以及何时调用每个服务端工具。
3. OpenRouter 拦截工具调用，在服务端执行，并将结果返回给模型。
4. 模型利用结果形成响应。如有需要，可能会再次调用该工具。

服务端工具可以与你自己的用户自定义工具一起使用。你可以在同一请求中同时包含二者。

工具调用上限

每个使用服务端工具的请求都会运行带步数预算的智能体循环。模型进行的每次工具调用（一次网页搜索、一次图像生成等）消耗一步；预算耗尽后，模型会被要求基于目前收集到的上下文给出最终答案。

两个顶层请求字段控制外层循环（二者都是 messages 和 tools 的同级字段）：

运行自身内层智能体循环的工具，通过该工具的 parameters 配置独立的按工具预算：

这些内层预算约束每位小组成员、Advisor 或工作者模型自己的工具循环，与外层请求预算相互独立。

快速开始

使用 openrouter: 类型前缀，将服务端工具添加到 tools 数组：

const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <OPENROUTER_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5.2',
    messages: [
      {
        role: 'user',
        content: 'AI 领域最近有哪些进展？'
      }
    ],
    tools: [
      { type: 'openrouter:web_search' },
      { type: 'openrouter:datetime' }
    ]
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

与用户自定义工具组合

服务端工具和用户自定义工具可以在同一请求中使用：

{
  "model": "openai/gpt-5.2",
  "messages": [...],
  "tools": [
    { "type": "openrouter:web_search", "parameters": { "max_results": 3 } },
    { "type": "openrouter:datetime" },
    {
      "type": "function",
      "function": {
        "name": "get_stock_price",
        "description": "获取某股票代码的当前股价",
        "parameters": {
          "type": "object",
          "properties": {
            "ticker": { "type": "string" }
          },
          "required": ["ticker"]
        }
      }
    }
  ]
}

模型可以调用服务端工具和用户自定义工具的任意组合。OpenRouter 自动执行服务端工具，而你的应用像往常一样处理用户自定义工具调用。

用量跟踪

服务端工具用量记录在响应的 usage 对象中：

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 250,
    "server_tool_use": {
      "web_search_requests": 2
    }
  }
}

下一步

• Web 搜索。搜索网络以获取实时信息
• Datetime。获取当前日期和时间
• 图像生成。根据文本提示词生成图像
• Web 获取。从 URL 获取并提取内容
• Apply Patch。通过 V4A diff 提议文件编辑
• Shell。在托管的沙箱 Shell 中运行命令
• Fusion。运行一组模型和一位分析师，进行多模型分析
• Advisor。在生成过程中咨询更强的模型以获取指导
• 子智能体。将自成一体的任务委派给更小、更快的工作者模型
• 搜索模型。搜索并筛选 OpenRouter 模型目录
• 工具调用。了解用户自定义工具调用