Migração

Claude Managed Agents substitui seu loop de agente escrito manualmente por infraestrutura gerenciada. Esta página aborda o que muda quando você migra de um loop personalizado construído na Messages API ou do Claude Agent SDK.



De um loop de agente da Messages API

Se você construiu um agente chamando messages.create em um loop while, executando chamadas de ferramentas por conta própria e anexando resultados ao histórico da conversa, a maior parte desse código desaparece.



O que você deixa de gerenciar



Comparação de código

Antes (loop da Messages API, simplificado):

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,
                        }
                    ],
                }
            )

Depois (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



O que você ainda controla

• Prompt do sistema e modelo: Mesmos campos, agora na definição do agente.
• Ferramentas personalizadas: Ainda declaradas com JSON Schema. A execução passa do tratamento inline para responder a eventos agent.custom_tool_use. Consulte Stream de eventos da sessão.
• Contexto: Você ainda pode injetar contexto através do prompt do sistema, recursos de arquivo ou skills.



Do Claude Agent SDK

Se você construiu com o Claude Agent SDK, já está trabalhando com agentes, ferramentas e sessões como conceitos. A diferença é onde eles são executados: o SDK executa em um processo que você opera, enquanto Managed Agents executa na infraestrutura da Anthropic. A maior parte da migração consiste em mapear objetos de configuração do SDK para seus equivalentes no lado da API.



O que muda



Comparação de código

Antes (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)

Depois (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

O Agente e o Ambiente são criados uma vez e reutilizados entre sessões. A função da ferramenta ainda executa no seu processo; a diferença é que você lê o evento agent.custom_tool_use e envia o resultado explicitamente, em vez de o SDK despachá-lo por você.



Funcionalidades que passam para o seu cliente

A contrapartida de a Anthropic executar o loop do agente é que algumas coisas que o SDK tratava automaticamente passam a ser responsabilidade do seu cliente.



Checklist de migração

1. Crie um ambiente com a rede e os runtimes que seu agente precisa.
2. Porte seu prompt do sistema e seleção de ferramentas para uma definição de agente.
3. Substitua seu loop por sessions.create e sessions.events.stream.
4. Para quaisquer arquivos locais que o agente lê, faça upload deles através da Files API e monte-os como resources.
5. Para quaisquer handlers de ferramentas personalizadas, mova a execução para o seu loop de eventos como respostas a eventos agent.custom_tool_use.
6. Verifique com uma sessão de teste antes de direcionar tráfego de produção para o novo fluxo.



Migrando entre versões de modelo

Quando um novo modelo Claude é lançado, migrar uma integração do Claude Managed Agents é tipicamente uma mudança de um único campo: atualize model na sua definição de agente e a mudança entra em vigor na próxima sessão que você criar.

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

A maioria das mudanças de comportamento no nível do modelo documentadas no guia de migração da Messages API não requer ação do seu lado:

• Mudanças em parâmetros de requisição (padrões de max_tokens, configuração de thinking) são tratadas pelo runtime do Claude Managed Agents. Esses campos não são expostos na definição do agente.
• Preenchimento prévio de mensagem do assistente não existe no modelo de sessão baseado em eventos, então sua remoção em modelos mais recentes não tem efeito.
• Escape de JSON em argumentos de ferramentas é analisado pelo runtime antes de você receber eventos agent.custom_tool_use. Você vê dados estruturados, não strings brutas.

As descrições de comportamento no guia da Messages API (o que o modelo faz de diferente) ainda se aplicam. As etapas de migração (como alterar seu código de requisição) não.