Миграция

Перенесите существующего агента, построенного на Messages API или Claude Agent SDK, на Claude Managed Agents.

Claude Managed Agents заменяет ваш написанный вручную цикл агента управляемой инфраструктурой. На этой странице описано, что меняется при миграции с пользовательского цикла, построенного на Messages API, или с Claude Agent SDK.

С цикла агента на Messages API

Если вы создали агента, вызывая client.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-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,
                        }
                    ],
                }
            )

После (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

Что вы по-прежнему контролируете

Системная подсказка и модель: те же поля, теперь в определении агента.
Пользовательские инструменты: по-прежнему объявляются с помощью JSON Schema. Выполнение переходит от встроенной обработки к ответам на события agent.custom_tool_use. См. Поток событий сессии.
Настройки веб-поиска и веб-загрузки: те же поля allowed_domains, blocked_domains, max_content_tokens и user_location, которые теперь задаются один раз в записях web_search и web_fetch массива configs набора инструментов агента, а не в каждом запросе. Поля max_uses, citations и cache_control недоступны. См. Отличия от инструментов Messages API.
Контекст: вы по-прежнему можете внедрять контекст через системную подсказку, файловые ресурсы или навыки.

С 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(...)`, затем отправка и получение событий.
Функции, определённые с помощью `@tool` и автоматически вызываемые SDK	Объявите их как `{"type": "custom", ...}` в Agent; ваш клиент обрабатывает события `agent.custom_tool_use` и отвечает событием `user.custom_tool_result`. См. Инструменты.
Встроенные инструменты выполняются в вашем процессе и работают с вашей файловой системой	`{"type": "agent_toolset_20260401"}` запускает те же инструменты внутри песочницы сессии и работает с `/workspace`.
`cwd`, `add_dirs` указывают на локальные пути	Загрузите или смонтируйте файлы как ресурсы сессии.
`system_prompt` и иерархия `CLAUDE.md`	Одна строка `system` в Agent. Каждое обновление, изменяющее агента, создаёт новую версию на стороне сервера; закрепляйте сессии за конкретной версией, чтобы продвигать или откатывать изменения без развёртывания. См. Настройка агента.
`mcp_servers` настраиваются и аутентифицируются в одном месте	Объявите серверы в Agent; предоставьте учётные данные через Vault в Session.
`permission_mode`, `can_use_tool`	`permission_policy` для каждого инструмента (`always_allow`, `always_ask` или `auto`); отправляйте события `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-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)

После (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

Агент и окружение создаются один раз и повторно используются в разных сессиях. Функция инструмента по-прежнему выполняется в вашем процессе; разница в том, что вы читаете событие agent.custom_tool_use и явно отправляете результат, вместо того чтобы SDK вызывал её за вас.

Функции, которые переходят к вашему клиенту

Компромисс за то, что Anthropic выполняет цикл агента, состоит в том, что некоторые вещи, которые SDK обрабатывал автоматически, становятся ответственностью вашего клиента.

Функция SDK	Подход в Managed Agents
«Plan mode» (режим планирования)	Сначала запустите сессию только для планирования, затем вторую сессию для выполнения плана.
Стили вывода, слэш-команды	Применяйте их в вашем клиенте перед отправкой `user.message` или после получения `agent.message`.
Хуки `PreToolUse` / `PostToolUse`	Ваш клиент уже видит каждое событие `agent.custom_tool_use` перед ответом; разместите логику там. Для встроенных инструментов используйте `permission_policy: always_ask`, чтобы проверять каждый вызов. `auto` позволяет вместо этого серверу оценивать каждый вызов, но если сервер оценит вызов как безопасный, он будет выполнен, не доходя до вашего клиента.
`max_turns`	Подсчитывайте ходы на стороне клиента.

Контрольный список миграции

Создайте окружение с сетевыми настройками и средами выполнения, необходимыми вашему агенту.
Перенесите вашу системную подсказку и выбор инструментов в определение агента.
Замените свой цикл: создайте сессию с помощью client.beta.sessions.create() и получайте поток её событий с помощью client.beta.sessions.events.stream().
Все локальные файлы, которые читает агент, загрузите через Files API и смонтируйте как resources.
Для всех обработчиков пользовательских инструментов перенесите выполнение в ваш цикл событий в виде ответов на события agent.custom_tool_use.
Проверьте с помощью тестовой сессии, прежде чем направлять производственный трафик на новый поток.