Claudeのエージェントループ・サンドボックス管理をAnthropicに委譲する「Managed Agents」

8月13日、Docker・クラウドネイティブ技術の実践的チュートリアルで知られるコミュニティメディアCollabnixが「Claude Managed Agents Tutorial: Build an Autonomous AI Agent Step by Step」と題した記事を公開した。AIエージェントの本番運用で開発者を悩ませる「インフラ的な雑務」——サンドボックス管理、リトライ処理、イベントストリームの実装——をAnthropicのホスト環境に委譲できる**Claude Managed Agents（現在beta）の仕組みと、ゼロからエージェントを構築する手順を解説している。betaステータスのためAPIの仕様変更が起こりうる**点は、冒頭から念頭に置いておきたい。

自前のエージェントループが不要になる

AIエージェントを本番運用する際に厄介なのが、サンドボックスの管理、リトライ処理、イベントストリームの実装といった「インフラ的な雑務」だ。Claude Managed Agentsは、これらをAnthropicのホスト環境に委ねることで、開発者がエージェントのロジックに集中できるようにする仕組みである。正確には「インフラ全体のホスティング」ではなく、エージェントループの制御・サンドボックスのライフサイクル管理・ツール呼び出しの調停をマネージドサービスとして提供するという位置づけだ。

必要なのはPython 3.9以上とAnthropicのAPIキー、そしてanthropicパッケージのみだ。

pip install anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

4つの構成要素を順に組み立てる

チュートリアルはAgent → Environment → Session → Event Streamという4階層の構造を順番に解説している。それぞれの役割を押さえると全体像が見えやすい。

Step 1: Agentの作成

Agentは「モデル・システムプロンプト・使用可能なツール」をひとまとめにした定義体だ。以下の例では、Gitのdiffからリリースノートを生成するエージェントを作っている。

from anthropic import Anthropic
client = Anthropic()

agent = client.beta.managed_agents.agents.create(
    name="release-notes-agent",
    model="claude-sonnet-4-6",
    system_prompt="Draft release notes from git diffs.",
    tools=[{"type": "bash_20250124", "name": "bash"}],
)
print(agent.id)

モデル名としてclaude-sonnet-4-6が使われているが、これは元記事がそのまま記載している名称であり、beta期間中の暫定的な識別子である可能性がある。実際に使用する際は公式モデル一覧で最新のモデル名を確認することを推奨する。また、組み込みツールとしてbashが使えるため、シェルコマンドの実行はほぼノーコストで実現できる。

Step 2: EnvironmentとSessionの生成

Environmentはエージェントが動くサンドボックス、Sessionはその中での1回の実行単位にあたる。

environment = client.beta.managed_agents.environments.create(
    agent_id=agent.id,
    type="sandbox",
)
session = client.beta.managed_agents.sessions.create(
    agent_id=agent.id,
    environment_id=environment.id,
    input="Summarize the last 10 commits into release notes.",
)

Step 3: イベントストリームでリアルタイム処理

ステータスをポーリングする代わりに、イベントストリームをループで処理する。tool_call・message・session_completedの3種類のイベントを拾う設計だ。

for event in client.beta.managed_agents.sessions.events.stream(
    agent_id=agent.id,
    session_id=session.id,
):
    if event.type == "tool_call":
        print("Tool call:", event.tool_name, event.input)
    elif event.type == "message":
        print("Agent:", event.text)
    elif event.type == "session_completed":
        print("Done:", event.result)
        break

カスタムツールの組み込みが肝

標準のbashツールで賄えない処理には、カスタムツールを追加登録する。記事ではGitHubのオープンPRを取得するget_open_prsツールを例に解説している。

def get_open_prs(repo: str):
    return [{"number": 42, "title": "Fix flaky test"}]

agent = client.beta.managed_agents.agents.update(
    agent_id=agent.id,
    tools=[
        {"type": "bash_20250124", "name": "bash"},
        {
            "name": "get_open_prs",
            "description": "Return open pull requests for a repo",
            "input_schema": {
                "type": "object",
                "properties": {"repo": {"type": "string"}},
                "required": ["repo"],
            },
        },
    ],
)

エージェントがツールを呼び出した際は、**submit_tool_resultで結果を同一のイベントループに返す**必要がある。この返送を忘れると、セッションがそのtool_call_idを待ち続けてハングアップする。

if event.type == "tool_call" and event.tool_name == "get_open_prs":
    result = get_open_prs(**event.input)
    client.beta.managed_agents.sessions.events.submit_tool_result(
        agent_id=agent.id,
        session_id=session.id,
        tool_call_id=event.id,
        output=result,
    )

ハマりやすいエラー3選

記事はよくある落とし穴も明記している。

429 rate limited: 標準のMessages APIと同様にバックオフ・リトライで対処する
Sessionがqueuedのまま止まる: Environmentのプロビジョニングが失敗している可能性がある。environment.statusを確認してからSessionを作成すること
tool_callが返ってこない: submit_tool_resultを送り忘れているケース。エラーパスを含むすべてのtool_callイベントに対して必ずsubmitすること

どういうケースで使うべきか

記事は「Managed Agentsは既存のMessages APIを使った自前エージェントループの置き換えではなく、代替手段だ」と明確に線引きしている。

Messages API直接利用が向くケース: 短いスクリプト、細かい制御が必要な場合
Managed Agentsが向くケース: 長時間実行エージェント、本番運用、サンドボックスやリトライの管理を自前でやりたくない場合

APIはbetaであり、メソッド名や挙動は今後変わる可能性がある。記事自体も「公式のClaude Platform docsで最新情報を確認してからリリースすること」と注記しており、本番投入前には必ず公式ドキュメントを参照したい。

詳細はClaude Managed Agents Tutorial: Build an Autonomous AI Agent Step by Stepを参照していただきたい。