定义结果 - Claude API Docs

结果（Outcomes）是研究预览功能。申请访问权限以试用。

outcome 将会话从对话提升为工作。您定义最终结果应该是什么样子以及如何衡量质量。智能体朝着该目标努力，进行自我评估并迭代，直到达到结果。

当您定义结果时，框架会自动配置一个评分器，根据评分标准对工件进行评估。它利用独立的上下文窗口，以避免受到主智能体实现选择的影响。

评分器返回每个标准的详细分解：确认工件满足评分标准，或者当前工作与要求之间的具体差距。该反馈会传回给智能体用于下一次迭代。

所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 beta 头部。研究预览功能还需要 managed-agents-2026-04-01-research-preview。SDK 会自动设置这些 beta 头部。

创建评分标准

评分标准是描述每个标准评分的 markdown 文档。评分标准是必需的。

示例评分标准：

# DCF 模型评分标准

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

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

## 折现率
- WACC 使用明确的股权成本和债务成本假设计算
- Beta、无风险利率和股权风险溢价有来源或合理依据

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

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

将评分标准作为内联文本传递给 user.define_outcome（在下一节中显示），或通过 Files API 上传以在会话间复用：

需要 beta 头部 files-api-2025-04-14。

创建带有结果的会话

创建会话后，发送 user.define_outcome 事件。智能体立即开始工作；不需要额外的用户消息事件。

结果事件

面向结果的会话的进度会在事件流中显示。

agent.* 事件（消息、工具使用等）显示朝向结果的进度。
span.outcome_evaluation_* 事件仅针对面向结果的会话发出，显示迭代循环次数和评分器的反馈过程。
您也可以向面向结果的会话发送 user.message 事件，以在进度推进时指导智能体的工作，但这并非必要；智能体知道要工作直到耗尽迭代次数或达到结果。
user.interrupt 事件将暂停当前结果的工作，并将 span.outcome_evaluation_end.result 标记为 interrupted，允许您启动新的结果。
在最终结果评估之后，会话可以作为对话会话继续，或者可以启动新的结果。会话将保留先前结果的历史记录。

定义结果用户事件

一次只支持一个结果，但您可以按顺序链接多个结果。为此，请在上一个结果的终止事件之后发送新的 user.define_outcome 事件。

这是您发送以启动结果的事件。它在收到时被回显，包括 processed_at 时间戳和 outcome_id。

{
  "type": "user.define_outcome",
  "description": "Build a DCF model for Costco in .xlsx",
  "rubric": { "type": "file", "file_id": "file_01..." },
  "max_iterations": 5
}

结果评估开始

在评分器开始对一个迭代循环进行评估后发出。iteration 字段是一个从 0 开始的修订计数器：0 是第一次评估，1 是第一次修订后的重新评估，依此类推。

{
  "type": "span.outcome_evaluation_start",
  "id": "sevt_01def...",
  "outcome_id": "outc_01a...",
  "iteration": 0,
  "processed_at": "2026-03-25T14:01:45Z"
}

结果评估进行中

评分器运行时发出的心跳。评分器的内部推理是不透明的：您看到它正在工作，但看不到它在思考什么。

{
  "type": "span.outcome_evaluation_ongoing",
  "id": "sevt_01ghi...",
  "outcome_id": "outc_01a...",
  "processed_at": "2026-03-25T14:02:10Z"
}

结果评估结束

在评分器完成对一次迭代的评估后发出。result 字段指示接下来会发生什么。

结果	下一步
`satisfied`	会话转换为 `idle`。
`needs_revision`	智能体开始新的迭代周期。
`max_iterations_reached`	不再有进一步的评估周期。智能体可能在会话转换为 `idle` 之前运行最后一次修订。
`failed`	会话转换为 `idle`。当评分标准从根本上与任务不匹配时返回，例如描述和评分标准相互矛盾。
`interrupted`	仅在 `outcome_evaluation_start` 已在中断之前触发时发出。

{
  "type": "span.outcome_evaluation_end",
  "id": "sevt_01jkl...",
  "outcome_evaluation_start_id": "sevt_01def...",
  "outcome_id": "outc_01a...",
  "result": "satisfied",
  "explanation": "All 12 criteria met: revenue projections use 5 years of historical data, WACC assumptions are stated, sensitivity table is included...",
  "iteration": 0,
  "usage": {
    "input_tokens": 2400,
    "output_tokens": 350,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 1800
  },
  "processed_at": "2026-03-25T14:03:00Z"
}

检查结果状态

您可以在事件流上监听 span.outcome_evaluation_end，或轮询 GET /v1/sessions/:id 并读取 outcome_evaluations[].result：

检索交付物

智能体将输出文件写入容器内的 /mnt/session/outputs/。会话空闲后，通过限定到该会话的 Files API 获取它们：

rubric=$(curl -fsSL https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01,files-api-2025-04-14" \
  -F file=@/path/to/pr_review_rubric.md)
rubric_id=$(jq -r '.id' <<<"$rubric")
printf 'Uploaded rubric: %s\n' "$rubric_id"

# 创建会话
session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01-research-preview" \
  --json @- <<EOF
{
  "agent": "$agent_id",
  "environment_id": "$environment_id",
  "title": "Financial analysis on Costco"
}
EOF
)
session_id=$(jq -r '.id' <<<"$session")

# 定义结果 — 智能体收到后立即开始工作
curl -fsSL "https://api.anthropic.com/v1/sessions/$session_id/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01-research-preview" \
  --json @- >/dev/null <<EOF
{
  "events": [
    {
      "type": "user.define_outcome",
      "description": "Build a DCF model for Costco in .xlsx",
      "rubric": {"type": "text", "content": "# DCF Model Rubric\n..."},
      "max_iterations": 5
    }
  ]
}
EOF
# 或者: "rubric": {"type": "file", "file_id": "$rubric_id"}
# "max_iterations" 是可选的；默认值为 3，最大值为 20

session=$(curl -fsSL "https://api.anthropic.com/v1/sessions/$session_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01-research-preview")

jq -r '.outcome_evaluations[] | "\(.outcome_id): \(.result)"' <<<"$session"
# outc_01a...: satisfied

# 列出此会话生成的文件
curl -fsSL "https://api.anthropic.com/v1/files?scope_id=$session_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14,managed-agents-2026-04-01-research-preview" \
| jq '.data[] | {id, filename, size_bytes}'

# 通过 file_id 下载
curl -fsSL "https://api.anthropic.com/v1/files/$file_id/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -o costco_dcf.xlsx

创建评分标准

编写有效评分标准的技巧

创建带有结果的会话

结果事件

定义结果用户事件

结果评估开始

结果评估进行中

结果评估结束

检查结果状态

检索交付物