Managed Agents パブリックベータに Outcomes・Multiagent・Webhooks が追加

2026年05月07日 01:05 JST anthropics/skills

https://github.com/anthropics/skills/pull/1096

managed-agents-2026-04-01 ベータヘッダーの傘下に、セッションをルーブリック評価ループで自動反復する Outcomes、複数エージェントを協調させる Multiagent、状態変化をプッシュ通知する Webhooks の3機能が新たに追加された。あわせてスキル上限の訂正（64→20）やCredentials SDK メソッドの追加など、既存リファレンスの修正も含まれる。

背景

これまでの Managed Agents リファレンスは、単一エージェントが1セッションを担うモデルを前提としていた。PR の SKILL.md 読み進めガイドには (core, environments, tools, events, memory, client-patterns, onboarding, api-reference) と列挙されており、Outcomes・Multiagent・Webhooks に対応するリファレンスページが存在しなかった。今回の変更はこの3機能のドキュメントを追加し、既存ページへのクロスリファレンスポインタを整備することで、Managed Agents の claude-api スキルがパブリックベータの全機能に回答できる状態に引き上げるものだ。

同時に、スキル上限が 64 から 20 に、ツール上限が 50 から 128 に訂正されており、既存リファレンスの数値が実際の制約と乖離していたことが示されている。

技術的な変更

Outcomes — ルーブリック評価によるイテレーションループ

Outcomes は、セッションを「会話」から「成果物の生成」に昇格させる仕組みだ。user.define_outcome イベントを送ると、エージェントが作業を開始し、独立したコンテキストウィンドウを持つ グレーダー がルーブリックの各基準を採点してフィードバックを返す iterate → grade → revise ループが回る。

Outcomes は sessions.create() のフィールドではなく、通常のセッション作成後に user.define_outcome イベントを送ることで起動する。user.message を別途送る必要はなく、イベント受信後にエージェントが即座に作業を開始する。

client.beta.sessions.events.send(
    session_id=session.id,
    events=[
        {
            "type": "user.define_outcome",
            "description": "Build a DCF model for Costco in .xlsx",
            "rubric": {"type": "text", "content": RUBRIC_MD},
            # or: "rubric": {"type": "file", "file_id": rubric.id}
            "max_iterations": 5,  # optional; default 3, max 20
        }
    ],
)

ルーブリックは text（インライン Markdown）または file（files-api-2025-04-14 で事前アップロードしたファイルID）で指定できる。max_iterations のデフォルトは 3、最大 20。イベントストリームには span.outcome_evaluation_start / _ongoing / _end が流れ、_end の result フィールドでループ終了状態を確認できる。割り込み（user.interrupt）が入ると span.outcome_evaluation_end.result: "interrupted" が記録される。

Multiagent — コーディネーターとスレッド

Multiagent は、コーディネーターエージェントがロスター上のサブエージェントに委譲する仕組みだ。全エージェントがコンテナとファイルシステムを共有しつつ、各サブエージェントは独自の スレッド（会話履歴・モデル・システムプロンプト・ツールを持つコンテキスト分離イベントストリーム）で動作する。スレッドは永続的で、コーディネーターが過去に呼んだサブエージェントに再度メッセージを送ると、そのサブエージェントは以前のターンを保持した状態で応答する。

multiagent は agents.create() / agents.update() の トップレベルフィールドであり、tools[] のエントリではない。ロスターは 1〜20 エントリで、以下の3種類の形式が使える：

文字列ショートハンド ("agent_abc123") — 最新バージョンを参照
エージェント参照 ({type: "agent", id, version?}) — バージョン固定可
セルフ参照 ({type: "self"}) — コーディネーター自身のコピーを生成

orchestrator = client.beta.agents.create(
    name="Engineering Lead",
    model="{{OPUS_ID}}",
    tools=[{"type": "agent_toolset_20260401"}],
    multiagent={
        "type": "coordinator",
        "agents": [
            reviewer.id,
            {"type": "agent", "id": test_writer.id, "version": 4},
            {"type": "self"},
        ],
    },
)

セッションレベルのイベントストリームはコーディネーターのトレースとサブエージェントの要約（スレッドステータス遷移・クロススレッドメッセージ）を表示する。個別スレッドへのドリルダウンは sessions.threads.list / retrieve / archive と sessions.threads.events.list / stream で行う。委譲は 1段階のみ（depth > 1 は無視）という制約がある。

Webhooks — HMAC 署名付きプッシュ通知

Webhooks は、SSE ストリームを保持したりポーリングする代わりに、Anthropic 側からセッション等のリソース状態変化を HTTPS エンドポイントへプッシュする仕組みだ。ペイロードは thin（イベントタイプ＋リソース ID のみ）で、受信後に実際のリソースをフェッチするパターンが想定されている。

エンドポイントの登録は Console のみ（Console → Manage → Webhooks）で、現時点でプログラマティックな API は提供されていない。署名の検証には SDK の client.beta.webhooks.unwrap() を使用する。これは署名検証・5分超の古いペイロードの拒否・パース済みイベントの返却を一括で行い、ANTHROPIC_WEBHOOK_SIGNING_KEY 環境変数から whsec_ プレフィックス付きシークレットを読み取る。

@app.route("/webhook", methods=["POST"])
def webhook():
    try:
        event = client.beta.webhooks.unwrap(
            request.get_data(as_text=True),
            headers=dict(request.headers),
        )
    except Exception:
        return "invalid signature", 400

    if event.id in seen_event_ids:  # dedupe retries
        return "", 204
    seen_event_ids.add(event.id)

    match event.data.type:
        case "session.status_idled":
            session = client.beta.sessions.retrieve(event.data.id)

event.id はペイロードごとではなく イベントごとに付与されるため、リトライ重複排除は event.id をキーにする。なお、Webhooks は「Anthropic → 開発者」方向の通知であり、「外部サービス → セッション起動」のような逆方向のトリガーは通常のアプリケーションコードで実装する。

API リファレンスの更新

Session Threads が SDK メソッドテーブルと HTTP エンドポイントテーブルに追加された。また、Session Threads は「archive のみ（delete なし）」のリソースとして命名規則の注記に加わった。

変更前:

- Agents have **no delete** — only `archive`.

変更後:

- Agents and Session Threads have **no delete** — only `archive`.

Credentials には mcp_oauth_validate が追加された（SDK: vaults.credentials.mcp_oauth_validate / HTTP: POST /v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate）。スキル上限は managed-agents-core.md・managed-agents-tools.md・managed-agents-onboarding.md の全3ファイルで 64 → 20 に修正された。

設計判断

user.define_outcome をセッション作成時ではなくイベントとして送る設計は、Outcomes を既存のセッションライフサイクルに非侵襲的に組み込む判断といえる。セッション作成フローを変えずに通常の sessions.create() → イベント送信というパターンを踏襲しており、Outcomes を使わないセッションへの影響がない。

Multiagent ロスターをエージェント設定（agents.create）のフィールドとして持つ設計は、委譲関係をエージェント定義に閉じ込め、sessions.create() 時に追加パラメータが不要になる。ロスターはエージェントと一緒にバージョン管理・更新でき、セッション作成ごとに指定し直す必要がない。

Webhooks のペイロードを thin（ID のみ）にして受信後にフェッチさせる設計は、デリバリのリトライや順序保証の複雑さを回避しつつ、受信側が常に最新状態を取得できることを保証する。「IDを受け取ってリソースをフェッチ」というパターンは冪等であり、重複排除（event.id によるデデュープ）と組み合わせることで at-least-once デリバリに安全に対応できる。

まとめ

この PR は、managed-agents-2026-04-01 ベータの3機能（Outcomes・Multiagent・Webhooks）をリファレンスドキュメントとして claude-api スキルに追加し、スキル上限の訂正を含む既存リファレンスの整合性も修正した変更だ。各機能が既存のセッションモデルや SDK 呼び出しパターンを拡張する形で設計されており、Managed Agents の利用範囲が単一エージェントの会話から、複数エージェントの協調・成果物の自動評価・イベント駆動の非同期処理へと広がったことを示している。