Migração

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

De um loop de agente da API de Mensagens

Se você construiu um agente chamando messages.create em um loop while, executando chamadas de ferramentas você mesmo e adicionando resultados ao histórico de conversas, a maioria desse código desaparece.

O que você para de gerenciar

Comparação de código

Antes (loop da API de Mensagens, simplificado):

Depois (Claude Managed Agents):

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. Veja Fluxo de eventos da sessão.
• Contexto: Você ainda pode injetar contexto via prompt do sistema, recursos de arquivo ou habilidades.

Do Claude Agent SDK

Se você construiu com o Claude Agent SDK, você já está trabalhando com agentes, ferramentas e sessões como conceitos. A diferença é onde eles são executados: o SDK é executado em um processo que você opera, enquanto Managed Agents é executado na infraestrutura da Anthropic. A maioria da migração é mapear objetos de configuração do SDK para seus equivalentes do 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-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)

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

O Agent e o Environment são criados uma vez e reutilizados em sessões. A função de ferramenta ainda é executada em seu processo; a diferença é que você lê o evento agent.custom_tool_use e envia o resultado explicitamente em vez do SDK despachá-lo para você.

Recursos que se movem para seu cliente

O tradeoff para Anthropic executar o loop do agente é que algumas coisas que o SDK tratava automaticamente se tornam responsabilidade do seu cliente.

Lista de verificação de migração

1. Crie um ambiente com a rede e 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.stream.
4. Para qualquer arquivo local que o agente leia, carregue-o via API de Arquivos e monte-o como resources.
5. Para qualquer manipulador de ferramenta personalizada, mova a execução para seu loop de eventos como respostas a eventos agent.custom_tool_use.
6. Verifique com uma sessão de teste antes de apontar o 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 Claude Managed Agents é tipicamente uma mudança de um campo: atualize model em sua definição de agente e a mudança entra em vigor na próxima sessão que você criar.

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

• Mudanças de parâmetro de solicitação (padrões de max_tokens, configuração de thinking) são tratadas pelo runtime Claude Managed Agents. Esses campos não são expostos na definição do agente.
• Preenchimento de mensagem do assistente não existe no modelo de sessão baseado em eventos, então sua remoção em modelos mais novos é uma operação nula.
• Escape JSON de argumento de ferramenta é 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 API de Mensagens (o que o modelo faz diferentemente) ainda se aplicam. As etapas de migração (como alterar seu código de solicitação) não.