Миграция

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



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

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



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



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

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

messages = [{"role": "user", "content": task}]
while True:
    response = client.messages.create(
        model="claude-opus-4-8",
        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-4-8",
    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. См. Поток событий сессии.
• Контекст: вы по-прежнему можете внедрять контекст через системную подсказку, файловые ресурсы или навыки.



С 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-8",
    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-8",
    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(block.text for block in ev.content if block.type == "text"))
        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
            and ev.stop_reason.type == "end_turn"
        ):
            break

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



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

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



Чек-лист миграции

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



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

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

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --model claude-opus-4-8

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

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

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