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

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

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

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

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

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

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

手元に叩き台がないときは、良い成果物の実例をClaudeに渡し、何が良いのかを分析させて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

見出しごとに評価領域を分け、各行を真偽判定に落とす書き方です。グレーダーはこの各行を独立に採点します。

送る前にRubricを機械的に点検する

アップロード前に、基準の数と「1行に複数の条件が入っていないか」「曖昧な語が残っていないか」を数えておくと、書き直しの手間が減ります。次のスクリプトは、行頭が- の行を基準として数え、and・or・カンマを含む行と、reasonableなどの語を含む行を拾うだけの簡易な点検です。

cat > lint.sh <<'EOF'
#!/bin/bash
f=$1
echo "criteria: $(grep -c '^- ' "$f")"
echo "--- 複数条件の疑い"
grep -n '^- ' "$f" | grep -E ' (and|or) |, '
echo "--- 曖昧語の疑い"
grep -n -i -E 'reasonable|appropriate|good|clear(ly)?|proper' "$f"
EOF
bash lint.sh rubric.md

上の公式サンプルをrubric.mdとして保存し、このスクリプトに通した結果は次のとおりです。

criteria: 12
--- 複数条件の疑い
6:- Growth rate assumptions are explicitly stated and reasonable
9:- COGS and operating expenses are modeled separately
10:- Margins are consistent with historical trends or deviations are justified
13:- WACC is calculated with stated assumptions for cost of equity and cost of debt
14:- Beta, risk-free rate, and equity risk premium are sourced or justified
17:- Uses either perpetuity growth or exit multiple method (stated which)
23:- Sensitivity analysis on WACC and terminal growth rate is included
--- 曖昧語の疑い
6:- Growth rate assumptions are explicitly stated and reasonable
21:- All figures are in a single .xlsx file with clearly labeled sheets

基準は12行で、うち7行が複数条件の疑いに引っかかります。正規表現で拾っただけなので、すべてが本当に複数判定とは限りません。たとえば6行目の「stated and reasonable」は、「明記されている」と「妥当である」の2つの判定が1行に入っています。後者の「妥当」は、グレーダーが何を基準にするのか読み手には決められない語でもあります。公式のサンプルであっても、1行1判定に整える余地は残っているわけです。

Rubricを渡す2つの方法

渡し方は2通りあり、使い方で選びます。

アップロードは次のとおりです。

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というベータヘッダーが必要です。SDKを使う場合は、このヘッダーが自動で付きます。メモリーストアのエンドポイントだけはagent-memory-2026-07-22を使い、2つを併記すると400エラーになります。

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

セッションと環境をあらかじめ作成した状態で、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

max_iterationsは省略可能で、デフォルトは3、上限は20です。セッション作成のリクエストに含める方法もあります。initial_eventsにuser.define_outcomeを1件入れれば、セッション作成とアウトカム設定が1回の呼び出しで済みます。

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

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

アウトカムが動いている最中でも、user.messageを送ってエージェントの作業を誘導できます。ただし必須ではなく、エージェントは成功するか反復を使い切るまで自力で進みます。user.interruptを送ると現在のアウトカムの作業が止まり、結果はinterruptedになります。そのあとで、新しいアウトカムを始め直せます。グレーダーの内部の推論は公開されず、動作中であることだけがイベントで見えます。

評価の開始・ハートビート・終了イベントの中身や、ストリームとポーリングの使い分けは、Managed Agentsのアウトカム評価イベントを監視するで扱っています。

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

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

DCFモデル作成でループを追う

公式のDCF例を使い、反復が2回で終わる場合を時系列にしてみます。評価のiterationは0始まりで、0が最初の評価、1が1回目の修正後の再評価です。ここでの修正内容は説明用の想定で、公式の出力例ではありません。

5回を使い切っても満たせなければ、max_iterations_reachedとなり、確認ターンを1回挟んで終わります。そのときは、最後の評価でsatisfiedが出ないまま終わります。

Rubricの書き方は反復の回り方に響きます。「感応度分析シートを含める」のように書いてあれば、グレーダーが何を指してneeds_revisionにしたのか読み取れます。「適切な分析を含める」では、公式が注意する「ノイズの多い評価」になりやすい書き方です。

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

• 基準1行につき1判定にします。複数の条件を1行に詰めると、片方だけ満たした場合の扱いが曖昧になります。前節のスクリプトで疑わしい行を洗い出せます
• 数値や形式は具体的に書きます。「適切なファイル形式」ではなく、「単一の.xlsxファイルで、シートにラベルが付いている」まで踏み込みます
• DescriptionとRubricを矛盾させません
• 複雑な成果物では、max_iterationsのデフォルト3回が足りるかを見積もります。上限は20です

Outcomeを使うか、通常の会話型セッションで足りるか

すべてのタスクにアウトカムが要るわけではありません。作業の性格で、素のuser.messageでエージェントを誘導するほうが向く場面もあります。

判断に迷ったときは、「この成果物が合格かどうかを、自分でチェックリストにして判定できるか」を試します。チェックリストにできるならRubricに落とせます。できないなら、アウトカムなしで探索させて、完成イメージが固まってからRubricを書く進め方もあります。

Rubric採点はセッション運用のどこにあたるか

Rubricによるアウトカム評価は、セッション全体の一部です。エージェントの動作は通常のイベントストリームに、評価の経過はspan.outcome_evaluation_*という専用イベントに流れ、両者は別のイベント種別です。Managed Agentsがセッション・ハーネス・サンドボックスを分離する設計思想は、Agent SDKのManaged Agentsの設計思想で解説しています。

セッションがidleになったあとの成果物は、サンドボックスの/mnt/session/outputs/に書かれています。取り出すにはFiles APIの一覧にscope_idとしてセッションIDを渡し、返ってきたIDでダウンロードします。この絞り込みにはmanaged-agents-2026-04-01のベータヘッダーが必要です。ファイルはアイドル後も数秒遅れて一覧に載ることがあり、見当たらなければ少し待って一覧を取り直します。

まとめ

まずは自分でチェックリストにできる成果物を1つ選び、lint.shで1行1判定に整えたRubricを送るところから始める、という進め方があります。needs_revisionが返ったら、explanationに書かれた不足を、次のRubricの書き直しにそのまま使えます。