# Advisor

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

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

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

> **说明**
>
> 此为邀测能力，如需使用，提交 [测试申请工单](https://console.volcengine.com/auth/login?redirectURI=%2Fworkorder%2Fcreate%3Fstep%3D2%26SubProductID%3DP00001166)。

# Advisor 配置说明

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

配置结构如下：

```json
{
  "tools": [
    {
      "type": "evolution",
      "configs": [
        {
          "name": "advisor",
          "enabled": true
        }
      ]
    }
  ]
}
```

> **说明**
>
> 当前不支持在 `evolution` 工具集上配置 `default_config`，也不支持为 `advisor` 单独配置 `permission_policy`。

字段说明

---

**tools[].type** `string` `必填`

工具类型，固定为 `evolution`。

---

**tools[].configs** `object[]` `必填`

演进工具的子工具配置列表。`tools[].type` 为 `evolution` 时，必须包含 `name` 为 `advisor` 的配置项。

---

configs.**name** `string` `必填`

子工具名称，Advisor 对应值为 `advisor`。

---

configs.**enabled** `boolean` `选填`

是否启用该子工具。默认值：`true`。

# 准备工作

开始前你需要：

- 已创建的 API Key：配置为环境变量 `ARK_API_KEY`，详情请参见 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apiKey)。
- 已创建的 Agent：详情请参见 [定义 Agent](/docs/define-agent)。
- 已创建的 Environment：详情请参见 [配置云环境](/docs/configure-cloud-environment)。

本章节示例的 Base URL 与鉴权方式详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

# 开启 Advisor

## 控制台方式

1. 进入 [Agent 管理页面](https://ark.volcengine.com/region:cn-beijing/managed-agent/agents)。
2. 点击「创建 Agent」，或在已有 Agent 卡片上点击「编辑」。
3. 在「05 高级参数」区域，找到「Advisor」开关，打开即可。
4. 点击「保存」。

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

## API 方式

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

### 创建时开启

**选项：cURL**

```Bash
curl 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

> **说明**
>
> 更新时需要传入当前 `version`，版本号不匹配会更新失败。仅更新 `display_name` 时不生成新版本；更新 `advisors`、`system` 等版本化字段时，即使提交值与当前版本相同，也会生成新版本。

**选项：cURL**

```Bash
curl 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
          }
        ]
      }
    ]
  }'
```

> **注意**
>
> `tools` 使用覆盖逻辑。请求体一旦传入 `tools`，系统会用该数组整体覆盖 Agent 当前的 `tools` 配置，不会在原有基础上追加。如果你只想新增或调整某个工具，需要先读取当前 Agent 的 `tools`，再把「需要保留的工具 + 新的工具」一起写回请求体。

# 工作方式

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

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

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

# 观察 Advisor 调用

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

查看方式：

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

事件流的使用方式详见 [Session 事件流](/docs/session-event-stream)。

# 系统提示词建议

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

```text
你是一个专业的代码工程师。你有一个顾问模型可以提供更高级的架构指导和代码审查。

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

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

# 计费说明

Advisor 调用产生的 Token 费用按顾问模型的价格单独计费，不计入执行模型的用量。具体计费规则请参考方舟 Managed Agents 的 [计费说明](/docs/model-pricing#ma_billing)。

> **说明**
>
> Beta 阶段 Advisor 功能可能有免费额度或优惠政策，具体以控制台公示为准。

# 相关文档

#### [Tools](/docs/tools)

了解 Agent 支持的公开工具类型和配置方式。

[/docs/tools](/docs/tools)

#### [编排 Multi Agent](/docs/multi-agent)

Multi Agent 支持一个协调器 Agent 将任务委派给多个子智能体并行执行。

[/docs/multi-agent](/docs/multi-agent)

#### [定义 Outcome](/docs/define-outcome)

Outcome 支持定义任务验收标准，Agent 自动迭代直到达标。

[/docs/define-outcome](/docs/define-outcome)

#### [Session 事件流](/docs/session-event-stream)

通过事件流实时观测 Agent 的执行过程，包括消息、工具调用和状态变化。

[/docs/session-event-stream](/docs/session-event-stream)

<!-- review-swap-test 2026-07-22 -->