移行

管理

マイグレーション

Messages APIまたはClaude Agent SDKで構築された既存のエージェントをClaude Managed Agentsに移行します。

Claude Managed Agentsは、手書きのエージェントループを管理されたインフラストラクチャに置き換えます。このページでは、Messages APIで構築されたカスタムループ、またはClaude Agent SDKからマイグレーションする際の変更点について説明します。

すべてのManaged Agents APIリクエストには、managed-agents-2026-04-01ベータヘッダーが必要です。SDKはベータヘッダーを自動的に設定します。

Messages APIエージェントループから

whileループでmessages.createを呼び出し、ツール呼び出しを自分で実行し、結果を会話履歴に追加することでエージェントを構築した場合、そのコードの大部分は不要になります。

管理を停止するもの

前	後
会話履歴配列を保持し、毎ターン戻す。	セッションはサーバー側に履歴を保存します。イベントを送信し、イベントを受け取ります。
`stop_reason: "tool_use"`を解析し、ツールを実行し、`tool_result`メッセージでループバックします。	事前構築されたツールはコンテナ内で自動的に実行されます。`agent.custom_tool_use`イベント経由でカスタムツールのみを処理します。
エージェント生成コードを実行するための独自のサンドボックスをプロビジョニングします。	セッションコンテナはコード実行、ファイル操作、およびbashを処理します。
ループが完了したときを決定します。	セッションはエージェントがすることがなくなったときに`session.status_idle`を発行します。

コード比較

前 (Messages APIループ、簡略版):

messages = [{"role": "user", "content": task}]
while True:
    response = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=1024,
        messages=messages,
        tools=tools,
    )
    messages.append({"role": "assistant", "content": response.content})
    if response.stop_reason == "end_turn":
        break
    for block in response.content:
        if block.type == "tool_use":
            result = execute_tool(block.name, block.input)
            messages.append(
                {
                    "role": "user",
                    "content": [
                        {
                            "type": "tool_result",
                            "tool_use_id": block.id,
                            "content": result,
                        }
                    ],
                }
            )

後 (Claude Managed Agents):

agent = client.beta.agents.create(
    name="Task Runner",
    model="claude-opus-4-7",
    tools=[{"type": "agent_toolset_20260401"}],
)

session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": agent.version},
    environment_id=environment.id,
)

with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[{"type": "user.message", "content": [{"type": "text", "text": task}]}],
    )
    for event in stream:
        if event.type == "session.status_idle":
            break

引き続き制御するもの

システムプロンプトとモデル: 同じフィールド、現在はエージェント定義上にあります。
カスタムツール: 引き続きJSONスキーマで宣言されます。実行はインラインハンドリングからagent.custom_tool_useイベントへの応答に移動します。セッションイベントストリームを参照してください。
コンテキスト: システムプロンプト、ファイルリソース、またはスキル経由でコンテキストを注入できます。

Claude Agent SDKから

Claude Agent SDKで構築した場合、エージェント、ツール、セッションの概念として既に作業しています。違いは実行場所です。SDKは操作するプロセスで実行され、Managed AgentsはAnthropicのインフラストラクチャで実行されます。マイグレーションのほとんどは、SDKの設定オブジェクトをAPI側の同等物にマッピングすることです。

変更内容

Agent SDK	Managed Agents
`ClaudeAgentOptions(...)`は実行ごとに構築されます	`client.beta.agents.create(...)`は1回実行されます。エージェントはサーバー側で永続化およびバージョン管理されます。エージェント設定を参照してください。
`async with ClaudeSDKClient(...)` または `query(...)`	`client.beta.sessions.create(...)`その後、イベントを送受信します。
`@tool`デコレーション関数はSDKによって自動的にディスパッチされます	エージェント上で`{"type": "custom", ...}`として宣言します。クライアントは`agent.custom_tool_use`イベントを処理し、`user.custom_tool_result`で応答します。ツールを参照してください。
組み込みツールはプロセス内でファイルシステムに対して実行されます	`{"type": "agent_toolset_20260401"}`はセッションコンテナ内で`/workspace`に対して同じツールを実行します。
`cwd`、`add_dirs`はローカルパスを指します	ファイルをアップロードまたはマウントしてセッションリソースとして使用します。
`system_prompt`と`CLAUDE.md`階層	エージェント上の単一の`system`文字列。各更新はサーバー側の新しいバージョンを生成します。セッションを特定のバージョンにピン留めして、デプロイなしで昇格またはロールバックします。エージェント設定を参照してください。
`mcp_servers`は1か所で構成および認証されます	エージェント上でサーバーを宣言します。セッション上のVault経由で認証情報を提供します。
`permission_mode`、`can_use_tool`	ツールごとの`permission_policy`。`always_ask`ツールの`user.tool_confirmation`イベントに応答します。

コード比較

前 (Agent SDK):

from claude_agent_sdk import (
    ClaudeAgentOptions,
    ClaudeSDKClient,
    create_sdk_mcp_server,
    tool,
)


@tool("get_weather", "Get the current weather for a city.", {"city": str})
async def get_weather(args: dict) -> dict:
    return {"content": [{"type": "text", "text": f"{args['city']}: 18°C, clear"}]}


options = ClaudeAgentOptions(
    model="claude-opus-4-7",
    system_prompt="You are a concise weather assistant.",
    mcp_servers={
        "weather": create_sdk_mcp_server("weather", "1.0", tools=[get_weather])
    },
)

async with ClaudeSDKClient(options=options) as agent:
    await agent.query("What's the weather in Tokyo?")
    async for msg in agent.receive_response():
        print(msg)

後 (Managed Agents):

from anthropic import Anthropic

client = Anthropic()

agent = client.beta.agents.create(
    name="weather-agent",
    model="claude-opus-4-7",
    system="You are a concise weather assistant.",
    tools=[
        {
            "type": "custom",
            "name": "get_weather",
            "description": "Get the current weather for a city.",
            "input_schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        }
    ],
)
environment = client.beta.environments.create(
    name="weather-env",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": agent.version},
    environment_id=environment.id,
)


def get_weather(city: str) -> str:
    return f"{city}: 18°C, clear"


with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [{"type": "text", "text": "What's the weather in Tokyo?"}],
            }
        ],
    )
    for ev in stream:
        if ev.type == "agent.message":
            print("".join(b.text for b in ev.content))
        elif ev.type == "agent.custom_tool_use":
            result = get_weather(**ev.input)
            client.beta.sessions.events.send(
                session.id,
                events=[
                    {
                        "type": "user.custom_tool_result",
                        "custom_tool_use_id": ev.id,
                        "content": [{"type": "text", "text": result}],
                    }
                ],
            )
        elif ev.type == "session.status_idle" and ev.stop_reason.type == "end_turn":
            break

エージェントと環境は1回作成され、セッション全体で再利用されます。ツール関数は引き続きプロセス内で実行されます。違いは、agent.custom_tool_useイベントを読み取り、SDKがディスパッチする代わりに明示的に結果を送信することです。

クライアントに移動する機能

エージェントループを実行するAnthropicのトレードオフは、SDKが自動的に処理していたいくつかのことがクライアントの責任になることです。

SDK機能	Managed Agentsアプローチ
プランモード	最初にプランのみのセッションを実行し、次に実行用の2番目のセッションを実行します。
出力スタイル、スラッシュコマンド	`user.message`を送信する前または`agent.message`を受け取った後にクライアントで適用します。
`PreToolUse` / `PostToolUse`フック	クライアントは既にすべての`agent.custom_tool_use`イベントを応答する前に見ています。ロジックをそこに配置します。組み込みツールの場合は、`permission_policy: always_ask`を使用します。
`max_turns`	クライアント側でターンをカウントします。