Advisor

Advisor 是方舟 Managed Agents 提供的进阶能力，属于 evolution（演进工具）下的核心能力之一，也是「Agent 自我进化」能力的重要组成部分。开启后，当 Agent 在执行任务过程中多次执行失败、遇到当前模型无法处理的问题时，会自动唤起更强的顾问模型提供指导，帮助 Agent 突破能力边界、提升复杂任务的完成质量。

本文介绍如何为 Agent 开启和使用 Advisor。

Advisor 配置说明#

Advisor 是 evolution 工具集中的一个子工具，通过 Agent 的 tools 字段配置。

配置结构如下：

1
2
3
4
5
6
7
8
9
10
11
12
13{
  "tools": [
    {
      "type": "evolution",
      "configs": [
        {
          "name": "advisor",
          "enabled": true
        }
      ]
    }
  ]
}

准备工作#

开始前你需要：

• 已创建的 API Key：配置为环境变量 ARK_API_KEY，详情请参见 API Key 管理。
• 已创建的 Agent：详情请参见 定义 Agent。
• 已创建的 Environment：详情请参见 配置云环境。

本章节示例的 Base URL 与鉴权方式详情请参见 Base URL 及鉴权。

开启 Advisor#

控制台方式#

1. 进入 Agent 管理页面。
2. 点击「创建 Agent」，或在已有 Agent 卡片上点击「编辑」。
3. 在「05 高级参数」区域，找到「Advisor」开关，打开即可。
4. 点击「保存」。

开启后，该 Agent 的所有新 Session 都会自动启用 Advisor 能力。

API 方式#

创建或更新 Agent 时，在 tools 中挂载 evolution 类型并配置 advisor 即可开启。

创建时开启#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24curl https://ark.cn-beijing.volces.com/api/v3/agents \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-advisor-agent",
    "model": {
      "id": "doubao-seed-2-1-pro-260628"
    },
    "system": "你是一个资深的代码工程师，负责处理复杂的编码和故障排查任务。",
    "tools": [
      {
        "type": "agent_toolset_20260916"
      },
      {
        "type": "evolution",
        "configs": [
          {
            "name": "advisor",
            "enabled": true
          }
        ]
      }
    ]
  }'

示例响应如下：

{
  "id": "agent-20260702070355-xxxxx",
  "type": "agent",
  "name": "my-advisor-agent",
  "version": 1,
  "model": {
    "id": "doubao-seed-2-1-pro-260628",
    "speed": "standard"
  },
  "tools": [
    {
      "type": "agent_toolset_20260916",
      "default_config": {
        "enabled": true
      }
    },
    {
      "type": "evolution",
      "configs": [
        {
          "name": "advisor",
          "enabled": true
        }
      ]
    }
  ],
  "created_at": "2026-07-02T07:03:55Z",
  "updated_at": "2026-07-02T07:03:55Z"
}

更新已有 Agent#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21curl https://ark.cn-beijing.volces.com/api/v3/agents/{agent_id} \
  -X POST \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "tools": [
      {
        "type": "agent_toolset_20260916"
      },
      {
        "type": "evolution",
        "configs": [
          {
            "name": "advisor",
            "enabled": true
          }
        ]
      }
    ]
  }'

工作方式#

开启 Advisor 后，Agent 在 Session 中执行任务时，遇到以下情况会自动唤起顾问模型：

• Agent 多次执行失败，无法通过自身能力解决
• 当前模型返回工具调用异常、输出格式错误
• 反复卡在同一问题无法推进
• 系统提示词中引导的关键决策节点

顾问模型会接收完整的任务上下文，给出指导建议后，Agent 继续执行。整个过程无需人工干预。

观察 Advisor 调用#

Advisor 的调用过程可以通过控制台 Debug 模式观测。当前公开的 Session 事件结构中未定义独立的 Advisor 调用事件；通过事件流 API 可以继续观察 Agent 消息、工具调用、状态变化等会话执行过程。

查看方式：

• 控制台 Debug 模式：在 Agent 调试页面切换到 Debug 模式，可直观看到 Advisor 调用的时间点和内容。
• 事件流 API：通过 Session Events 接口获取完整事件流，编程方式处理会话执行事件。

事件流的使用方式详见 Session 事件流。

系统提示词建议#

开启 Advisor 后，建议在系统提示词中明确告知 Agent 何时应该寻求顾问帮助，以获得更好的效果。以下是一段参考模板：

1
2
3
4
5
6
7
8
9你是一个专业的代码工程师。你有一个顾问模型可以提供更高级的架构指导和代码审查。

在以下情况下，请主动寻求顾问的帮助：
1. 在开始编写复杂代码之前，先咨询架构设计方案
2. 当你连续两次尝试同一问题仍未解决时
3. 当你需要在多个技术方案之间做选择时
4. 在任务完成前，进行最终的代码质量审查

对于顾问的建议，请认真考虑并采纳。如果你有充分的理由认为建议不适用，可以坚持自己的方案，但需要在回复中说明原因。

计费说明#

Advisor 调用产生的 Token 费用按顾问模型的价格单独计费，不计入执行模型的用量。具体计费规则请参考方舟 Managed Agents 的 计费说明。

相关文档#