Managed Agentsエージェントに作業を委任する

アウトカムを定義する

エージェントに「完了」の状態を伝え、そこに到達するまで反復させます。

outcome は、セッションを会話から作業へと昇格させます。最終結果がどのようなものであるべきか、そして品質をどのように測定するかを定義します。エージェントはそのターゲットに向けて作業を進め、アウトカムが満たされるまで自己評価と反復を繰り返します。

アウトカムを定義すると、ハーネスは自動的にグレーダーをプロビジョニングし、ルーブリックに照らして成果物を評価します。グレーダーは、メインエージェントの実装上の選択に影響されないように、別のコンテキストウィンドウを使用します。

グレーダーは、どの基準が合格または不合格だったかを要約した説明、または成果物がルーブリックを満たしていることを確認する説明を返します。そのフィードバックは、次の反復のためにエージェントに渡されます。

すべてのManaged Agents APIリクエストには、managed-agents-2026-04-01ベータヘッダーが必要です。SDKはベータヘッダーを自動的に設定します。

ルーブリックを作成する

ルーブリックは、基準ごとのスコアリングを記述したマークダウンドキュメントです。ルーブリックは必須です。

ルーブリックの例：

# 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経由でアップロードします。

Files API経由でアップロードするには、managed-agents-2026-04-01 と files-api-2025-04-14 の両方のベータヘッダーが必要です。

rubric = client.beta.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 としてマークします。これにより、新しいアウトカムを開始できます。
最終的なアウトカム評価の後、セッションは会話型セッションとして継続することも、新しいアウトカムを開始することもできます。セッションは以前のアウトカムの履歴を保持します。

アウトカム定義ユーザーイベント

一度にサポートされるアウトカムは1つだけですが、アウトカムを順番にチェーンすることができます。これを行うには、前のアウトカムの終端イベントの後に新しい 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
}

アウトカム評価開始

グレーダーが1回の反復ループに対する評価を開始すると発行されます。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"
}

アウトカム評価終了

グレーダーが1回の反復の評価を終了した後に発行されます。result フィールドは次に何が起こるかを示します。

結果	次のステップ
`satisfied`	セッションは `idle` に遷移します。
`needs_revision`	エージェントは新しい反復サイクルを開始します。
`max_iterations_reached`	これ以上の評価サイクルはありません。エージェントは、セッションが `idle` に遷移する前に最後のリビジョンを1回実行する場合があります。
`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:
    print(f.id, f.filename)

# ファイルをダウンロード
if files.data:
    content = client.beta.files.download(files.data[0].id)
    content.write_to_file("/tmp/output.txt")

Was this page helpful?

Managed Agentsエージェントに作業を委任する

アウトカムを定義する

エージェントに「完了」の状態を伝え、そこに到達するまで反復させます。

すべてのManaged Agents APIリクエストには、managed-agents-2026-04-01ベータヘッダーが必要です。SDKはベータヘッダーを自動的に設定します。

ルーブリックを作成する

ルーブリックは、基準ごとのスコアリングを記述したマークダウンドキュメントです。ルーブリックは必須です。

ルーブリックの例：

# 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

Files API経由でアップロードするには、managed-agents-2026-04-01 と files-api-2025-04-14 の両方のベータヘッダーが必要です。

rubric = client.beta.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
}

アウトカム評価開始

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

アウトカム評価終了

グレーダーが1回の反復の評価を終了した後に発行されます。result フィールドは次に何が起こるかを示します。

結果	次のステップ
`satisfied`	セッションは `idle` に遷移します。
`needs_revision`	エージェントは新しい反復サイクルを開始します。
`max_iterations_reached`	これ以上の評価サイクルはありません。エージェントは、セッションが `idle` に遷移する前に最後のリビジョンを1回実行する場合があります。
`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"
}

アウトカムステータスの確認

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:
    print(f.id, f.filename)

# ファイルをダウンロード
if files.data:
    content = client.beta.files.download(files.data[0].id)
    content.write_to_file("/tmp/output.txt")

Was this page helpful?

ルーブリックを作成する

効果的なルーブリックを書くためのヒント

アウトカムを持つセッションを作成する

アウトカムイベント

アウトカム定義ユーザーイベント

アウトカム評価開始

アウトカム評価進行中

アウトカム評価終了

アウトカムステータスの確認

成果物の取得

ルーブリックを作成する

効果的なルーブリックを書くためのヒント

アウトカムを持つセッションを作成する

アウトカムイベント

アウトカム定義ユーザーイベント

アウトカム評価開始

アウトカム評価進行中

アウトカム評価終了

アウトカムステータスの確認

成果物の取得

ルーブリックを作成する

アウトカムを持つセッションを作成する

アウトカムイベント

アウトカム定義ユーザーイベント

アウトカム評価開始

アウトカム評価進行中

アウトカム評価終了

アウトカムステータスの確認

成果物の取得

ルーブリックを作成する

アウトカムを持つセッションを作成する

アウトカムイベント

アウトカム定義ユーザーイベント

アウトカム評価開始

アウトカム評価進行中

アウトカム評価終了

アウトカムステータスの確認

成果物の取得