Managed Agents將工作委派給您的代理

定義成果

告訴代理「完成」是什麼樣子，並讓它反覆迭代直到達成目標。

「Outcome」（成果）告訴工作階段最終結果應該是什麼樣子，以及如何衡量其品質。代理會朝著該目標努力，自我評估並反覆迭代，直到達成成果為止。

當您定義成果時，harness 會自動配置一個 grader（評分器），依據評分標準來評估產出物。評分器使用獨立的「context window」（上下文視窗），以避免受到主代理實作選擇的影響。

評分器會回傳一段說明，總結哪些標準通過或未通過，或確認產出物符合評分標準。該回饋會交回給代理，用於下一次迭代。

建立評分標準

「Rubric」（評分標準）是一份描述逐項標準評分方式的 markdown 文件。評分標準為必填。

評分標準範例：

# DCF Model Rubric

## Revenue Projections
- Uses historical revenue data from the last 5 fiscal years
- Projects revenue for at least 5 years forward
- Growth rate assumptions are explicitly stated and reasonable

## Cost Structure
- COGS and operating expenses are modeled separately
- Margins are consistent with historical trends or deviations are justified

## Discount Rate
- WACC is calculated with stated assumptions for cost of equity and cost of debt
- Beta, risk-free rate, and equity risk premium are sourced or justified

## Terminal Value
- Uses either perpetuity growth or exit multiple method (stated which)
- Terminal growth rate does not exceed long-term GDP growth

## Output Quality
- All figures are in a single .xlsx file with clearly labeled sheets
- Key assumptions are on a separate "Assumptions" sheet
- Sensitivity analysis on WACC and terminal growth rate is included

將評分標準以內嵌文字的形式傳入 user.define_outcome（請參閱建立帶有成果的工作階段），或透過 Files API 上傳，以便在多個工作階段之間重複使用。

import time
from pathlib import Path

from anthropic import Anthropic

client = Anthropic()

RUBRIC = """# DCF Model Rubric

## Revenue Projections
- Uses historical revenue data from the last 5 fiscal years
- Projects revenue for at least 5 years forward

## Output Quality
- All figures are in a single .xlsx file with clearly labeled sheets
"""
Path("/tmp/rubric.md").write_text(RUBRIC)

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

建立帶有成果的工作階段

以下範例為現有的代理與環境（兩者皆另行建立）建立一個工作階段，然後傳送一個 user.define_outcome 事件。代理會立即開始工作，不需要額外的使用者訊息事件。

# 建立工作階段
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Financial analysis on Costco",
)

# 定義成果 — 代理程式收到後即開始工作
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},
            # 或："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，讓您可以啟動新的成果。
在最終成果評估之後，工作階段可以作為對話式工作階段繼續，或開始新的成果。工作階段會保留先前成果的歷史記錄。

定義成果使用者事件

這是您用來啟動成果所傳送的事件。收到後會回傳該事件，其中包含 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...",
  "iteration": 0,
  "processed_at": "2026-03-25T14:02:10Z"
}

成果評估結束

當一個成果評估週期結束時發出：在評分器完成一次迭代的評估之後，或在成果處於作用中時工作階段被中斷。result 欄位指出接下來會發生什麼。

結果	後續
`satisfied`	工作階段轉換為 `idle`。
`needs_revision`	代理開始新的迭代週期。
`max_iterations_reached`	在工作階段轉換為 `idle` 之前，會再進行最後一次確認回合。不會再執行進一步的評估。
`failed`	工作階段轉換為 `idle`。當評分標準不適用於交付成果時回傳，例如描述與評分標準互相矛盾。
`interrupted`	當成果處於作用中時工作階段被中斷即會發出，即使評估尚未開始。若在中斷前沒有觸發任何 `outcome_evaluation_start`，則 `outcome_evaluation_start_id` 為空字串。

{
  "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/{session_id} 並讀取 outcome_evaluations[].result。在評估完成之前，result 會回報 pending、running 或 evaluating：

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 取得這些檔案。

# 列出此工作階段產生的檔案
# scope_id 篩選需要在 files 請求上啟用 managed-agents beta
files = client.beta.files.list(scope_id=session.id, betas=["managed-agents-2026-04-01"])
for file in files:
    print(file.id, file.filename)

# 下載檔案
if files.data:
    content = client.files.download(files.data[0].id)
    content.write_to_file("/tmp/output.txt")

後續步驟

使用 vault 進行驗證

在建立工作階段時註冊每位使用者的憑證。

工作階段事件串流

傳送事件、串流回應，並在執行中途中斷或重新導向您的工作階段。

新增檔案

上傳檔案並將其掛載到您的沙箱中以供讀取與處理。

Was this page helpful?

Managed Agents將工作委派給您的代理

定義成果

告訴代理「完成」是什麼樣子，並讓它反覆迭代直到達成目標。

「Outcome」（成果）告訴工作階段最終結果應該是什麼樣子，以及如何衡量其品質。代理會朝著該目標努力，自我評估並反覆迭代，直到達成成果為止。

評分器會回傳一段說明，總結哪些標準通過或未通過，或確認產出物符合評分標準。該回饋會交回給代理，用於下一次迭代。

建立評分標準

「Rubric」（評分標準）是一份描述逐項標準評分方式的 markdown 文件。評分標準為必填。

評分標準範例：

# DCF Model Rubric

## Revenue Projections
- Uses historical revenue data from the last 5 fiscal years
- Projects revenue for at least 5 years forward
- Growth rate assumptions are explicitly stated and reasonable

## Cost Structure
- COGS and operating expenses are modeled separately
- Margins are consistent with historical trends or deviations are justified

## Discount Rate
- WACC is calculated with stated assumptions for cost of equity and cost of debt
- Beta, risk-free rate, and equity risk premium are sourced or justified

## Terminal Value
- Uses either perpetuity growth or exit multiple method (stated which)
- Terminal growth rate does not exceed long-term GDP growth

## Output Quality
- All figures are in a single .xlsx file with clearly labeled sheets
- Key assumptions are on a separate "Assumptions" sheet
- Sensitivity analysis on WACC and terminal growth rate is included

將評分標準以內嵌文字的形式傳入 user.define_outcome（請參閱建立帶有成果的工作階段），或透過 Files API 上傳，以便在多個工作階段之間重複使用。

import time
from pathlib import Path

from anthropic import Anthropic

client = Anthropic()

RUBRIC = """# DCF Model Rubric

## Revenue Projections
- Uses historical revenue data from the last 5 fiscal years
- Projects revenue for at least 5 years forward

## Output Quality
- All figures are in a single .xlsx file with clearly labeled sheets
"""
Path("/tmp/rubric.md").write_text(RUBRIC)

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

建立帶有成果的工作階段

# 建立工作階段
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Financial analysis on Costco",
)

# 定義成果 — 代理程式收到後即開始工作
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},
            # 或："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，讓您可以啟動新的成果。
在最終成果評估之後，工作階段可以作為對話式工作階段繼續，或開始新的成果。工作階段會保留先前成果的歷史記錄。

定義成果使用者事件

這是您用來啟動成果所傳送的事件。收到後會回傳該事件，其中包含 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...",
  "iteration": 0,
  "processed_at": "2026-03-25T14:02:10Z"
}

成果評估結束

當一個成果評估週期結束時發出：在評分器完成一次迭代的評估之後，或在成果處於作用中時工作階段被中斷。result 欄位指出接下來會發生什麼。

結果	後續
`satisfied`	工作階段轉換為 `idle`。
`needs_revision`	代理開始新的迭代週期。
`max_iterations_reached`	在工作階段轉換為 `idle` 之前，會再進行最後一次確認回合。不會再執行進一步的評估。
`failed`	工作階段轉換為 `idle`。當評分標準不適用於交付成果時回傳，例如描述與評分標準互相矛盾。
`interrupted`	當成果處於作用中時工作階段被中斷即會發出，即使評估尚未開始。若在中斷前沒有觸發任何 `outcome_evaluation_start`，則 `outcome_evaluation_start_id` 為空字串。

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

檢查成果狀態

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 取得這些檔案。

# 列出此工作階段產生的檔案
# scope_id 篩選需要在 files 請求上啟用 managed-agents beta
files = client.beta.files.list(scope_id=session.id, betas=["managed-agents-2026-04-01"])
for file in files:
    print(file.id, file.filename)

# 下載檔案
if files.data:
    content = client.files.download(files.data[0].id)
    content.write_to_file("/tmp/output.txt")

後續步驟

使用 vault 進行驗證

在建立工作階段時註冊每位使用者的憑證。

工作階段事件串流

傳送事件、串流回應，並在執行中途中斷或重新導向您的工作階段。

新增檔案

上傳檔案並將其掛載到您的沙箱中以供讀取與處理。

Was this page helpful?

建立評分標準

撰寫有效評分標準的技巧

建立帶有成果的工作階段

成果事件

定義成果使用者事件

成果評估開始

成果評估進行中

成果評估結束

檢查成果狀態

擷取交付成果

後續步驟

建立評分標準

撰寫有效評分標準的技巧

建立帶有成果的工作階段

成果事件

定義成果使用者事件

成果評估開始

成果評估進行中

成果評估結束

檢查成果狀態

擷取交付成果

後續步驟

建立評分標準

建立帶有成果的工作階段

成果事件

定義成果使用者事件

成果評估開始

成果評估進行中

成果評估結束

檢查成果狀態

擷取交付成果

後續步驟

建立評分標準

建立帶有成果的工作階段

成果事件

定義成果使用者事件

成果評估開始

成果評估進行中

成果評估結束

檢查成果狀態

擷取交付成果

後續步驟