定義結果

建構將工作委派給代理

定義結果

告訴代理「完成」的樣子，讓它迭代直到達成目標。

Outcomes 是一項研究預覽功能。申請存取權以試用。

outcome 將一個會話從對話提升到工作。您定義最終結果應該是什麼樣子以及如何衡量品質。代理會朝著該目標工作，自我評估並迭代直到達成結果。

當您定義一個結果時，系統會自動配置一個評分器來根據評分標準評估工件。它利用單獨的上下文窗口，以避免受到主代理實現選擇的影響。

評分器返回按標準的細分：要麼確認工件滿足評分標準，要麼指出當前工作與要求之間的具體差距。該反饋被傳回給代理進行下一次迭代。

所有 Managed Agents API 請求都需要 managed-agents-2026-04-01 測試版標頭。研究預覽功能另外需要 managed-agents-2026-04-01-research-preview。SDK 會自動設定這些測試版標頭。

建立評分標準

評分標準是描述按標準評分的 markdown 文件。評分標準是必需的。

範例評分標準：

# DCF 模型評分標準

## 收入預測
- 使用過去 5 個財政年度的歷史收入資料
- 向前預測至少 5 年的收入
- 增長率假設明確說明且合理

## 成本結構
- COGS 和營運費用分別建模
- 邊際利潤與歷史趨勢一致或偏差有正當理由

## 折扣率
- WACC 使用股權成本和債務成本的明確假設計算
- Beta、無風險利率和股權風險溢價有來源或正當理由

## 終端價值
- 使用永續增長或退出倍數方法（說明使用哪一種）
- 終端增長率不超過長期 GDP 增長

## 輸出品質
- 所有數字都在單個 .xlsx 檔案中，具有清晰標記的工作表
- 關鍵假設在單獨的「假設」工作表上
- 包含 WACC 和終端增長率的敏感性分析

在 user.define_outcome 上以內聯文本傳遞評分標準（如下一節所示），或透過 Files API 上傳以在會話間重複使用：

需要測試版標頭 files-api-2025-04-14。

from pathlib import Path

rubric = client.beta.files.upload(file=Path("/path/to/pr_review_rubric.md"))
print(f"Uploaded rubric: {rubric.id}")

使用結果建立會話

建立會話後，發送 user.define_outcome 事件。代理立即開始工作；不需要額外的使用者訊息事件。

# 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
        }
    ],
)

結果事件

結果導向會話的進度在事件串流上顯示。

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：

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

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

檢索可交付成果

代理將輸出檔案寫入容器內的 /mnt/session/outputs/。會話閒置後，透過Files API（限定於會話）取得它們：

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")

Was this page helpful?

建構將工作委派給代理

定義結果

告訴代理「完成」的樣子，讓它迭代直到達成目標。

Outcomes 是一項研究預覽功能。申請存取權以試用。

outcome 將一個會話從對話提升到工作。您定義最終結果應該是什麼樣子以及如何衡量品質。代理會朝著該目標工作，自我評估並迭代直到達成結果。

當您定義一個結果時，系統會自動配置一個評分器來根據評分標準評估工件。它利用單獨的上下文窗口，以避免受到主代理實現選擇的影響。

評分器返回按標準的細分：要麼確認工件滿足評分標準，要麼指出當前工作與要求之間的具體差距。該反饋被傳回給代理進行下一次迭代。

建立評分標準

評分標準是描述按標準評分的 markdown 文件。評分標準是必需的。

範例評分標準：

# DCF 模型評分標準

## 收入預測
- 使用過去 5 個財政年度的歷史收入資料
- 向前預測至少 5 年的收入
- 增長率假設明確說明且合理

## 成本結構
- COGS 和營運費用分別建模
- 邊際利潤與歷史趨勢一致或偏差有正當理由

## 折扣率
- WACC 使用股權成本和債務成本的明確假設計算
- Beta、無風險利率和股權風險溢價有來源或正當理由

## 終端價值
- 使用永續增長或退出倍數方法（說明使用哪一種）
- 終端增長率不超過長期 GDP 增長

## 輸出品質
- 所有數字都在單個 .xlsx 檔案中，具有清晰標記的工作表
- 關鍵假設在單獨的「假設」工作表上
- 包含 WACC 和終端增長率的敏感性分析

在 user.define_outcome 上以內聯文本傳遞評分標準（如下一節所示），或透過 Files API 上傳以在會話間重複使用：

需要測試版標頭 files-api-2025-04-14。

from pathlib import Path

rubric = client.beta.files.upload(file=Path("/path/to/pr_review_rubric.md"))
print(f"Uploaded rubric: {rubric.id}")

使用結果建立會話

建立會話後，發送 user.define_outcome 事件。代理立即開始工作；不需要額外的使用者訊息事件。

# 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
        }
    ],
)

結果事件

結果導向會話的進度在事件串流上顯示。

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
}

結果評估開始

{
  "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：

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

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

檢索可交付成果

代理將輸出檔案寫入容器內的 /mnt/session/outputs/。會話閒置後，透過Files API（限定於會話）取得它們：

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")

Was this page helpful?

建立評分標準

撰寫有效評分標準的提示

使用結果建立會話

結果事件

定義結果使用者事件

結果評估開始

結果評估進行中

結果評估結束

檢查結果狀態

檢索可交付成果

建立評分標準

撰寫有效評分標準的提示

使用結果建立會話

結果事件

定義結果使用者事件

結果評估開始

結果評估進行中

結果評估結束

檢查結果狀態

檢索可交付成果