Claude Platform Docs
Managed AgentsFirst steps

Migration

Move an existing agent built on the Messages API or the Claude Agent SDK to Claude Managed Agents.

Claude Managed Agents replaces your hand-written agent loop with managed infrastructure. This page covers what changes when you migrate from a custom loop built on the Messages API or from the Claude Agent SDK.

From a Messages API agent loop

If you built an agent by calling client.messages.create() in a loop, running tool calls yourself, and appending results to the conversation history, Claude Managed Agents replaces most of that loop code.

What you stop managing

BeforeAfter
You maintain the conversation history array and pass it back on every turn.The session stores history server-side. You send events and receive events.
You iterate tool_use content blocks, run each tool, and loop back with tool_result messages.Built-in tools run inside the sandbox automatically. You only handle custom tools through agent.custom_tool_use events.
You provision your own sandbox for running agent-generated code.The session sandbox handles code execution, file operations, and bash.
You decide when the loop is done.The session emits session.status_idle when the agent has nothing more to do.

Code comparison

Before (Messages API loop, simplified):

messages = [{"role": "user", "content": task}]
while True:
    response = client.messages.create(
        model="claude-opus-5-5",
        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,
                        }
                    ],
                }
            )

After (Claude Managed Agents):

agent = client.beta.agents.create(
    name="Task Runner",
    model="claude-opus-5-5",
    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

What you control

  • System prompt and model: Same fields, on the agent definition.
  • Custom tools: Declared with JSON Schema. Your client runs them when agent.custom_tool_use events arrive, not inside a request loop. See Session event stream.
  • Web search and web fetch settings: Same allowed_domains, blocked_domains, max_content_tokens, and user_location fields, set once on the web_search and web_fetch entries of the agent toolset’s configs array instead of on every request. The max_uses, citations, and cache_control fields are not available. See Differences from the Messages API tools.
  • Context: You can inject context through the system prompt, file resources, or skills.

From the Claude Agent SDK

If you built with the Claude Agent SDK, you’re already working with agents, tools, and sessions as concepts. The difference is where they run: the SDK runs in a process you operate, whereas Managed Agents runs in Anthropic’s infrastructure. Most of the migration is mapping SDK configuration objects to their API-side equivalents.

What changes

Agent SDKManaged Agents
ClaudeAgentOptions(...) constructed for each runclient.beta.agents.create(...) once. The server persists and versions the agent. See Define your agent.
async with ClaudeSDKClient(...) or query(...)client.beta.sessions.create(...) then send and receive events.
Functions defined with @tool, dispatched automatically by the SDKDeclare as {"type": "custom", ...} on the agent; your client handles agent.custom_tool_use events and replies with user.custom_tool_result. See Tools.
Built-in tools run in your process against your filesystem{"type": "agent_toolset_20260401"} runs the same tools inside the session sandbox against /workspace.
cwd, add_dirs point at local pathsUpload or mount files as session resources.
system_prompt and the CLAUDE.md hierarchyA single system string on the agent. Each update that changes the agent produces a new server-side version; pin sessions to a specific version to promote or roll back without a deploy. See Define your agent.
mcp_servers configured and authenticated in one placeDeclare servers on the agent; provide credentials through a vault on the session.
permission_mode, can_use_toolPer-tool permission_policy (always_allow, always_ask, or auto). Send user.tool_confirmation events for calls that pause for your approval.

Code comparison

Before (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-5-5",
    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)

After (Managed Agents):

from anthropic import Anthropic

client = Anthropic()

agent = client.beta.agents.create(
    name="weather-agent",
    model="claude-opus-5-5",
    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": "limited", "allow_package_managers": True},
    },
)

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 event in stream:
        match event.type:
            case "agent.message":
                print(
                    "".join(
                        block.text for block in event.content if block.type == "text"
                    )
                )
            case "agent.custom_tool_use":
                result = get_weather(**event.input)
                client.beta.sessions.events.send(
                    session.id,
                    events=[
                        {
                            "type": "user.custom_tool_result",
                            "custom_tool_use_id": event.id,
                            "content": [{"type": "text", "text": result}],
                        }
                    ],
                )
            case "session.status_idle":
                if event.stop_reason and event.stop_reason.type == "end_turn":
                    break

You create the agent and environment once and reuse them across sessions. The tool function still runs in your process. The difference is that you read the agent.custom_tool_use event and send the result explicitly instead of the Agent SDK dispatching it for you.

Features that move to your client

The tradeoff for Anthropic running the agent loop is that a few things the SDK handled automatically become your client’s responsibility.

SDK featureManaged Agents approach
Plan modeRun a planning-only session first, then a second session to run the plan.
Output styles, slash commandsApply in your client before sending user.message or after receiving agent.message.
PreToolUse / PostToolUse hooksYour client already sees every agent.custom_tool_use event before responding; put the logic there. For built-in tools, use permission_policy: always_ask to review every call. auto lets the server evaluate each call instead, but if the server evaluates a call as safe, it runs without reaching your client.
max_turnsCount turns client-side.

Migration checklist

  1. Create an environment with the networking and runtimes your agent needs.
  2. Port your system prompt and tool selection to an agent definition.
  3. Replace your loop: create a session with client.beta.sessions.create() and stream its events with client.beta.sessions.events.stream().
  4. For any local files the agent reads, upload them through the Files API and mount them as resources.
  5. For any custom tool handlers, run them in your event loop as responses to agent.custom_tool_use events.
  6. Run a test session before you point production traffic at the migrated flow.

Migrating between model versions

When a new Claude model is released, migrating a Claude Managed Agents integration is typically a one-field change: update model on your agent definition, and the change takes effect on the next session you create.

ant apply agent.md
agent.md
---
name: Task Runner
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a task automation agent. Complete the task you are given end to end.

Most model-level behavior changes documented in the Migration guides do not require action on your side:

  • Request parameter changes (max_tokens defaults, thinking configuration) need no action: the Claude Managed Agents runtime handles them. The agent definition does not expose these fields.
  • Assistant message prefilling does not exist in the event-based session model, so moving to a model that rejects prefill needs no change from you.
  • Tool argument JSON escaping needs no action: the runtime parses the arguments before you receive agent.custom_tool_use events. You see structured data, not raw strings.

The behavior descriptions in those guides (what the model does differently) still apply. The migration steps (how to change your request code) do not.

Was this page helpful?