定义 Outcome

Outcome（任务验收）是方舟 Managed Agents 提供的进阶能力，也是「Agent 自我进化」能力的重要组成部分。在对话中定义任务目标和验收标准后，系统会自动拉起独立的评分器（Grader）对 Agent 的产出进行评估，让 Agent 检查要求可完成度，并根据反馈继续迭代优化，直到满足验收标准、达到迭代上限或任务失败。

Outcome 将 Session 从「对话」提升为「工作」——你只需要定义「完成」是什么样子，Agent 会自动朝着目标努力，自我评估、不断迭代，直到达成结果。

准备工作#

开始前你需要：

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

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

在使用 Outcome 之前，你需要：

1. 已经创建好 Agent 和 Environment，并能正常启动 Session。
2. 明确任务的验收标准。

Outcome 通过 Session 事件定义，无需创建专用 Agent。可以直接使用已有 Agent 的 agent_id 创建 Session。

使用 Outcome#

基本流程#

按照以下顺序创建任务并观察评估结果：

1. 通过 创建会话 创建绑定 Agent 和 Environment 的 Session。
2. 通过 流式获取会话事件 订阅 Session 事件流，并等待服务端返回 : ready。
3. 通过 发送会话事件 发送 user.define_outcome 事件，定义任务和验收标准。
4. 通过 SSE 持续接收 span.outcome_evaluation_start、span.outcome_evaluation_ongoing 和 span.outcome_evaluation_end 事件。

Agent 收到 user.define_outcome 事件后会立即开始工作，无需额外发送 user.message。

定义 Outcome#

向 Session 的事件入口提交 user.define_outcome 事件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16curl "https://ark.cn-beijing.volces.com/api/v3/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.define_outcome",
        "description": "为 Costco 构建一个 DCF 财务模型，并输出到 /mnt/session/outputs/costco_dcf.xlsx",
        "rubric": {
          "type": "text",
          "content": "# DCF 模型验收标准\n\n## 收入预测\n- 使用了过去 5 个财年的历史收入数据\n- 至少预测了未来 5 年的收入\n- 增长率假设明确说明且合理\n\n## 输出质量\n- 所有数据写入 /mnt/session/outputs/costco_dcf.xlsx\n- 工作表命名清晰\n- 关键假设在单独的「假设」工作表中"
        },
        "max_iterations": 5
      }
    ]
  }'

max_iterations 用于限制评估轮数，取值范围为 1～20，默认值为 3。user.define_outcome 的完整字段结构，请参见 会话事件结构参考。

发送成功后，Session 状态会从 idle 切换到 running，Agent 开始执行任务。

观察执行状态#

Outcome 事件流转#

下图展示一次 Outcome 中，任务执行、结果评估和自动修订之间的关系。客户端主要根据 span.outcome_evaluation_end.result 判断是继续等待下一轮评估，还是等待 Session 结束。

1. 客户端发送 user.define_outcome 后，Session 返回 session.status_running，Agent 开始执行任务。
2. Agent 生成本轮产出后，Session 返回 span.outcome_evaluation_start。评估期间可能多次返回 span.outcome_evaluation_ongoing，该事件只表示评估仍在进行。
3. Session 通过 span.outcome_evaluation_end 返回本轮评估结果。
4. 如果 result=needs_revision，Agent 根据评估反馈修订产出，然后进入下一轮评估；iteration 随评估轮次递增。
5. 如果返回其他结果，继续监听至 session.status_idle。max_iterations_reached 返回后，Agent 还会执行一次收尾。

如何建立和恢复 SSE 连接，请参见 Session 事件流。各事件的字段、取值和关联 ID，请参见 会话事件结构参考。

评估结果类型#

span.outcome_evaluation_end 事件中的 result 字段表示本轮评估的结论：

评估结束事件示例#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16{
  "type": "span.outcome_evaluation_end",
  "id": "sevt-20260702070410-xxxxx",
  "outcome_evaluation_start_id": "eval-20260702070405-xxxxx",
  "outcome_id": "outc-20260702070355-xxxxx",
  "result": "satisfied",
  "explanation": "所有 12 条标准均已满足：收入预测使用了 5 年历史数据，WACC 假设已说明，包含敏感性分析表...",
  "iteration": 0,
  "usage": {
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 22240,
    "input_tokens": 2400,
    "output_tokens": 350
  },
  "processed_at": "2026-07-02T07:04:10Z"
}

中断任务#

如果需要在 Outcome 运行过程中停止，可以发送 user.interrupt 事件：

1
2
3
4
5
6
7
8
9
10curl https://ark.cn-beijing.volces.com/api/v3/sessions/sesn-20260702070355-xxxxx/events \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.interrupt"
      }
    ]
  }'

中断后，当前 Outcome 会停止，span.outcome_evaluation_end.result 将标记为 interrupted。你可以在中断后启动一个新的 Outcome。

多个 Outcome 串联#

一次只支持一个 Outcome 运行，但你可以按顺序串联多个 Outcome。在前一个 Outcome 的终止事件（span.outcome_evaluation_end）之后，发送新的 user.define_outcome 事件即可启动下一个任务。

这对于多阶段工作流非常有用，例如：

1. 阶段一：需求分析
2. 阶段二：方案设计
3. 阶段三：编码实现
4. 阶段四：测试验证

编写验收标准#

验收标准（Rubric）是 Outcome 的核心，它定义了任务完成的评判标准。清晰、可验证的验收标准可以帮助 Agent 判断产出是否达标。

编写原则#

1. 明确、可量化，而非模糊描述

✅ 好：报告包含至少 3 个数据图表，且每个图表都有明确的标题和数据来源
❌ 不好：报告看起来不错

2. 描述「是什么」，而非「怎么做」

验收标准用来判断「交付物是否达标」，而不是指导 Agent「怎么完成任务」。让 Agent 自己选择执行方式，你只需要定义终点。

✅ 好：代码通过所有单元测试，覆盖率不低于 80%
❌ 不好：你应该先写测试再写代码，使用 pytest 框架...

3. 结构化、分条列项

使用 Markdown 标题和列表组织，让评分器能够逐条评估。

4. 从示例反推

如果你手头有已知合格的产出物示例，可以先分析「是什么让它合格」，然后将这些特质转化为验收标准条目。

验收标准模板#

以下是一个 DCF 财务模型的 Rubric 示例，供参考：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23# DCF 模型验收标准

## 收入预测
- 使用了过去 5 个财年的历史收入数据
- 至少预测了未来 5 年的收入
- 增长率假设明确说明且合理

## 成本结构
- 销货成本（COGS）和运营费用分别建模
- 利润率与历史趋势一致，或有合理解释

## 折现率
- WACC 计算包含权益成本和债务成本的假设说明
- Beta、无风险利率、股权风险溢价有来源或说明

## 终值
- 使用了永续增长法或退出倍数法（明确说明使用哪种）
- 终值增长率不超过长期 GDP 增长率

## 输出质量
- 所有数据在一个 .xlsx 文件中，工作表命名清晰
- 关键假设在单独的「假设」工作表中
- 包含 WACC 和终值增长率的敏感性分析

获取并验证交付物#

Agent 将输出文件写入沙箱内的 /mnt/session/outputs/ 目录。Session 进入 idle 后，产物可能暂时无法通过 Files API 查询。下面的示例从已完成的 $SESSION_ID 出发，完成以下操作：

1. 分页查询 purpose=agent 的文件。
2. 按文件名选择 costco_dcf.xlsx；尚未查询到目标文件时，每 2 秒重试一次，最多重试 10 次。
3. 从文件对象中提取 download_url 并下载。
4. 校验服务端返回的文件名与目标名称一致，并确认下载文件非空；任一条件不满足时返回非零状态。

需要将交付物长期保存在自己的 TOS Bucket 时，在创建 Environment 时配置 config.tos。未配置时，平台将产物存入方舟公共 TOS，请在平台 TTL 到期前下载所需文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70set -euo pipefail

: "${ARK_API_KEY:?Set ARK_API_KEY before running this script}"
: "${SESSION_ID:?Set SESSION_ID to the completed Session ID}"

OUTPUT_FILENAME="${OUTPUT_FILENAME:-costco_dcf.xlsx}"
OUTPUT_PATH="${OUTPUT_PATH:-./$OUTPUT_FILENAME}"
MAX_ATTEMPTS="${MAX_ATTEMPTS:-10}"
POLL_INTERVAL_SECONDS="${POLL_INTERVAL_SECONDS:-2}"

command -v jq >/dev/null 2>&1 || {
  echo "jq is required to parse the Files API response." >&2
  exit 1
}

file=""
for ((attempt = 1; attempt <= MAX_ATTEMPTS; attempt++)); do
  after=""

  while :; do
    url="https://ark.cn-beijing.volces.com/api/v3/files?scope_id=$SESSION_ID&purpose=agent&limit=100&order=desc"
    if [[ -n "$after" ]]; then
      url="$url&after=$after"
    fi

    response=$(curl -fsS "$url" \
      -H "Authorization: Bearer $ARK_API_KEY")

    file=$(jq -cer --arg filename "$OUTPUT_FILENAME" '
      [.data[]?
        | select(.filename == $filename)
        | select(.status == "active")
        | select((.download_url // "") != "")]
      | first // empty
    ' <<<"$response" || true)

    if [[ -n "$file" ]]; then
      break 2
    fi

    if [[ $(jq -r '.has_more // false' <<<"$response") != "true" ]]; then
      break
    fi
    after=$(jq -er '.last_id' <<<"$response")
  done

  if ((attempt < MAX_ATTEMPTS)); then
    sleep "$POLL_INTERVAL_SECONDS"
  fi
done

if [[ -z "$file" ]]; then
  echo "File not ready after $MAX_ATTEMPTS attempts: $OUTPUT_FILENAME" >&2
  exit 1
fi

filename=$(jq -r '.filename' <<<"$file")
download_url=$(jq -er '.download_url' <<<"$file")
if [[ "$filename" != "$OUTPUT_FILENAME" ]]; then
  echo "Unexpected filename: $filename" >&2
  exit 1
fi

curl -fsSL "$download_url" -o "$OUTPUT_PATH"
if [[ ! -s "$OUTPUT_PATH" ]]; then
  echo "Downloaded file is empty: $OUTPUT_PATH" >&2
  exit 1
fi

printf 'Downloaded %s (%s bytes)\n' "$OUTPUT_PATH" "$(wc -c <"$OUTPUT_PATH")"

如果脚本重试后仍未找到目标文件，先确认 Session 已进入 idle，并检查 Agent 是否将文件写入 /mnt/session/outputs/costco_dcf.xlsx。仅重新执行查询脚本即可，不需要重新提交 Outcome。

查询和下载产物的方法，详情请参见 上传与挂载文件。配置产物存储的方法，详情请参见 配置产物存储。

最佳实践#

从简单开始：初次使用 Outcome 时，建议从简单、明确的任务开始，逐步调优验收标准。

迭代优化验收标准：根据实际运行结果调整验收标准。如果 Agent 总是在同一环节出错，增加对应的检查项。

设置合理的迭代次数：初次使用时可以保持默认值 3。如果多次出现 max_iterations_reached，先检查任务目标和验收标准是否明确，再在 1～20 的范围内调整 max_iterations。

计费说明#

Outcome 的费用包含以下部分：

• Agent 执行费用：Agent 每轮迭代产生的模型 Token 费用，按 Agent 配置的模型价格计费。
• 评分器费用：每轮评估产生的模型 Token 费用，评分器使用独立模型，按对应价格计费。
• 沙箱费用：Session 运行期间的沙箱资源费用。

具体计费规则请参考方舟 Managed Agents 的 计费说明。

相关文档#