リリースノート移行ガイド

移行

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を呼び出し、ツール呼び出しを自分で実行し、結果を会話履歴に追加することでエージェントを構築していた場合、そのコードのほとんどは不要になります。

管理しなくなるもの

移行前	移行後
会話履歴の配列を維持し、毎ターンそれを渡す。	セッションが履歴をサーバー側に保存します。イベントを送信し、イベントを受信します。
`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-8",
        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-8",
    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 Schemaで宣言します。実行はインライン処理から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(...)`を一度実行。Agentはサーバー側で永続化され、バージョン管理されます。エージェントのセットアップを参照してください。
`async with ClaudeSDKClient(...)`または`query(...)`	`client.beta.sessions.create(...)`を実行し、その後イベントを送受信します。
SDKによって自動的にディスパッチされる`@tool`デコレータ付き関数	Agent上で`{"type": "custom", ...}`として宣言します。クライアントが`agent.custom_tool_use`イベントを処理し、`user.custom_tool_result`で応答します。ツールを参照してください。
組み込みツールはあなたのプロセス内でローカルファイルシステムに対して実行される	`{"type": "agent_toolset_20260401"}`は同じツールをセッションサンドボックス内で`/workspace`に対して実行します。
`cwd`、`add_dirs`はローカルパスを指す	ファイルをセッションリソースとしてアップロードまたはマウントします。
`system_prompt`と`CLAUDE.md`階層	Agent上の単一の`system`文字列。更新ごとに新しいサーバー側バージョンが生成されます。デプロイなしで昇格またはロールバックするには、セッションを特定のバージョンに固定します。エージェントのセットアップを参照してください。
一箇所で設定および認証される`mcp_servers`	Agent上でサーバーを宣言し、Session上の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-8",
    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-8",
    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(block.text for block in ev.content if block.type == "text"))
        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
            and ev.stop_reason.type == "end_turn"
        ):
            break

AgentとEnvironmentは一度作成され、セッション間で再利用されます。ツール関数は引き続きあなたのプロセス内で実行されます。違いは、SDKが自動的にディスパッチする代わりに、agent.custom_tool_useイベントを読み取り、結果を明示的に送信することです。

クライアント側に移る機能

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

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

移行チェックリスト

エージェントが必要とするネットワーキングとランタイムを備えた環境を作成します。
システムプロンプトとツール選択をエージェント定義に移植します。
ループをsessions.createとsessions.events.streamに置き換えます。
エージェントが読み取るローカルファイルについては、Files APIを通じてアップロードし、resourcesとしてマウントします。
カスタムツールハンドラーについては、実行をagent.custom_tool_useイベントへの応答としてイベントループに移動します。
本番トラフィックを新しいフローに向ける前に、テストセッションで検証します。

モデルバージョン間の移行

新しいClaudeモデルがリリースされた場合、Claude Managed Agents統合の移行は通常、1つのフィールドの変更のみです。エージェント定義のmodelを更新すると、次に作成するセッションから変更が有効になります。

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --model claude-opus-4-8

Messages API移行ガイドに記載されているモデルレベルの動作変更のほとんどは、あなたの側での対応を必要としません。

リクエストパラメータの変更（max_tokensのデフォルト、thinking設定）はClaude Managed Agentsランタイムによって処理されます。これらのフィールドはエージェント定義上で公開されていません。
アシスタントメッセージのプリフィルはイベントベースのセッションモデルには存在しないため、新しいモデルでの削除は影響がありません。
ツール引数のJSONエスケープは、agent.custom_tool_useイベントを受信する前にランタイムによって解析されます。生の文字列ではなく、構造化されたデータが表示されます。

Messages APIガイドの動作説明（モデルが何を異なる方法で行うか）は引き続き適用されます。移行手順（リクエストコードをどのように変更するか）は適用されません。

Was this page helpful?

リリースノート移行ガイド

移行

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

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

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

管理しなくなるもの

移行前	移行後
会話履歴の配列を維持し、毎ターンそれを渡す。	セッションが履歴をサーバー側に保存します。イベントを送信し、イベントを受信します。
`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-8",
        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-8",
    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 Schemaで宣言します。実行はインライン処理からagent.custom_tool_useイベントへの応答に移行します。セッションイベントストリームを参照してください。
コンテキスト： システムプロンプト、ファイルリソース、またはスキルを通じて引き続きコンテキストを注入できます。

Claude Agent SDKからの移行

変更点

Agent SDK	Managed Agents
実行ごとに構築される`ClaudeAgentOptions(...)`	`client.beta.agents.create(...)`を一度実行。Agentはサーバー側で永続化され、バージョン管理されます。エージェントのセットアップを参照してください。
`async with ClaudeSDKClient(...)`または`query(...)`	`client.beta.sessions.create(...)`を実行し、その後イベントを送受信します。
SDKによって自動的にディスパッチされる`@tool`デコレータ付き関数	Agent上で`{"type": "custom", ...}`として宣言します。クライアントが`agent.custom_tool_use`イベントを処理し、`user.custom_tool_result`で応答します。ツールを参照してください。
組み込みツールはあなたのプロセス内でローカルファイルシステムに対して実行される	`{"type": "agent_toolset_20260401"}`は同じツールをセッションサンドボックス内で`/workspace`に対して実行します。
`cwd`、`add_dirs`はローカルパスを指す	ファイルをセッションリソースとしてアップロードまたはマウントします。
`system_prompt`と`CLAUDE.md`階層	Agent上の単一の`system`文字列。更新ごとに新しいサーバー側バージョンが生成されます。デプロイなしで昇格またはロールバックするには、セッションを特定のバージョンに固定します。エージェントのセットアップを参照してください。
一箇所で設定および認証される`mcp_servers`	Agent上でサーバーを宣言し、Session上の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-8",
    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-8",
    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(block.text for block in ev.content if block.type == "text"))
        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
            and ev.stop_reason.type == "end_turn"
        ):
            break

クライアント側に移る機能

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

移行チェックリスト

エージェントが必要とするネットワーキングとランタイムを備えた環境を作成します。
システムプロンプトとツール選択をエージェント定義に移植します。
ループをsessions.createとsessions.events.streamに置き換えます。
エージェントが読み取るローカルファイルについては、Files APIを通じてアップロードし、resourcesとしてマウントします。
カスタムツールハンドラーについては、実行をagent.custom_tool_useイベントへの応答としてイベントループに移動します。
本番トラフィックを新しいフローに向ける前に、テストセッションで検証します。

モデルバージョン間の移行

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --model claude-opus-4-8

Messages API移行ガイドに記載されているモデルレベルの動作変更のほとんどは、あなたの側での対応を必要としません。

リクエストパラメータの変更（max_tokensのデフォルト、thinking設定）はClaude Managed Agentsランタイムによって処理されます。これらのフィールドはエージェント定義上で公開されていません。
アシスタントメッセージのプリフィルはイベントベースのセッションモデルには存在しないため、新しいモデルでの削除は影響がありません。
ツール引数のJSONエスケープは、agent.custom_tool_useイベントを受信する前にランタイムによって解析されます。生の文字列ではなく、構造化されたデータが表示されます。

Was this page helpful?

Messages APIエージェントループからの移行

管理しなくなるもの

コード比較

引き続き制御できるもの

Claude Agent SDKからの移行

変更点

コード比較

クライアント側に移る機能

移行チェックリスト

モデルバージョン間の移行

Messages APIエージェントループからの移行

管理しなくなるもの

コード比較

引き続き制御できるもの

Claude Agent SDKからの移行

変更点

コード比較

クライアント側に移る機能

移行チェックリスト

モデルバージョン間の移行

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

管理しなくなるもの

コード比較

引き続き制御できるもの

Claude Agent SDKからの移行

変更点

コード比較

クライアント側に移る機能

移行チェックリスト

モデルバージョン間の移行

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

管理しなくなるもの

コード比較

引き続き制御できるもの

Claude Agent SDKからの移行

変更点

コード比較

クライアント側に移る機能

移行チェックリスト

モデルバージョン間の移行