Managed AgentsのRubricでアウトカムを定義する方法

Managed Agentsのセッションに「完成の定義」を渡すと、エージェントは自己評価しながら完成まで反復します。この完成の定義がRubric(採点基準)です。Rubricを書き、セッションにuser.define_outcomeイベントとして渡すところまでを実装順に説明します。

Managed Agentsのアウトカムとは何か

アウトカムは、セッションに「最終的な成果物がどう見えるべきか、どう品質を測るか」を伝える仕組みです。アウトカムを定義すると、ハーネスは自動的にグレーダー(grader、採点役)をプロビジョニングし、Rubricに基づいて成果物を評価します。

グレーダーはメインのエージェントとは別のコンテキストウィンドウで動きます。実装の途中経過に引きずられず、成果物そのものを見て採点するための設計です。グレーダーは各基準の合否をまとめた説明を返し、その内容は次のイテレーションに向けてエージェントへ渡されます。ここが通常のセッションとの決定的な違いです。ゴールを人間が言語化するだけで、達成度の判定まで機械が引き受けます。

Rubricの書き方 — 採点可能な基準に分解する

Rubricは採点基準を書いたMarkdown文書です。必須項目であり、省略はできません。

グレーダーは基準を1つずつ独立に採点します。したがって「データが良さそう」のような曖昧な基準はノイズの多い評価しか生みません。「CSVにpriceという数値列が含まれる」のように、機械的に真偽判定できる粒度まで具体化する必要があります。

手元にRubricの叩き台がないときは、良い成果物の実例をClaudeに渡し、「何が良いのかを分析してRubric化して」と頼む方法が効きます。ゼロから基準を書き下すより、実例からの逆算のほうが精度の高いRubricになりやすいアプローチです。

以下は公式ドキュメントが示すDCFモデル(ディスカウント・キャッシュフローモデル、企業価値評価の手法)採点用Rubricの例です。

# 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

見出しごとに評価領域を分け、各行を独立した真偽判定に落とし込んでいる点に注目してください。「収益予測」「コスト構造」「割引率」「ターミナルバリュー」「出力品質」という5領域が、そのままグレーダーの採点票になります。

Rubricを渡す2つの方法 — インラインテキストとFiles API

Rubricはuser.define_outcomeイベントに直接テキストとして埋め込むか、Files APIへ事前アップロードしてIDで参照するかのどちらかで渡します。1回限りの利用ならインライン、複数セッションで使い回すならFiles APIが向きます。

rubric=$(curl -fsSL https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -F file=@/tmp/rubric.md)
rubric_id=$(jq -r '.id' <<<"$rubric")

Managed Agents API全体の前提として、リクエストにはmanaged-agents-2026-04-01というベータヘッダーが必要です(メモリーストアのエンドポイントのみagent-memory-2026-07-22を使う例外があります)。SDKを使う場合はこのヘッダーが自動で付与されます。

セッションにアウトカムを渡して起動する

セッションと環境をあらかじめ作成した状態で、user.define_outcomeイベントを送るとエージェントは即座に作業を開始します。追加のユーザーメッセージは不要です。

# セッションを作成
session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  --json @- <<EOF
{
  "agent": "$agent_id",
  "environment_id": "$environment_id",
  "title": "Financial analysis on Costco"
}
EOF
)
session_id=$(jq -r '.id' <<<"$session")
 
# アウトカムを定義 — 受信と同時にエージェントが作業を開始する
curl -fsSL "https://api.anthropic.com/v1/sessions/$session_id/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  --json @- >/dev/null <<EOF
{
  "events": [
    {
      "type": "user.define_outcome",
      "description": "Build a DCF model for Costco in .xlsx",
      "rubric": {"type": "text", "content": "# DCF Model Rubric\n..."},
      "max_iterations": 5
    }
  ]
}
EOF

rubricは{"type": "file", "file_id": "..."}の形でも渡せます。max_iterationsは省略可能で、デフォルト3、上限20です。イベント作成のリクエスト自体をセッション作成に含める方法もあります。initial_eventsにuser.define_outcomeを1件入れれば、セッション作成とアウトカム設定を1回の呼び出しで済ませられます。

採点ループが回るとき何が起きているか

max_iterationsを超えて反復し続けることはありません。グレーダーが返すresultの値に応じて、セッションの次の挙動が決まります。

failedは「基準を満たさなかった」ではなく「そもそも採点が成立しなかった」ケースを指す点に注意してください。DescriptionとRubricの内容が食い違っていると、グレーダーは基準の適用先を判断できずこの結果を返します。

1セッションに保持できるアウトカムは1つ

同時に評価できるアウトカムは1つだけです。複数のゴールを順番に達成させたい場合は、直前のアウトカムの終端イベント(span.outcome_evaluation_end)を確認してから、新しいuser.define_outcomeを送って連鎖させます。最終評価のあとは、セッションを通常の会話セッションとして継続することも、新しいアウトカムを始めることもできます。過去のアウトカムの履歴はセッションに残ったままです。

具体例で流れを追う — DCFモデル作成を最初から最後まで

ここまでの手順を、公式ドキュメントのDCFモデル例に沿って時系列でつなげてみます。

まず/tmp/rubric.mdに前述のDCF Model Rubricを書き、Files APIへアップロードしてrubric_idを取得します。次にエージェントと環境をひも付けたセッションを作成し、user.define_outcomeイベントを送ります。Descriptionは「Build a DCF model for Costco in .xlsx」、Rubricは先ほどのrubric_id、max_iterationsは5に設定したとします。

イベント受信と同時にエージェントが着手し、財務データを収集してExcelファイルを組み立てます。作業が一区切りつくと1回目の評価(iteration: 0)が走ります。ここで、たとえば感応度分析シートが欠けていたとすると、グレーダーはneeds_revisionを返し、explanationに「Sensitivity analysis sheet is missing」のような指摘が入ります。この指摘はそのままエージェントへのフィードバックとして機能し、エージェントは指摘された不足分だけを補って再提出します。

2回目の評価(iteration: 1)で全12基準が満たされればsatisfiedが返り、セッションはidleへ遷移します。ここまでで反復は2回、max_iterationsの5回のうち3回を残した状態で完了しています。もし5回を使い切っても基準を満たせなければ、max_iterations_reachedで確認ターンを挟んで終了し、成果物は未達成のまま人手のレビューに回すことになります。

この一連の流れが示しているのは、Rubricの書き方1つで反復回数が大きく変わるということです。「感応度分析シートを含める」のように具体的に書いておけば1回で通ることもあれば、「適切な分析を含める」のように曖昧に書けば、グレーダーが何を指してneeds_revisionにしているのか毎回変わり、反復が長引きます。

Rubric設計でつまずきやすい点

Rubricの精度は、そのままグレーダーの採点精度に跳ね返ります。設計段階で押さえておきたい点は次の5つです。

• 基準1行につき1判定にする。複数の条件を1行に詰め込むと、片方だけ満たした場合の扱いが曖昧になります
• 数値や形式は具体的に書く。「適切なファイル形式」ではなく「単一の.xlsxファイルで、シートにラベルが付いている」まで踏み込みます
• DescriptionとRubricを矛盾させない。failedの主因はここです。作業の目的(Description)と採点基準(Rubric)は同じ成果物を指していなければなりません
• 反復回数の見積もりを甘くしない。複雑な成果物ほどneeds_revisionが重なりやすく、デフォルトの3回ではmax_iterations_reachedに到達しがちです
• 基準の順序を評価の優先度と一致させる。Rubricの見出し順がそのまま採点の切り口になるため、致命的な基準ほど先頭に置くと、途中で終了した場合でも重要な不足に気づきやすくなります

Outcomeを使うべきか、通常の会話型セッションで十分か

Managed Agentsのすべてのタスクにアウトカムを設定する必要はありません。作業の性格によって、素のuser.messageでエージェントを誘導する通常運用のほうが向く場面もあります。

判断に迷ったときの目安は、「この成果物が合格かどうかを、あなた自身がチェックリストで判定できるか」です。チェックリスト化できるならRubricに落とし込めますが、できないならまずアウトカムなしで探索させ、完成イメージが固まった段階でRubric化するほうが手戻りが少なくなります。

Rubric採点はセッション運用のどこに位置するか

Rubricによるアウトカム評価は、Managed Agentsのセッションライフサイクル全体の一部分にすぎません。エージェントの動作そのものを追いたい場合はイベントストリームの監視が必要で、評価だけを切り出して追いたい場合は評価専用のイベントを見る必要があります。両者は別の関心事として設計されており、それぞれのイベント種別も異なります。アウトカム評価イベントの詳細と運用中の監視手順は、Managed Agentsのアウトカム評価イベントを監視するで扱っています。

セッション・ハーネス・サンドボックスを分離するManaged Agentsそのものの設計思想は、Agent SDKのManaged Agentsの設計思想で解説しています。Rubricによる自己評価ループは、この分離アーキテクチャの上に成り立つ機能の1つです。

まとめ

RubricはManaged Agentsに「完成」を数値化して渡す唯一の手段です。採点可能な粒度まで基準を分解し、user.define_outcomeイベントでセッションに渡せば、あとはsatisfiedかmax_iterations_reachedに達するまでエージェントが自律的に反復します。DescriptionとRubricの整合を保つことと、基準を1行1判定に保つことが、failedや無駄な反復を避ける近道です。

最初のRubricを完璧に書き切ろうとする必要はありません。まず粗くても採点可能な形で走らせ、needs_revisionのexplanationを見ながら基準の粒度を調整していくほうが、机上でRubricを練り込むより早く実用的な精度にたどり着きます。反復のたびに得られるexplanationはグレーダーからのフィードバックであると同時に、次のRubric改訂に使える一次情報でもあります。