OpenRouter 平台功能

Subagent

2 分钟阅读

子智能体（Subagent）

作为服务端工具，将任务委派给更小、更快的模型

测试版（Beta）

服务端工具目前处于测试阶段。API 与行为可能会变更。

openrouter:subagent 服务端工具让模型能在生成过程中，将自成一体的任务委派给更小、更便宜、更快的工作模型。当你的模型有一块不需要其全部能力的工作——总结文档、提取结构化数据、起草样板代码、重新格式化文本——它会带着 task_name 和 task_description 调用该工具。工作模型执行任务，将其结果作为工具的 outcome 返回，你的模型继续作答并整合该结果。

工作模型可以是任意 OpenRouter 模型，并且可以选择作为带有自己工具的子智能体运行（例如 openrouter:web_search）。每项任务都是独立的：工作模型只看到任务描述（看不到父对话），并且在任务之间不保留记忆。

快速开始

Unsupported component: <Template>

const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {{API_KEY_REF}}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: '{{MODEL}}',
    messages: [
      {
        role: 'user',
        content: '审核此次发布：总结更新日志、列出破坏性变更，并起草公告。',
      },
    ],
    tools: [
      {
        type: 'openrouter:subagent',
        parameters: { model: '~anthropic/claude-haiku-latest' },
      },
    ],
  }),
});

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

选择工作模型

工作模型按以下优先级解析：

若已设置，使用工具定义上的 parameters.model。
回退为外层 API 请求中的模型。

与 Advisor 工具不同，委派模型不能按次选择工作模型——工作模型由工具定义固定。子智能体工具本身永远不能作为工作模型。

模型何时会调用它？

该工具的描述会引导模型将不需要其全部能力的聚焦子任务委派出去——并跳过那些直接做比描述出来更快的工作。因为工作模型无法访问父对话，模型会被指示在 task_description 中包含所有相关上下文以及期望的输出格式。

参数

在工具条目上传入可选的 parameters 对象：

{
  "tools": [
    {
      "type": "openrouter:subagent",
      "parameters": {
        "model": "~anthropic/claude-haiku-latest",
        "instructions": "你是一名快速、专注的执行者。严格按照描述完成任务。",
        "tools": [{ "type": "openrouter:web_search" }]
      }
    }
  ]
}

字段	默认值	说明
`model`	外层请求模型	执行被委派任务的工作模型（任意 OpenRouter 模型）。通常比委派模型更小、更便宜、更快。
`tools`	无	提供给工作模型的工具。仅支持 OpenRouter 服务端工具（例如 `openrouter:web_search`）；函数工具会以 `400` 被拒绝，因为工作模型无法执行它们。子智能体不得列出自身。
`instructions`	无	工作模型的系统指令。
`max_tool_calls`	服务提供商默认值	工作模型最多可采取的工具调用步数。仅在工作模型拥有工具时有意义。范围为 1–25。会被接受和校验，但尚未在工作模型调用上强制执行。
`max_completion_tokens`	服务提供商默认值	工作模型调用的最大输出 Token 数（含推理）。
`reasoning`	服务提供商默认值	工作模型调用的推理配置——一个可包含可选 `effort` 和 `max_tokens` 的对象。`effort` 会转发给工作模型；`max_tokens` 会被接受和校验，但尚未转发。
`temperature`	服务提供商默认值	转发给工作模型调用的采样温度（`0`–`2`）。

工具调用参数

调用该工具时，模型会传入：

参数	说明
`task_name`	被委派任务的简短标识符（例如 `summarize-changelog`）。
`task_description`	工作模型完成任务所需的一切：完整上下文、输入、约束以及期望的输出格式。工作模型只看到这段描述。

工具返回什么

成功时，工具结果包含结果文本、任务名称以及生成它的模型：

{
  "status": "ok",
  "model": "anthropic/claude-haiku-4.5",
  "task_name": "summarize-changelog",
  "outcome": "2.4 版本亮点：1) 新的流式 API..."
}

失败时，结果为 status: "error" 并带有消息；调用方模型会在没有该结果的情况下继续：

{
  "status": "error",
  "task_name": "summarize-changelog",
  "error": "Subagent call failed: ..."
}

工作模型工具

当你传入 tools 时，工作模型会在给出结果之前作为具备智能体能力的子智能体在这些工具上运行——例如，给工作模型提供 openrouter:web_search，即可让它根据最新来源得出结果。工作模型的工具使用发生在该工具调用内部；只有其最终文本会返回给你的模型。

嵌套工具必须是 OpenRouter 服务端工具（例如 openrouter:web_search 或 openrouter:web_fetch）。函数工具（{ "type": "function" }）会以 400 被拒绝：工作模型调用没有客户端执行方，因此函数工具调用永远无法被完成。

递归保护

子智能体工具不能调用自身。有两道防护强制这一点：

自引用检查会拒绝子智能体自己的 tools 数组中的子智能体条目（也会拒绝将子智能体工具名称作为工作 model）。
每次内部子智能体调用都会携带 x-openrouter-subagent-depth 请求头；子智能体工具会从任何子调用中剥离，因此工作模型永远无法再次进入子智能体。

每次请求的任务执行次数也会设上限，以控制费用和延迟。

Advisor 服务端工具 — 咨询更强的模型以获取指导
Fusion 服务端工具 — 多模型合议
Web 搜索（Web Search）服务端工具

子智能体（Subagent）

快速开始

选择工作模型

模型何时会调用它？

参数

工具调用参数

工具返回什么

工作模型工具

递归保护

相关内容