user.define_outcome で Session の合格基準を設定し、評価結果を取得します。
Outcome は Session に評価可能な合格目標を設定します。
Outcome を定義すると、
Session ごとに同時に有効な Outcome は 1 件だけです。終了状態に達した後は同じ Session に別の Outcome を定義でき、以前の評価記録は保持されます。
rubric は合格基準を 1 件ずつ列挙した Markdown 文書です。評価スレッドは各基準を個別に評価するため、具体的な基準ほど安定した判定が得られます。
評価スレッドが読めるのは rubric、サンドボックス、Agent の返信だけで、
複数の Session で rubric を再利用するには、ファイルとしてアップロードし、
各 Outcome は Session オブジェクトの
各評価回の記録はイベントストリーム(イベント一覧またはストリーミング)から取得できます。
サーバーは Agent turn、評価、修正を切り替える際に
1 件の Outcome は複数の
評価スレッドは Agent のツール権限を継承し、サンドボックス内で成果物を検証します。
正常終了した Agent turn だけが評価されます。Agent turn または修正 turn が自動再試行を使い切ってエラー終了した場合:
Session が
Outcome は
Agent が
エンドポイントは Session の成果物の交付と取得を参照してください。
以下のいずれも有効な Outcome を
description はタスク、rubric は合格基準を記述します。Agent が作業を完了すると、独立した評価スレッドが rubric に従って成果物を評価し、satisfied や failed などの判定を返します。
推奨されるエンドツーエンドの使い方は Outcome のベストプラクティスを参照してください。
動作の仕組み
Outcome を定義すると、description を入力として Agent turn が開始します。turn が終了すると、評価スレッドが成果物を評価します。不合格の場合は判定を Agent に返して修正させ、合格するか評価回数の上限に達するまで繰り返します。
1
Outcome を定義
description と rubric を指定して user.define_outcome を送信します。outcome_id はサーバーが生成します。2
Agent が作業
Agent は
description に従って成果物を作成します。turn が正常終了すると直ちに評価が始まり、Session は running のままです。3
評価
評価スレッドが rubric に従って成果物を評価します。イベントストリームに
span.outcome_evaluation_start と span.outcome_evaluation_ongoing が発行されます。4
修正
span.outcome_evaluation_end.result が needs_revision の場合、Agent は判定に基づいて修正 turn を開始します。クライアントからイベントを送信する必要はありません。5
終了状態
Outcome は
satisfied、failed、max_iterations_reached、interrupted のいずれかに達し、completed_at が設定されます。評価スレッドが判定を返した後、Agent は最終返信を書くために最後の turn を実行し、その後 Session は idle に戻ります。rubric の記述
rubric は合格基準を 1 件ずつ列挙した Markdown 文書です。評価スレッドは各基準を個別に評価するため、具体的な基準ほど安定した判定が得られます。
description は読めません。基準が依存する期待値や元データは rubric に記載してください。
記述のヒント
記述のヒント
- 各基準を検証可能にする。 「データ品質が良い」ではなく「CSV に数値型の
price列がある」と記述します。 - 具体的な証拠を求める。 取得したページ、追跡可能な計算、
file:lineの参照などです。 - 手順ではなく目標を記述する。 rubric が指定したコマンドを利用できないと、評価を進められません。
- 許容しない内容を明記する。 例えば「ミラー、転載、検索スニペットは証拠として認めない」と記述します。
- フィードバック形式を指定する。 基準ごとの合否と不足点を求めます。
- 評価対象外を明記する。 書式や、基準に関係のない追加成果物などです。
- rubric がまだない場合は、既知の良い成果物をモデルに分析させ、その分析を rubric にできます。
曖昧な基準では評価スレッドが
satisfied を返しやすく、厳しすぎる基準では評価回数が増えます。まず max_iterations: 1 で rubric を調整し、1 回で正しい判定が得られることを確認します。{"type":"file","file_id":"file_..."} で参照します。
Outcome の定義
POST /api/v1/cloud/sessions/{session_id}/events
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
description | string | はい | Agent turn の入力となるタスク記述 |
rubric | object | はい | 評価スレッド専用の合格基準。{"type":"text","content":"..."} または {"type":"file","file_id":"file_..."}。不明なフィールドは指定できません |
max_iterations | integer | いいえ | 最大評価回数。1–20 の整数、デフォルトは 3 |
user.define_outcomeは直ちに課金対象の Agent turn を開始します。タスクはdescription、合格基準だけをrubricに記述します。- rubric のテキストまたはファイル内容の上限は 64 KiB で、超過すると
400です。rubric.typeがfileの場合、参照ファイルは読み取り可能である必要があります。 - 各評価が credits を消費します。
max_iterationsが大きいほど、最悪の場合の評価回数が増えます。 outcome_id(接頭辞outc_)はサーバーが生成するため、リクエストに指定できません。
評価状態
各 Outcome は Session オブジェクトの outcome_evaluations 配列に 1 件の記録を持ち、Session の取得、Session 一覧、Session の検索で取得できます。
| フィールド | 型 | 説明 |
|---|---|---|
type | string | 常に outcome_evaluation |
outcome_id | string | 接頭辞 outc_ の Outcome ID |
description | string | 定義時に渡した description |
iteration | integer | 0 から始まる現在の評価回数 |
result | string | 現在の状態。以下の表を参照 |
explanation | string | null | 最新の評価説明。初回評価が終了するまでは null |
completed_at | string | null | 終了状態に達した時刻。それまでは null |
result の値:
| 値 | 説明 |
|---|---|
pending | 定義済み。Agent はまだ作業を開始していません |
running | Agent が作業または修正中 |
evaluating | 評価スレッドが評価中 |
satisfied | 終了。すべての基準を満たしました |
max_iterations_reached | 終了。最大回数に達しても成果物が合格しませんでした |
failed | 終了。タスクが rubric を満たせないと評価スレッドが判定した場合(例:description が rubric と矛盾)、または判定を返さなかった場合 |
interrupted | 終了。キャンセル、中断、またはサーバーによる回収 |
評価イベント
各評価回の記録はイベントストリーム(イベント一覧またはストリーミング)から取得できます。
| イベント | フィールド | 説明 |
|---|---|---|
span.outcome_evaluation_start | outcome_id, iteration | 評価開始 |
span.outcome_evaluation_ongoing | outcome_id, iteration | 評価中。間隔は固定ではないため、タイムアウトの判断には使わないでください |
span.outcome_evaluation_end | outcome_id, iteration, result, explanation, outcome_evaluation_start_id, usage | 評価終了 |
span.outcome_evaluation_end.resultは終了状態の値に加え、needs_revisionになることがあります。これは今回が不合格で残り回数があることを示します。最終回で不合格の場合はmax_iterations_reachedです。usage.creditsは今回の評価で消費した credits です。計量記録がない場合はusageが省略されます。- 評価開始前に Outcome が中断された場合、ストリームには
result: interruptedのspan.outcome_evaluation_endだけがあり、対応するspan.outcome_evaluation_startはありません。outcome_evaluation_start_idは空文字列です。
Outcome 実行中の Session 状態
サーバーは Agent turn、評価、修正を切り替える際に session.status_idle や session.status_running を発行しません。Outcome の定義から最後の turn の終了まで Session は running のままで、user.message と user.define_outcome の送信は 409 になります。
completed_at は評価スレッドが終了判定を返す時点で設定され、最後の turn の終了より前です。
| 目的 | 条件 |
|---|---|
| 評価判定を読む | outcome_evaluations[].completed_at が null ではない |
| Agent の最終返信を読む、または次のイベントを送る | Session の status が idle に戻る |
agent.message を生成します。Agent turn、各修正 turn、最後の turn がそれぞれ 1 件ずつ出力します。最終返信は終端の span.outcome_evaluation_end より後のものです。interrupted と、評価スレッドが判定を返さないことによる failed には最後の turn がありません。
Outcome 実行中も以下の状態イベントが発行される場合があります。これらは Outcome の終了を意味しません。
| イベント | 原因 | 対応 |
|---|---|---|
stop_reason.type が requires_action の session.status_idle | ツール呼び出しが確認待ち | ツール確認を参照 |
session.status_rescheduled に続く session.status_running | モデル要求の自動再試行 | 対応不要。モデル要求の自動再試行を参照 |
ツール確認
評価スレッドは Agent のツール権限を継承し、サンドボックス内で成果物を検証します。always_ask のツールは Agent と評価スレッドのどちらが呼び出しても確認待ちになります。Pending Action フローと同じ流れです。
evaluated_permission: askのagent.tool_useと、stop_reason.type: requires_actionのsession.status_idleが発行されます。- クライアントは
stop_reason.event_idsのイベント ID を使ってuser.tool_confirmationを送信します。 - 確認後に評価が続きます。
status は running、outcome_evaluations[].result は running または evaluating です。Pending action は自動タイムアウトしないため、確認されるまで評価は続きません。
評価スレッドが発行した agent.tool_use は、スレッド一覧に返されない内部スレッドの session_thread_id を持ちます。呼び出しの確認後、このイベントはイベント履歴に残りません。
無人評価では、必要な読み取りツール(Read、Bash、Glob、Grep など)を always_allow に設定します。
Agent turn のエラー
正常終了した Agent turn だけが評価されます。Agent turn または修正 turn が自動再試行を使い切ってエラー終了した場合:
error.retry_status.type: exhaustedのsession.errorが発行され、session.status_idleは発行されません。Session のstatusはidleに戻ります。- Outcome は有効なままです。
resultはpendingまたはrunning、completed_atはnullです。 - 新しい Outcome の定義は
409になります。user.messageを送ると新しい turn が始まり、終了後は現在の Outcome の rubric で評価されます。 - 一定時間新しい turn が始まらない場合、サーバーが Outcome を回収します。
resultはinterruptedになり、span.outcome_evaluation_endが発行されます。
リクエスト制約
| 制約 | 結果 |
|---|---|
user.define_outcome を user.message、user.tool_result、user.custom_tool_result と同じリクエストで送信 | リクエスト全体が 400 となり、どのイベントも適用されません |
1 リクエストに複数の user.define_outcome を含む | 順に処理され、最初は適用されます。後続は 409 で、最初はロールバックされません |
Session が turn を処理中(running または rescheduling) | 409 |
Session に有効な Outcome がある(result が pending、running、evaluating) | 409 |
idle でも有効な Outcome が残る場合があります(Agent turn のエラーを参照)。user.define_outcome を送る前に、Session が idle で有効な Outcome がないことの両方を確認します。
user.define_outcome イベントでのみ定義でき、Session 作成時のフィールドではありません。Deployment の initial_events にこのイベントを指定できます。
成果物の取得
Agent が DeliverArtifacts で交付したファイルは現在の Session に属します。成功すると、ストリームに agent.artifact_delivered が発行されます。
- 修正 turn で再交付すると新しい File が作成されます。最後の
agent.artifact_deliveredのfile_idで最終版を取得します。 - 交付後、一覧に反映されるまで数秒かかる場合があります。
- Agent が
agent.messageに直接結果を返す場合もあります。クライアントは両方を処理してください。
キャンセルと中断
以下のいずれも有効な Outcome を interrupted にします。
- Session をキャンセル:
POST /api/v1/cloud/sessions/{session_id}/cancel。 session_thread_idなしでuser.interruptを送信。Session のキャンセルと同じ効果です。
完全な例
推奨事項
| 状況 | 推奨 |
|---|---|
| 合否判定だけが必要 | max_iterations: 1 とし、rubric に合格条件と失敗条件を明記 |
| 判定に基づいて Agent に修正させたい | max_iterations を 1 より大きく設定。評価コストは回数に応じて増加 |
| 作業は完了し、検証だけが必要 | 定義しても Agent turn は開始するため、description に既存成果物の検証と修正を指示 |
| 交付されたかだけを知りたい | Outcome は不要。agent.artifact_delivered と Session 状態を利用 |
エラー
| HTTP 状態 | 原因 |
|---|---|
400 | rubric の構造不正、max_iterations が 1–20 の範囲外、64 KiB 超過、outcome_id など禁止フィールド、user.message またはツール結果と同じリクエストで送信 |
404 | Session が存在しない、または rubric.file_id が参照するファイルが存在しない |
409 | Session が turn を処理中、または有効な Outcome が存在 |