定義成果 - 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

建立評分標準

撰寫有效評分標準的技巧

建立含有成果的工作階段

成果事件

定義成果使用者事件

成果評估開始

成果評估進行中

成果評估結束

檢查成果狀態

擷取交付成果