Skip to main content
Agent にタスクを委任する

Outcome の評価

user.define_outcome で Session の合格基準を設定し、評価結果を取得します。

Outcome は Session に評価可能な合格目標を設定します。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 に戻ります。
Session ごとに同時に有効な Outcome は 1 件だけです。終了状態に達した後は同じ Session に別の Outcome を定義でき、以前の評価記録は保持されます。

rubric の記述

rubric は合格基準を 1 件ずつ列挙した Markdown 文書です。評価スレッドは各基準を個別に評価するため、具体的な基準ほど安定した判定が得られます。
# Performance report rubric

## Deliverables
- /data/report.html exists
- The report contains throughput and latency figures, with at least one chart each

## Quality of conclusions
- The top 3 bottlenecks are listed explicitly
- Each bottleneck cites a code location or profiling data as evidence

## Exclusions
- No placeholder content, TODOs, or sample data
評価スレッドが読めるのは rubric、サンドボックス、Agent の返信だけで、description は読めません。基準が依存する期待値や元データは rubric に記載してください。
  • 各基準を検証可能にする。 「データ品質が良い」ではなく「CSV に数値型の price 列がある」と記述します。
  • 具体的な証拠を求める。 取得したページ、追跡可能な計算、file:line の参照などです。
  • 手順ではなく目標を記述する。 rubric が指定したコマンドを利用できないと、評価を進められません。
  • 許容しない内容を明記する。 例えば「ミラー、転載、検索スニペットは証拠として認めない」と記述します。
  • フィードバック形式を指定する。 基準ごとの合否と不足点を求めます。
  • 評価対象外を明記する。 書式や、基準に関係のない追加成果物などです。
  • rubric がまだない場合は、既知の良い成果物をモデルに分析させ、その分析を rubric にできます。
曖昧な基準では評価スレッドが satisfied を返しやすく、厳しすぎる基準では評価回数が増えます。まず max_iterations: 1 で rubric を調整し、1 回で正しい判定が得られることを確認します。
複数の Session で rubric を再利用するには、ファイルとしてアップロードし、{"type":"file","file_id":"file_..."} で参照します。

Outcome の定義

POST /api/v1/cloud/sessions/{session_id}/events
{
  "events": [
    {
      "type": "user.define_outcome",
      "description": "Deliver a runnable performance report that identifies the top 3 bottlenecks",
      "rubric": {
        "type": "text",
        "content": "Must produce /data/report.html; include throughput and latency figures; list the top 3 bottlenecks with evidence"
      },
      "max_iterations": 1
    }
  ]
}
フィールド型必須説明
descriptionstringはいAgent turn の入力となるタスク記述
rubricobjectはい評価スレッド専用の合格基準。{"type":"text","content":"..."} または {"type":"file","file_id":"file_..."}。不明なフィールドは指定できません
max_iterationsintegerいいえ最大評価回数。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 の検索で取得できます。
フィールド型説明
typestring常に outcome_evaluation
outcome_idstring接頭辞 outc_ の Outcome ID
descriptionstring定義時に渡した description
iterationinteger0 から始まる現在の評価回数
resultstring現在の状態。以下の表を参照
explanationstring | null最新の評価説明。初回評価が終了するまでは null
completed_atstring | null終了状態に達した時刻。それまでは null
result の値:
値説明
pending定義済み。Agent はまだ作業を開始していません
runningAgent が作業または修正中
evaluating評価スレッドが評価中
satisfied終了。すべての基準を満たしました
max_iterations_reached終了。最大回数に達しても成果物が合格しませんでした
failed終了。タスクが rubric を満たせないと評価スレッドが判定した場合(例:description が rubric と矛盾)、または判定を返さなかった場合
interrupted終了。キャンセル、中断、またはサーバーによる回収

評価イベント

各評価回の記録はイベントストリーム(イベント一覧またはストリーミング)から取得できます。
イベントフィールド説明
span.outcome_evaluation_startoutcome_id, iteration評価開始
span.outcome_evaluation_ongoingoutcome_id, iteration評価中。間隔は固定ではないため、タイムアウトの判断には使わないでください
span.outcome_evaluation_endoutcome_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 に戻る
1 件の Outcome は複数の 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 フローと同じ流れです。
  1. evaluated_permission: ask の agent.tool_use と、stop_reason.type: requires_action の session.status_idle が発行されます。
  2. クライアントは stop_reason.event_ids のイベント ID を使って user.tool_confirmation を送信します。
  3. 確認後に評価が続きます。
確認待ちの間も Session の 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 が発行されます。
直ちに終了するには Session をキャンセルします。

リクエスト制約

制約結果
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
Session が idle でも有効な Outcome が残る場合があります(Agent turn のエラーを参照)。user.define_outcome を送る前に、Session が idle で有効な Outcome がないことの両方を確認します。
curl -s "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  | jq '{status, active_outcomes: [.outcome_evaluations[] | select(.completed_at == null)] | length}'
Outcome は user.define_outcome イベントでのみ定義でき、Session 作成時のフィールドではありません。Deployment の initial_events にこのイベントを指定できます。

成果物の取得

Agent が DeliverArtifacts で交付したファイルは現在の Session に属します。成功すると、ストリームに agent.artifact_delivered が発行されます。
# List the Session's files
curl -s "https://api.qoder.com/api/v1/cloud/files?scope_id=$SESSION_ID" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

# Get the download URL and download the file
curl -s "https://api.qoder.com/api/v1/cloud/files/$FILE_ID/content" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" | jq -r '.url' | xargs curl -s -o report.html
  • 修正 turn で再交付すると新しい File が作成されます。最後の agent.artifact_delivered の file_id で最終版を取得します。
  • 交付後、一覧に反映されるまで数秒かかる場合があります。
  • Agent が agent.message に直接結果を返す場合もあります。クライアントは両方を処理してください。
エンドポイントは Session の成果物の交付と取得を参照してください。

キャンセルと中断

以下のいずれも有効な Outcome を interrupted にします。
  • Session をキャンセル:POST /api/v1/cloud/sessions/{session_id}/cancel。
  • session_thread_id なしで user.interrupt を送信。Session のキャンセルと同じ効果です。
実行中にタスクを変更する場合は、先にキャンセルしてから新しい Outcome を定義します。

完全な例

# 1. Define the Outcome
curl -s -X POST "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.define_outcome",
        "description": "Analyze this repository for performance problems and write the findings to /data/report.html",
        "rubric": {"type": "text", "content": "/data/report.html exists; it lists the top 3 bottlenecks with evidence; no placeholder content"},
        "max_iterations": 1
      }
    ]
  }'

# 2. Wait for the Outcome to reach a terminal state
until [ "$(curl -s "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  | jq -r '.outcome_evaluations[-1].completed_at // empty')" != "" ]; do sleep 5; done

# 3. Read the verdict
curl -s "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  | jq '.outcome_evaluations[-1] | {result, iteration, explanation}'

# 4. Wait for the wrap-up turn to end
until [ "$(curl -s "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" | jq -r '.status')" = "idle" ]; do sleep 2; done

# 5. List the deliverables
curl -s "https://api.qoder.com/api/v1/cloud/files?scope_id=$SESSION_ID" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" | jq '.data[] | {id, filename}'

推奨事項

状況推奨
合否判定だけが必要max_iterations: 1 とし、rubric に合格条件と失敗条件を明記
判定に基づいて Agent に修正させたいmax_iterations を 1 より大きく設定。評価コストは回数に応じて増加
作業は完了し、検証だけが必要定義しても Agent turn は開始するため、description に既存成果物の検証と修正を指示
交付されたかだけを知りたいOutcome は不要。agent.artifact_delivered と Session 状態を利用

エラー

HTTP 状態原因
400rubric の構造不正、max_iterations が 1–20 の範囲外、64 KiB 超過、outcome_id など禁止フィールド、user.message またはツール結果と同じリクエストで送信
404Session が存在しない、または rubric.file_id が参照するファイルが存在しない
409Session が turn を処理中、または有効な Outcome が存在