Claude Managed Agents入門｜3層構造を理解して自律AIエージェントを自分で構築する

要約

2026年4月8日にAnthropicがパブリックベータとして公開した「Claude Managed Agents」は、エージェントループ・サンドボックスコンテナ・状態永続化・観測ログを丸ごと肩代わりするマネージドサービスである。本記事ではAgent / Environment / Sessionの3層アーキテクチャ、組み込みツール8種、料金体系、Pythonでの最小実装コードを、公式ドキュメント準拠で網羅的に解説する。

対象読者: Pythonで業務自動化やAIエージェントを試し始めているエンジニアで、Messages APIで自前のエージェントループを書いた経験がある方。

検証環境: Claude Managed Agents パブリックベータ（2026年4月時点）/ Python SDK anthropic v0.94.1+ / モデル claude-sonnet-4-6

この記事を読むことで得られるメリット

この記事を読むことで以下のことが分かる:

Managed Agentsが自前実装と比べて何を肩代わりしてくれるかが具体的に理解できる
Agent / Environment / Sessionの3層アーキテクチャの責務分離を体系的に把握できる
組み込みツール8種とホワイトリスト方式の最小権限設定を本番運用視点で押さえられる
get-or-createパターンでリソース二重作成を防ぐ実装ノウハウが手に入る
session-hour課金の料金感覚と、SSEストリームを使ったWebアプリ組み込みパターンが学べる

この記事を読むのにかかる時間

約18分

環境

Claude Managed Agents パブリックベータ（2026年4月8日リリース）
Python 3.10以降（match文使用のため）
anthropic Python SDK v0.94.1以降（requires_python=">=3.9"）
モデル: claude-sonnet-4-6（Claude 4.5以降の全モデル対応）
ベータヘッダー: managed-agents-2026-04-01

Claude Managed Agentsとは何か

Claude Managed Agentsは、Claudeを自律的なエージェントとして動作させるためのハーネスおよびサンドボックス実行環境を、Anthropicがマネージドサービスとして提供する仕組みである。

開発者が書くのはAgent定義・Environment定義・Session起動の3箇所のみで、エージェントループ、コンテナ、状態永続化、ログ基盤まで、Anthropic側がすべて肩代わりしてくれる。

自前実装との対比

Messages APIで自律エージェントを実装する場合、以下のループを開発者自身が書く必要がある。

while True:
    response = client.messages.create(
        model="claude-sonnet-4-6",
        messages=messages,
        tools=tool_definitions,
    )
    if response.stop_reason == "end_turn":
        break
    if response.stop_reason == "tool_use":
        tool_result = execute_tool(response.content)
        messages.append({"role": "user", "content": tool_result})

加えて、ツール実行用のサンドボックスコンテナ、会話履歴の永続化DB、実行ログの基盤（CloudWatchやDatadog）、リトライ・復旧処理を別途構築する必要がある。

一方、Managed Agentsでは同じことが以下5行程度で済む。

session = client.beta.sessions.create(agent=agent.id, environment_id=env.id)
with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(session.id, events=[user_message])
    for event in stream:
        handle_event(event)

肩代わりされる7要素

要素	自前実装	Managed Agents
エージェントループ	`while True` + `tool_use`分岐を実装	自動
サンドボックスコンテナ	DockerやKubernetesで構築	Anthropicが提供
会話履歴の永続化	DB設計・実装	Sessionが内部保持
実行ログ基盤	CloudWatch / Datadog構築	Consoleで自動可視化
プロンプトキャッシング	手動チューニング	自動最適化
コンテキスト圧縮	自前で実装	自動圧縮
コンテナ障害復旧	リトライロジック実装	`status_rescheduling`で自動切替

公式ドキュメントの一次ソースは platform.claude.com/docs/en/managed-agents/overview を参照されたい。

3層アーキテクチャ — Agent / Environment / Session

Managed Agentsの中核は、責務を3層に分離した設計である。

Agent層 — 「何者で、何ができるか」を定義する

Agent層は、モデル、システムプロンプト、ツール定義、Skills、MCPサーバー設定を持つステートレスな定義である。

設定項目	役割
`name`	必須。Agentの識別名
`model`	必須。Claude 4.5以降の全モデル対応
`system`	システムプロンプト（`system_prompt`ではない点に注意）
`tools`	組み込みツール、MCPツール、カスタムツールを統合
`mcp_servers`	MCPサーバー接続定義
`skills`	ドメイン知識パッケージ（最大20個）
`callable_agents`	呼び出し可能な他エージェント（Research Preview）
`description`	補助情報（`null`でクリア可）
`metadata`	key-levelマージ。空文字で個別キー削除

エンドポイントは /v1/agents、Python SDKでは client.beta.agents.create() で作成する。

Environment層 — コンテナとネットワーキングを定義する

Environment層は、エージェントがbashを実行する隔離コンテナと、外部通信ポリシー、Vaultをバンドルする。

主な設定項目は以下である。

config.type: 現状 cloud のみ（Anthropicマネージドコンテナ）
config.packages: apt/cargo/gem/go/npm/pipで事前インストール
networking.type: unrestricted（既定）または limited
allowed_hosts: limited時のホワイトリスト
vault_ids: MCPサーバー認証用Vault

エンドポイントは /v1/environments、Python SDKでは client.beta.environments.create() で作成する。

Session層 — タスクごとに起動するインスタンス

Session層は、AgentとEnvironmentを参照して起動するランタイムインスタンスである。1セッション = 1タスクが原則で、毎回新規作成する。

agent: 必須。agent_idまたはインライン定義
environment_id: 必須
resources: 初期ファイル・Markdownなど
vault_ids: MCP認証用Vault
outcome: 完了判定基準（Research Preview）

エンドポイントは /v1/sessions、入出力は events.send() と events.stream() で行う。

3層の処理フロー

1. agents.create + environments.create  ← 永続リソースを1回作成
2. sessions.create                       ← タスクごとに起動
3. events.send(user.message)             ← ユーザー入力を投げる
4. events.stream                         ← SSEイベントを購読
5. session.status_idle 受信 + stop_reason 判定 → 完了 or 追加応答

組み込みツール8種 — `agent_toolset_20260401`

Managed Agentsには、組み込みツール8種がパッケージとして用意されている。agent_toolset_20260401という名前で一括有効化できる。

ツール名	用途
`bash`	コンテナ内でbashコマンド実行
`read`	ファイル読み込み
`write`	ファイル書き込み
`edit`	文字列置換による編集
`glob`	ファイルパターンマッチング
`grep`	正規表現でテキスト検索
`web_fetch`	URLからコンテンツ取得
`web_search`	Web検索

ツール設定の3パターン

ツールの有効化方法には、用途に応じた3つのアプローチがある。

パターン1: 全有効化（最速・PoC向け）

tools = [{"type": "agent_toolset_20260401"}]

パターン2: 個別無効化（差分指定）

tools = [{
    "type": "agent_toolset_20260401",
    "configs": [{"name": "web_fetch", "enabled": False}],
}]

web_fetchだけoffにして、残り7ツールはそのまま使う書き方である。

パターン3: ホワイトリスト方式（本番推奨）

tools = [{
    "type": "agent_toolset_20260401",
    "default_config": {"enabled": False},
    "configs": [
        {"name": "bash", "enabled": True},
        {"name": "read", "enabled": True},
        {"name": "write", "enabled": True},
    ],
}]

default_configで全offにしてから、必要なツールだけを明示的に有効化する。Anthropicが将来新しい組み込みツールを追加しても、勝手に有効化されない設計になる。最小権限の原則（least privilege）を徹底するなら、このパターンを採用するとよい。

ハンズオン題材1: AI Trend Watcher Agent（Python CLI）

実際にManaged Agentsを動かす題材として、AI Trend Watcher Agentを紹介する。

ユースケース

GitHubのプロフィールリポジトリに preferences/favorite-keywords.md（関心キーワード）と preferences/excluded-themes.md（除外テーマ）を置いておく。Managed Agentsがこれを起点にWeb検索・要約・スコアリングを行い、出典URL付きレポートをDiscordに通知する。

データフロー

GitHub Profile Repo (preferences/)
  ├─ favorite-keywords.md
  └─ excluded-themes.md
       ↓
Managed Agents Session
  ├─ Agent (claude-sonnet-4-6 + 組み込みツール)
  └─ Environment (cloud / unrestricted)
       ↓
1. git clone でリポジトリ取得
2. read で keywords / excluded を読込
3. web_search でテーマ別最新情報取得
4. web_fetch で本文取得・要約
5. 重要度スコアリング
6. bash + curl で Discord Webhook に POST
       ↓
Discord チャンネル
  └─ Step別進捗通知 + カテゴリ別レポート

実装コード（最小版）

import anthropic
import os

client = anthropic.Anthropic(
    default_headers={"anthropic-beta": "managed-agents-2026-04-01"}
)

# 1. Agent定義
agent = client.beta.agents.create(
    name="ai-trend-watcher",
    model="claude-sonnet-4-6",
    system=f"""あなたはAIトレンド調査エージェントである。
GitHubの {os.environ['GITHUB_PROFILE_REPO']} から
preferences/favorite-keywords.md と preferences/excluded-themes.md を取得し、
キーワードごとにWeb検索・要約・スコアリングを行い、
最後に curl で {os.environ['DISCORD_WEBHOOK_URL']} に POST せよ。""",
    tools=[{"type": "agent_toolset_20260401"}],
)

# 2. Environment定義
env = client.beta.environments.create(
    config={
        "type": "cloud",
        "networking": {"type": "unrestricted"},
    },
)

# 3. Session起動 + イベントストリーム購読
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=env.id,
)

import httpx
with client.beta.sessions.events.stream(
    session.id,
    timeout=httpx.Timeout(300.0, read=120.0),
) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[{
            "type": "user.message",
            "content": [{"type": "text", "text": "今日のトレンドをDiscordに通知せよ"}],
        }],
    )
    for event in stream:
        match event.type:
            case "agent.tool_use":
                print(f"[TOOL] {event.tool_use.name}")
            case "agent.message":
                print(f"[MSG] {event.message.content}")
            case "session.status_idle":
                if event.stop_reason.type == "end_turn":
                    break

コードのポイント

anthropic-beta ヘッダー: パブリックベータのため managed-agents-2026-04-01 が必須
system パラメータ: system_prompt ではなく system である点に注意
タイムアウトは2段構え: httpx.Timeout(300.0, read=120.0) で全体300秒・無イベント120秒。Managed Agentsは数分かかるタスクが多いため、デフォルトでは途中で切れる
stream を先に開いてから send: 送信直後に返るイベントを取りこぼさないため、公式推奨パターンはストリーム先行・送信後追い
session.status_idle は「終了」ではなく「1ターン完了」: 完了判定は必ず stop_reason.type で行う

ハンズオン題材2: Markdown Review App（Next.js Web）

CLIだけでなく、Webアプリ組み込みの実例も押さえておく。

アーキテクチャ

[ブラウザ React]  ──POST──>  [Next.js API Route]  ──>  [Managed Agents]
       ↑                            │
       └────────SSE中継─────────────┘

3層構成のポイントは以下である。

フロントエンド (React): ユーザー入力を受け取りPOST送信、結果はSSEで逐次表示
API Route (Node.js): ANTHROPIC_API_KEY を握り、Sessionをポーリング、SSEで前段に中継
Managed Agents: Agent / Environment / Sessionを起動してレビュー本体を実行

APIキーをブラウザに露出させないため、必ずサーバー経由で呼び出すのが鉄則である。これはManaged Agents固有の制約ではないが、一般的なセキュリティベストプラクティスである。

`get-or-create`パターンの重要性

Webアプリで気をつけたいのは、agents.create と environments.create が 毎回新規作成される 仕様である点である。リクエストのたびに呼び出すと、Anthropic側にリソースが無限に蓄積されていく。

必ず以下のような get-or-create パターンで、初回のみcreateし、以降は保存済みIDを読み込んで再利用する実装にする。

import json
from pathlib import Path

STATE_FILE = Path(".agent-state.json")

def get_or_create_agent(client):
    if STATE_FILE.exists():
        state = json.loads(STATE_FILE.read_text())
        if "agent_id" in state:
            return client.beta.agents.retrieve(state["agent_id"])
    agent = client.beta.agents.create(name="...", model="claude-sonnet-4-6", ...)
    state = json.loads(STATE_FILE.read_text()) if STATE_FILE.exists() else {}
    state["agent_id"] = agent.id
    STATE_FILE.write_text(json.dumps(state))
    return agent

.agent-state.json の中身は agent_id / agent_version / environment_id の3キー程度の小さなJSONになる。.gitignore への追加も忘れずに行うとよい。

ネットワーキング設定 — `unrestricted`と`limited`

Environmentの networking.type には2モードがあり、デフォルト値の理解が運用上重要である。

モード	挙動	用途
`unrestricted`（既定）	Anthropicのセーフティブロックリスト以外、フルアウトバウンドアクセス許可	デモ・PoC
`limited`	`allowed_hosts` に列挙したホストのみ許可	本番・機密データ

❌ よくある誤解

多くの二次情報で「デフォルトは limited」と書かれているが、これは誤りである。公式ドキュメントの一次ソースでは unrestricted が既定値である（公式ドキュメントの networking テーブルに unrestricted: This is the default. と明記）。

つまり何も設定しないとフルアクセス状態のため、機密データを扱う本番環境では必ず limited への変更を検討する必要がある。

`limited`モードの設定例

env = client.beta.environments.create(
    config={
        "type": "cloud",
        "networking": {
            "type": "limited",
            "allowed_hosts": [
                "https://api.example.com",
                "https://discord.com",
            ],
            "allow_mcp_servers": True,
            "allow_package_managers": True,
        },
    },
)

allow_mcp_servers と allow_package_managers のデフォルトはどちらも False のため、MCPやpip/npmを使う場合は明示的に有効化する必要がある。

Sessionのライフサイクル — 4状態の遷移

Sessionは以下4つの状態を遷移する。

状態	意味	推奨アクション
`running`	思考中・ツール実行中	ストリーム受信を継続
`idle`	1ターン完了・入力待ち	`stop_reason.type` で判定
`rescheduling`	コンテナ障害で別コンテナへ自動復旧中	そのまま待機
`terminated`	異常終了・回復不能	ログ出力・エラー通知

idle は「終わった」サインではなく「1ターン終わった」サインである。完了判定は stop_reason.type を以下のように分岐させる。

case "session.status_idle":
    match event.stop_reason.type:
        case "end_turn":
            break  # 正常完了
        case "requires_action":
            # tool_confirmation や custom_tool_result を送り返す
            send_user_response(...)
            continue

料金体系 — session-hour課金の実例

料金はシンプルで、session-hour課金 + 標準トークン料金 の二階建てである。

active runtime（ツール実行中などの稼働時間）: $0.08 per session-hour
非active runtime（待機時間）: active runtime分のみ課金
これに標準のトークン料金が上乗せ

公式の単位は per session-hour で claude.com/pricing に明記されている。「秒単位」という二次情報の表現があるが、正しくは「時間単位」である点に注意してほしい。

実例

Markdownレビューを1回走らせた例では以下のような料金感である。

項目	値
実行時間	39.9秒
入力トークン	5,600
出力トークン	2,700
session-hour課金	$0.08 × 39.9 ÷ 3600 ≈ $0.0009
トークン料金	およそ$0.06
合計	約$0.06（約9円）

session-hour課金より、トークン料金のほうが支配的である。$5チャージで数十回規模のレビューが回せる計算になる。

SSEストリームを採用する3つの理由

Managed Agentsは双方向通信にREST APIではなくServer-Sent Events（SSE）を採用している。設計上の理由は3つである。

1. 長時間タスクへの対応

エージェント処理は数秒から数十分の長時間タスクが多い。通常のRESTではレスポンス完了まで無応答になるが、SSEなら思考・ツール呼び出し・結果を逐次配信できる。

2. ツール実行中の可視化

通常のRESTではログを自前収集する必要があるが、SSEなら agent.tool_use や agent.tool_result が届くたびに画面更新できる。

3. 双方向性

ポーリングでごまかす必要がなく、sendとstreamを独立チャネルとして併用できる。

イベントの4カテゴリ

ストリームには以下4カテゴリのイベントが流れる。

カテゴリ	方向	代表例
User events	アプリ → Agent	`user.message`, `user.tool_confirmation`, `user.custom_tool_result`
Agent events	Claude → アプリ	`agent.message`, `agent.tool_use`, `agent.tool_result`, `agent.thinking`
Session events	Session → アプリ	`session.status_idle`, `status_running`, `status_terminated`, `session.error`
Span events	観測用	`span.model_request_start`, `span.model_request_end`

match文で分岐させると、Python 3.10以降では特に読みやすく書ける。

Vault — シークレットを安全に扱う仕組み

VaultはAnthropic管理型のシークレットストアで、MCPサーバー認証専用 に設計されている。

公式の表現を引用すると以下の通りである。

Vaults and credentials are authentication primitives that let you register credentials for third-party services once and reference them by ID at session creation.

Vaultのセキュリティ特性

特性	内容
トークン秘匿	エージェントは実際のトークンを一切見ない（Anthropic側プロキシが差し込み）
自動再解決	セッション中に定期的にクレデンシャルを再解決（ローテーション対応）
書き込み専用フィールド	`token` / `access_token` / `refresh_token` / `client_secret` はAPIレスポンスで返らない

Vaultの注意点

Vaultは MCPサーバー認証専用 である。Discord Webhook URLのような任意のシークレットには使えない点に注意してほしい。任意シークレットはシステムプロンプト経由か環境変数経由で渡すのが基本方針となる。

Skills — オンデマンドで読み込まれる専門知識

Skillsは、エージェントがタスクに関連すると判断したときだけコンテキストに注入される、progressive disclosure型の仕組みである。

agent = client.beta.agents.create(
    name="...",
    model="claude-sonnet-4-6",
    skills=[
        {"type": "anthropic", "name": "xlsx"},   # プリビルト
        {"type": "anthropic", "name": "pptx"},
        {"type": "custom", "id": "skill_abc123", "version": "latest"},
    ],
)

種類	例
Anthropicプリビルト	`xlsx` / `pptx` / `docx` / `pdf` など
カスタムスキル	`skill_` で始まるID + version

セッションあたり最大20スキルまで登録できる。明示的なプロンプト指示は不要で、エージェントが自動的に呼び出す。

ベータ版利用時の注意点

バージョン管理の落とし穴

Agentの update 操作には以下の特殊な仕様がある。

updateのたびに version がインクリメント（初期値1）
省略フィールドは保持
配列フィールド（tools / mcp_servers / skills / callable_agents）は完全置換 — 部分指定すると既存要素が消える
スカラーフィールド（system / description）は null 渡しでクリア可
model / name は必須でクリア不可

Rate Limit

種類	制限
作成系（`agents`, `sessions`, `environments`の `create`）	60 req/min
読み取り系（`retrieve`, `list`, `stream`）	600 req/min

Console での観測性

platform.claude.com の管理ダッシュボードで、セッション単位の以下情報が時系列で見られる。

全イベント履歴
ツール呼び出し詳細
トークン消費
実行時間
エラー・リトライ
並列ツール実行のトレース（Claude 4.5+のネイティブ並列ツール使用、Web Search ×3 などが可視化される）

自前実装ではDatadogやCloudWatchで構築する必要がある観測基盤が、追加コストなしで利用できる。

メリットとデメリットの整理

メリット

✅ 自前実装の数百行が5行程度に圧縮できる
✅ プロンプトキャッシング・コンテキスト圧縮が自動最適化される
✅ サンドボックスコンテナがすぐ使える（curl / wget / git / python3 プリインストール済み）
✅ Consoleでセッションの全イベント・ログが時系列可視化される
✅ コンテナ障害時のリトライがマネージド（status_rescheduling）
✅ 料金は active runtime のみ課金で、待機時間は無料相当

デメリット

❌ パブリックベータのため、仕様変更の可能性がある
❌ 定期実行機構は内蔵されていない（cron / GitHub Actions / EventBridge等の外部スケジューラと組み合わせる必要あり）
❌ Vaultは MCPサーバー認証専用で、任意シークレット用途には使えない
❌ ネットワーキングのデフォルトが unrestricted で、明示的に絞り込まないと本番でも緩い設定のまま
❌ agents.create は毎回新規作成されるため、get-or-create パターンの実装が必須

まとめ

Claude Managed Agentsは、自律エージェント実装で最も面倒だった「エージェントループ・コンテナ・状態永続化・観測ログ」を一括で肩代わりするマネージドサービスである。本記事の要点を再掲する。

3層アーキテクチャ: Agent（モデル+ツール）/ Environment（コンテナ+ネットワーク）/ Session（実行インスタンス）の責務分離。Agent と Environment は永続、Session は都度作成
組み込みツール8種: agent_toolset_20260401 で一括有効化。本番ではホワイトリスト方式で最小権限を徹底するとよい
get-or-create パターン必須: agents.create は毎回新規作成。IDをローカルファイル等に保存して再利用する実装が事実上の前提
ネットワーキング既定値の罠: デフォルトは unrestricted（フルアクセス）。本番では明示的に limited への変更を検討
SSEストリームによる双方向通信: 長時間タスクへの対応、ツール実行の可視化、双方向性が設計理由。streamを先に開いてからsendするのが公式推奨パターン
料金は session-hour 課金 + トークン料金: $0.08 / session-hour（active runtimeのみ）。実際はトークン料金のほうが支配的
Console で観測性が無料相当: 自前でDatadogやCloudWatchを構築する必要がない

ベータ版のため仕様変更の可能性は残るが、自律エージェント実装の学習コストと運用コストを大幅に削減できる仕組みとして、まずは小規模なPoCから試してみるとよい。公式ドキュメント platform.claude.com/docs/en/managed-agents/overview を一次ソースとして、本記事のサンプルコードをベースに手元で動かしてみてほしい。

INDEX

要約