Миграция

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

Из цикла агента Messages API

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

Что вы перестаёте контролировать

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

До (цикл Messages API, упрощённо):

После (Claude Managed Agents):

Что остаётся под вашим контролем

• Системный промпт и модель: Те же поля, теперь в определении агента.
• Пользовательские инструменты: По-прежнему объявляются с помощью JSON Schema. Выполнение переходит от встроенной обработки к ответам на события agent.custom_tool_use. См. Поток событий сессии.
• Контекст: Вы по-прежнему можете вводить контекст через системный промпт, файловые ресурсы или навыки.

Из Claude Agent SDK

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

Что меняется

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

До (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-sonnet-4-6",
    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-sonnet-4-6",
    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

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

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

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

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

1. Создайте окружение с сетевыми настройками и средами выполнения, необходимыми вашему агенту.
2. Перенесите системный промпт и выбор инструментов в определение агента.
3. Замените ваш цикл на sessions.create и sessions.stream.
4. Для любых локальных файлов, которые читает агент, загрузите их через Files API и смонтируйте как resources.
5. Для любых обработчиков пользовательских инструментов перенесите выполнение в ваш цикл событий как ответы на события agent.custom_tool_use.
6. Проверьте с помощью тестовой сессии перед тем, как направить производственный трафик на новый поток.

Миграция между версиями модели

Когда выходит новая модель Claude, миграция интеграции Claude Managed Agents обычно представляет собой изменение одного поля: обновите model в вашем определении агента, и изменение вступит в силу в следующей создаваемой вами сессии.

Большинство изменений поведения на уровне модели, задокументированных в руководстве по миграции Messages API, не требуют действий с вашей стороны:

• Изменения параметров запроса (значения по умолчанию max_tokens, конфигурация thinking) обрабатываются средой выполнения Claude Managed Agents. Эти поля не представлены в определении агента.
• Предзаполнение сообщений ассистента не существует в событийно-ориентированной модели сессий, поэтому его удаление в новых моделях является холостой операцией.
• Экранирование JSON аргументов инструментов разбирается средой выполнения до того, как вы получаете события agent.custom_tool_use. Вы видите структурированные данные, а не необработанные строки.

Описания поведения в руководстве Messages API (что модель делает по-другому) по-прежнему применимы. Шаги миграции (как изменить код запроса) — нет.