【速報】Claude Managed Agents Outcomes試してみた
こんにちは、せーのです。
サンフランシスコで開催された Code with Claude developers' conference をはじめとして、Claude の開発者向け発表がまとまって出ています。本記事は、そのなかでも Claude Managed Agents の「Outcomes」 に焦点を当て、公式情報を読んだうえで Python SDK から実際に API を叩いてみました。
Outcomes とは
Outcomes は、Claude Managed Agents において「セッションを会話だけで終わらせず、仕事として完了させる」ための仕組みです。
ざっくり言うと、ユーザーが ゴールの説明（description） と ルーブリック（採点基準） を渡すと、エージェントが成果物を作り、グレーダーがルーブリックに沿って合否とギャップを評価します。評価が needs_revision なら、フィードバックを踏まえてエージェントがもう一度作り直し……という反復が、満足するか上限イテレーションに達するまで続きます。グレーダーは メインエージェントとは別のコンテキストウィンドウで動く、という説明が公式側にもあります。
一方、従来イメージの強い Managed Agents は「エージェントにタスクを渡して実行させる」が中心でした。
つまり、手作業で組んでいたAgent loopが公式の機能として実装された、というわけですね。
公式が強調しているポイント（抜粋）
- Public Beta として位置づけられており、Managed Agents beta に含まれる形で利用イメージが広がっている、という整理が記事・ドキュメントから読み取れます。
- セッションに
user.define_outcomeイベントを送ると、追加のuser.messageなしでエージェントが作業を開始する、という流れがドキュメント上の中心です。 - Anthropic のブログでは、構造化ファイル生成のテストにおいて、標準的なプロンプティングループと比べて成功率が改善した、という数字も紹介されています（例:
.docxで +8.4%、.pptxで +10.1% など。再現や条件は元記事を参照ください）。
ユースケースとしては、.docx / .pptx / .xlsx などのフォーマット準拠、コード品質、分析レポートの要件充足、ブランドガイドラインなど「採点可能な基準」に落とせる仕事が相性よさそう、と個人的には読みました。
やってみた
今回は 「財務分析レポートの .xlsx をルーブリックで評価しながら自動生成」 というシナリオで試してみました。実行日は 2026-05-07、セッション ID は sesn_011CamoGhUYi9x1Mgs4cGMc2 でした。尚、速報性を重視するため、英語で回します。
大枠は「Agent / Environment を作る → ルーブリックをテキストで渡す → user.define_outcome を送る → sessions.events.stream で span.outcome_evaluation_* を観察 → Files API で成果物を取る」という流れです。
実験で動かしたコード（抜粋）
以下は 実際に実行したスクリプトの要点だけ 抜き出したものです（import やエラーハンドリングなどは省略）。どの API が「何の役割か」を追いやすいように、ブロックごとにコメントを付けます。
1. Agent を作る（誰が・どこに書き出すか）
Managed Agent の定義です。名前・モデル・system プロンプトと、ツールとして agent_toolset_20260401（エージェント用ツール一式）を指定しています。system では「財務アナリストとして Excel を作れ」「出力は必ず /mnt/session/outputs/」と縛っています。後から Files API で拾うファイルは、このパス配下に出てくる想定です。
agent = client.beta.agents.create(
name="Financial Analyst",
model="claude-sonnet-4-6",
system="""You are a financial analyst.
Create detailed financial models in Excel format.
Write output files to /mnt/session/outputs/""",
tools=[{"type": "agent_toolset_20260401"}],
)
print(f"Agent created: {agent.id}")
2. Environment を作る（openpyxl などを載せた実行環境）
エージェントが動く クラウド環境 に、pip で入れたいパッケージを載せます。ドキュメントによっては packages= を直接渡す例がありますが、手元の SDK では config のネストで渡す必要がありました（ここがドキュメントとズレたポイントのひとつです）。
environment = client.beta.environments.create(
name="excel-env",
config={
"type": "cloud",
"packages": {
"type": "packages",
"pip": ["openpyxl", "pandas", "xlsxwriter"],
},
},
)
print(f"Environment created: {environment.id}")
3. ルーブリック（採点基準）と Outcome の送信（ここが Outcomes の核心）
RUBRIC は マークダウン文字列として「データが何年分あるか」「数式かハードコードか」「見た目」などを 検証可能な文で書いています。このあと user.define_outcome だけ送るので、通常のチャットの user.message は不要です。max_iterations は評価ループの上限です。
RUBRIC = """
# Financial Report Rubric
## Data Coverage
- Contains revenue figures for at least 3 years
- Includes both revenue and cost breakdown
- All numeric values are actual numbers (not placeholder text)
## Calculations
- All cells with formulas are working (not hardcoded values)
- Growth rates are calculated as percentage change from previous year
- Totals match the sum of individual line items
## Presentation
- File is saved as .xlsx format
- Sheet has clear column headers (Year, Revenue, Costs, etc.)
- Summary row at the bottom shows totals
"""
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
title="Financial Report with Outcome",
)
client.beta.sessions.events.send(
session_id=session.id,
events=[{
"type": "user.define_outcome",
"description": "Create a simple financial summary report in .xlsx format with 3 years of revenue data",
"rubric": {"type": "text", "content": RUBRIC},
"max_iterations": 3,
}],
)
4. ストリームで「評価が始まった／終わった」を観察する
sessions.events.stream でイベントを読みます。span.outcome_evaluation_start / end で 何回目の採点かと **result（satisfied など）**が取れます。agent.message はエージェントのテキスト出力で、ターミナルにログが流れます。後述のとおり、確実な result はこの span.outcome_evaluation_end 側を見るのがよかったです。
with client.beta.sessions.events.stream(session.id) as stream:
for event in stream:
match event.type:
case "span.outcome_evaluation_start":
print(f"\n=== Evaluation iteration {event.iteration} started ===")
case "span.outcome_evaluation_end":
print(f"Result: {event.result}")
print(f"Explanation: {event.explanation[:200]}...")
if event.result in ("satisfied", "failed", "max_iterations_reached"):
break
case "agent.message":
for block in event.content:
if hasattr(block, "text"):
print(block.text, end="", flush=True)
5. 成果物を Files API で一覧・ダウンロードする
セッション ID を scope_id に渡して、セッション内に出たファイルを列挙します。手元では extra_headers に managed-agents-2026-04-01 を付けないと list が通らないケースがありました。download にも同じヘッダーを付けています。
MA_HEADER = {"anthropic-beta": "managed-agents-2026-04-01"}
session = client.beta.sessions.retrieve(session.id)
files = client.beta.files.list(
scope_id=session.id,
extra_headers=MA_HEADER,
)
for f in files.data:
content = client.beta.files.download(f.id, extra_headers=MA_HEADER)
content.write_to_file(f"/tmp/{f.filename}")
以上が「今回の実験で実際に回した処理」の骨格です。このあと続く iteration の話は、まさしく 上記ルーブリックの「Calculations」節をグレーダーがどう解釈したかが焦点になります。
iteration の流れ
ここでいう iteration（何回目の採点か）は、成果物ファイルに埋め込まれる値ではなく、sessions.events.stream で届く span.outcome_evaluation_* イベントの event.iteration です。記事のサンプルでは print でターミナルに出していますが、取り方はアプリ側次第です。
iteration 0 は needs_revision でした。エージェントは pip install openpyxl から入り、Python で .xlsx を生成して /mnt/session/outputs/ に保存する、という筋はきちんと踏めていました。数値も見た目も悪くないのに、グレーダーが実ファイルを開いて確認したところ、ワークブック内に Excel の数式セルが 1 つもなく、すべてハードコードの数値だった、と判定されました。ルーブリックに「All cells with formulas are working (not hardcoded values)」と書いていたので、ここが未充足扱いになった、という筋が通ります。
iteration 1 で satisfied になりました。エージェントは formula 前提の Python を書き直し、=SUM($C$7:$C$10) のような実数式を多数のセルに設定し直したあと、再評価で全条件を満たした、という流れです。iteration 2 は、そこで終わったので走っていません。
グレーダーの explanation（抜粋）
iteration 0 の needs_revision では、だいたい次のような説明でした（英語のまま引用しています）。
However, the rubric explicitly requires 'All cells with formulas are working (not hardcoded values),' and inspection of the file reveals that every single cell contains a hardcoded number — there are zero Excel formulas anywhere in the workbook.
つまり「数値の足し合わせは合っているが、ルーブリックが求めている“式として動いている”状態ではない」が理由だと推測できます。
iteration 1 の satisfied では、3 年分の売上・コスト、数式ベースの合計と前年比、.xlsx とヘッダー、といった項目が列挙されたうえで、すべて met と判定されていました。
最終的な result
satisfied で完了しました。評価が回ったのは iteration 0 と 1 の 2 回で、max_iterations_reached にはなっていません。
最終的にExcelファイルが作られました。
ハマりどころと気づき
Environment の packages= は、手元の SDK ではドキュメントどおりに直渡しできず、config 経由で pip パッケージを渡す必要がありました。仕様とサンプルのズレはベタ期によくあるやつです。
Files API の一覧は、client.beta.files.list(scope_id=session.id) だけでは手元では弾かれ、anthropic-beta: managed-agents-2026-04-01 を extra_headers で明示したら動きました。download 側も同じヘッダーが必要です。
session.outcome_evaluations を retrieve で取り直したところ、outcome_id や result が空に見えた、という現象もありました。ストリーム中の span.outcome_evaluation_end から直接 result と explanation を拾う方が確実、という学びです。
あと、iteration 0 の途中では ImportError が一度出たのですが、Outcomes の差し戻しとは別に、エージェント側で import を直して続行していました。実行時エラーの自己修正は、ルーブリック評価とは独立に走るんだな、と観察しました。
グレーダーは数値の整合だけでなく、ファイルの中身（式があるかどうか）まで見にいくので、「きれいに見える成果物」と「ルーブリック上の合格」はズレる、というのは体感としておもしろかったです。
注意点（ベータ前提）
- API キーと Managed Agents 向けの ベータヘッダー（
managed-agents-2026-04-01）は、エンドポイントによっては SDK のデフォルトだけでは足りないことがあります。今回の Files 一覧がその例です。 - 成果物は
/mnt/session/outputs/に書き出す前提に合わせるのが安全です。ここを外すと「動いたのにファイルが取れない」が起きやすいタイプだと推測できます。 - ルーブリックは 検証可能な文に落としたほうがよく、今回のように「式で動いていること」まで書けると、グレーダーがズレにくいです。
まとめ
Outcomes を使ってみて感じたのは次のとおりです。
- 要点: ゴールとルーブリックを渡すと、独立したグレーダーが評価し、差し戻しつつ寄せていける。
- ユースケース: 「見た目は正しいが中身が違う」系の成果物に強い。検証可能な基準が書けるタスクほど相性がよさそうです。
- 注意点: ルーブリック設計と API のベータ挙動（ヘッダーや SDK シグネチャ）をセットで見る必要がある。評価ループ自体にもコストが乗る、という意識も必要です。
ユースケースは選ぶものの採点基準が明確に示せるものであれば、かなり使いやすくなるのではないでしょうか。
