Миграция

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-opus-4-7",
    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-7",
    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 (что модель делает по-другому) по-прежнему применяются. Шаги миграции (как изменить код вашего запроса) — нет.