定义结果 - 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 年的收入
- 增长率假设明确说明且合理

## 成本结构
- COGS 和运营费用分别建模
- 利润率与历史趋势一致或偏差有正当理由

## 折扣率
- 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范围限定到会话来获取它们：

# Create a session
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Financial analysis on Costco",
)

# Define the outcome — agent starts working on receipt
client.beta.sessions.events.send(
    session_id=session.id,
    events=[
        {
            "type": "user.define_outcome",
            "description": "Build a DCF model for Costco in .xlsx",
            "rubric": {"type": "text", "content": RUBRIC},
            # or: "rubric": {"type": "file", "file_id": rubric.id},
            "max_iterations": 5,  # optional; default 3, max 20
        }
    ],
)

session = client.beta.sessions.retrieve(session.id)

for outcome in session.outcome_evaluations:
    print(f"{outcome.outcome_id}: {outcome.result}")
    # outc_01a...: satisfied

files = client.beta.files.list(scope_id=session.id)
for f in files.data:
    print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)")

content = client.beta.files.download(files.data[0].id)
content.write_to_file("costco_dcf.xlsx")

创建评分标准

编写有效评分标准的提示

使用结果创建会话

结果事件

定义结果用户事件

结果评估开始

结果评估进行中

结果评估结束

检查结果状态

检索可交付物