OpenRouter 平台功能

Advisor

4 分钟阅读

Advisor

作为服务端工具，在生成过程中咨询更强的模型

测试版（Beta）

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

openrouter:advisor 服务端工具让模型能在生成过程中咨询能力更强的 Advisor 模型。当你的模型遇到决策点——在确定方案之前、卡住时，或在宣布任务完成之前——会带着 prompt 调用该工具。Advisor 模型进行思考，将其指导作为工具结果返回，你的模型在获知建议后继续作答。

与固定的模型配对不同，Advisor 可以是任意 OpenRouter 模型，并且可以选择作为带有自己工具的子智能体运行（例如 openrouter:web_search）。该工具将 Advisor 模型的回复直接作为工具结果返回——最终答案仍由你的模型撰写。

你可以通过在 tools 数组中加入多个 openrouter:advisor 条目——每个 Advisor 一条——向模型提供若干具名 Advisor 供其选择（见多个 Advisor）。最多只能有一条条目省略 name，作为默认 Advisor。

当你回放对话记录时，每个 Advisor 还会跨请求记住自己先前的咨询（见跨请求记忆），并且该工具可用于 Chat Completions、Responses 和 Anthropic Messages API（见 Anthropic Messages API）。

快速开始

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: '用 Go 实现一个支持优雅关闭的并发工作池。',
      },
    ],
    tools: [
      {
        type: 'openrouter:advisor',
        parameters: { model: '~anthropic/claude-opus-latest' },
      },
    ],
  }),
});

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

选择 Advisor 模型

Advisor 模型按以下优先级解析：

若已设置，使用工具定义上的 parameters.model。
若定义未固定模型，则使用执行方在工具调用中传入的 model 参数。
回退为外层 API 请求中的模型。

这样你既可以预先固定 Advisor 模型（parameters.model），也可以让执行模型按次选择。Advisor 工具本身永远不能作为 Advisor 模型。

模型何时会调用它？

该工具的描述会引导模型在开展实质性工作之前、卡住时，或在宣布任务完成之前咨询 Advisor——而不是为单个模型就能直接解决的琐碎步骤去咨询。若要在每次请求上都强制咨询，设置 tool_choice: "required"（存在多个 Advisor 时，这会强制使用第一条——见多个 Advisor）。

参数

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

{
  "tools": [
    {
      "type": "openrouter:advisor",
      "parameters": {
        "model": "~anthropic/claude-opus-latest",
        "instructions": "你是一名资深工程师。请果断给出建议。",
        "tools": [{ "type": "openrouter:web_search" }],
        "forward_transcript": false
      }
    }
  ]
}

字段	默认值	说明
`name`	无（默认 Advisor）	此 Advisor 的可选名称。模型会为每个具名 Advisor 看到一个工具（外加一条无 `name` 的条目作为默认）。各条目的名称必须唯一。允许字母、数字、空格、下划线和连字符；会去除首尾空白；长度为 1–64 个字符。见多个 Advisor。
`model`	外层请求模型	要咨询的 Advisor 模型（任意 OpenRouter 模型）。见选择 Advisor 模型。
`tools`	无	提供给 Advisor 子智能体的工具。仅支持 OpenRouter 服务端工具（例如 `openrouter:web_search`）；函数工具会以 `400` 被拒绝，因为 Advisor 无法执行它们。Advisor 不得列出自身。
`instructions`	无	Advisor 子智能体的系统指令。
`forward_transcript`	`false`	为 `true` 时，会将完整的父对话转发给 Advisor（若提供了工具调用的 `prompt`，会作为最后一轮用户消息追加）。为 `false` 时，Advisor 只看到 `prompt`。
`stream`	`false`	为 `true` 时，建议会在生成过程中增量流式传输（仅 Responses API）。见流式建议。
`max_tool_calls`	服务提供商默认值	Advisor 子智能体最多可采取的工具调用步数。仅在 Advisor 拥有工具时有意义。范围为 1–25。
`max_completion_tokens`	服务提供商默认值	Advisor 调用的最大输出 Token 数（含推理）。
`reasoning`	服务提供商默认值	转发给 Advisor 调用的推理配置——一个可包含可选 `effort` 和 `max_tokens` 的对象。
`temperature`	服务提供商默认值	转发给 Advisor 调用的采样温度（`0`–`2`）。

工具调用参数

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

参数	说明
`prompt`	模型希望获得建议的内容。除非 `forward_transcript` 为 `true`，否则必填。
`model`	要使用的 Advisor 模型。仅当工具定义未固定 `model` 时才会生效。

多个 Advisor

若要向模型提供多个 Advisor 供其选择，在 tools 数组中加入多个 openrouter:advisor 条目——每个 Advisor 一条。为每个条目指定自己的 name（以及各自的 model、instructions 和其他 Advisor 字段）；模型会为每个具名 Advisor 看到一个独立工具，并调用最适合该任务的那个：

{
  "tools": [
    {
      "type": "openrouter:advisor",
      "parameters": {
        "name": "reviewer",
        "model": "~anthropic/claude-opus-latest",
        "instructions": "你是一名严格的代码审查者。找出缺陷。"
      }
    },
    {
      "type": "openrouter:advisor",
      "parameters": {
        "name": "architect",
        "model": "~openai/gpt-latest",
        "instructions": "你是一名系统架构师。从规模扩展的角度思考。"
      }
    }
  ]
}

Advisor 条目的规则：

最多只能有一条条目省略 name——它会成为默认 Advisor。两条或更多未命名的 Advisor 条目会使请求失败，并返回 400："Only one advisor tool can serve as the default. All other advisor tools must have a name defined."
各条目的名称必须唯一（比较前会去除空白）。重复名称会使请求失败，并返回 400。
名称允许字母、数字、空格、下划线和连字符（例如 "Lead Architect"），会去除首尾空白，且必须为 1–64 个字符。

单个 Advisor 就是一条条目——可以命名，也可以省略 name 以保持为默认。每个 Advisor 的结果会报告它所咨询的模型，因此你可以在响应中区分各个 Advisor。

tool_choice 与具名 Advisor

使用 tool_choice 强制 Advisor（例如 tool_choice: "required"，或选择 openrouter:advisor 工具）会指向第一条 Advisor 条目。目前尚不支持通过 tool_choice 强制某个特定的具名 Advisor。

跨请求记忆

每个 Advisor 都会在对话中跨 API 请求记住自己先前的 prompt → advice 往来。当你发送回放先前记录的后续请求——包含助手消息及其 Advisor 工具调用和结果（按 API 返回的原样）——Advisor 会在新的提示词之前，将其先前咨询回放到自己的上下文中。在一次请求中告诉 Advisor 某个事实，它就能在下一次回忆起来，而无需执行模型再次复述。

这在全部三种 API 上都有效；唯一要求是你回放你收到的 Advisor 往来：

Chat Completions：包含助手消息中的 Advisor tool_calls，以及先前轮次中配对的 role: "tool" 结果消息。
Responses API：在 input 中原样包含先前响应里的 openrouter:advisor 输出项。
Anthropic Messages API：包含助手消息中先前轮次的 Advisor server_tool_use 和 advisor_tool_result 内容块。

记忆是按 Advisor 隔离的：在多 Advisor 设置中，每个 Advisor 只回忆自己先前的往来——「reviewer」Advisor 永远看不到告诉「architect」的内容。回放往来的数量没有固定上限；若历史超出 Advisor 模型的上下文窗口，会使用中间向外变换（middle-out transform）压缩，它会裁剪对话中部，并保留最早和最新的往来。

记忆适用于提示词模式的咨询。当 forward_transcript: true 时，Advisor 已经能看到完整的父对话，因此不会单独回放先前往来。

保持 Advisor 条目顺序稳定

Advisor 身份是按位置确定的——来自该条目在请求 tools 数组中的索引。在同一段对话的各次请求中保持 Advisor 条目顺序稳定（并在回放的 Responses 项上原样回传 instance_name 字段）。在请求之间重排或插入 Advisor 条目会改变身份，导致每个 Advisor 重建他人的记忆。

流式建议

默认情况下，建议仅在 Advisor 完成后一次性作为工具结果到达。将 parameters.stream 设为 true，即可在 Advisor 模型生成时增量流出建议：

{
  "tools": [
    {
      "type": "openrouter:advisor",
      "parameters": {
        "model": "~anthropic/claude-opus-latest",
        "stream": true
      }
    }
  ]
}

在 Responses API 中，Advisor 的输出项随后会在建议生成时发出 response.output_text.delta 事件，接着是 response.output_text.done 和已完成的项。已完成的项仍携带完整的 advice 字符串，因此不读取增量的消费者不受影响。stream 可以按 Advisor 条目分别设置，因此你可以对部分 Advisor 启用流式传输，而对其他 Advisor 不启用。

流式增量的方式与普通助手消息流式传输文本相同——每个增量上的 item_id 就是 Advisor 输出项的 id。

流式传输对 Chat Completions API 没有效果（无论 stream 如何，建议都只作为最终工具结果到达）。在 Anthropic Messages API 中流式传输建议是计划中的快速跟进功能；目前 Messages 请求的行为等同于 stream 为 false。

工具返回什么

成功时，工具结果包含建议文本以及生成它的模型：

{
  "status": "ok",
  "model": "anthropic/claude-opus-4.8",
  "advice": "使用基于通道的协调模式。先关闭输入通道，再等待 WaitGroup 排空进行中的工作，然后关闭..."
}

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

{
  "status": "error",
  "error": "Advisor call failed: ..."
}

Anthropic Messages API

在 /api/v1/messages 上，使用 Anthropic 原生工具形态请求 Advisor——并且它适用于任意执行模型，而不仅限于 Anthropic 模型：

{
  "model": "anthropic/claude-haiku-4.5",
  "max_tokens": 1024,
  "messages": [
    { "role": "user", "content": "用 Go 实现一个支持优雅关闭的并发工作池。" }
  ],
  "tools": [
    {
      "type": "advisor_20260301",
      "name": "advisor",
      "model": "~anthropic/claude-opus-latest"
    }
  ]
}

响应以官方 Anthropic 块形态携带 Advisor 咨询——一次调用对应 name: "advisor" 的 server_tool_use 块，随后是带有建议的 advisor_tool_result 块：

{
  "content": [
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01abc",
      "name": "advisor",
      "input": { "prompt": "..." }
    },
    {
      "type": "advisor_tool_result",
      "tool_use_id": "srvtoolu_01abc",
      "content": { "type": "advisor_result", "text": "使用基于通道的协调模式..." }
    },
    { "type": "text", "text": "..." }
  ]
}

在后续请求的助手消息上原样回放这些块，即可启用跨请求记忆。

关于原生形态的说明：

model 是原生形态携带的唯一 Advisor 配置。对于 instructions、子智能体 tools、forward_transcript 以及其他参数，请在 Chat Completions 或 Responses 上使用 openrouter:advisor 形态。
max_uses 不会被遵守：每次请求的咨询次数由 OpenRouter 的固定上限封顶，低于该上限的 max_uses 不会进一步降低它。caching、allowed_callers 和 defer_loading 也会被忽略。
通过 tool_choice: { "type": "tool", "name": "advisor" } 强制 Advisor 是支持的。

子智能体工具

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

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

递归保护

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

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

每次请求的咨询次数也会设上限，以控制费用和延迟。

上一页Fusion 下一页 Subagent

Advisor

快速开始

选择 Advisor 模型

模型何时会调用它？

参数

工具调用参数

多个 Advisor

跨请求记忆

流式建议

工具返回什么

Anthropic Messages API

子智能体工具

递归保护

相关内容