Managed AgentsПервые шаги

Миграция

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

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

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

Если вы построили агента, вызывая messages.create в цикле while, самостоятельно выполняя вызовы инструментов и добавляя результаты в историю разговора, большая часть этого кода исчезает.

Чем вы перестаёте управлять

До	После
Вы поддерживаете массив истории разговора и передаёте его обратно на каждом ходе.	Сессия хранит историю на стороне сервера. Отправляйте события, получайте события.
Вы перебираете блоки содержимого `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",
        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",
    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 недоступны. См. Ограничение доменов веб-поиска и веб-загрузки.
Контекст: вы по-прежнему можете внедрять контекст через системную подсказку, файловые ресурсы или навыки.

С Claude Agent SDK

Если вы разрабатывали с помощью Claude Agent SDK, вы уже работаете с агентами, инструментами и сессиями как с понятиями. Разница в том, где они выполняются: SDK работает в процессе, которым управляете вы, а Managed Agents работает в инфраструктуре Anthropic. Большая часть миграции — это сопоставление объектов конфигурации SDK с их эквивалентами на стороне API.

Что меняется

Agent SDK	Managed Agents
`ClaudeAgentOptions(...)`, создаваемый при каждом запуске	`client.beta.agents.create(...)` один раз; агент сохраняется и версионируется на стороне сервера. См. Настройка агента.
`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` настраиваются и аутентифицируются в одном месте	Объявите серверы в агенте; предоставьте учётные данные через Vault в сессии.
`permission_mode`, `can_use_tool`	`permission_policy` для каждого инструмента; отправляйте события `user.tool_confirmation` для инструментов `always_ask`.

Сравнение кода

До (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",
    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",
    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 event in stream:
        if event.type == "agent.message":
            print(
                "".join(block.text for block in event.content if block.type == "text")
            )
        elif event.type == "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}],
                    }
                ],
            )
        elif (
            event.type == "session.status_idle"
            and event.stop_reason
            and event.stop_reason.type == "end_turn"
        ):
            break

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

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

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

Функция SDK	Подход Managed Agents
Режим планирования	Сначала запустите сессию только для планирования, затем вторую сессию для выполнения плана.
Стили вывода, слэш-команды	Применяйте в вашем клиенте перед отправкой `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.
Проверьте с помощью тестовой сессии, прежде чем направлять производственный трафик на новый поток.