Migração

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

A partir 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 maior parte 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 de 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 de sessão.
• Contexto: Você ainda pode injetar contexto via prompt de sistema, recursos de arquivo ou habilidades.

A partir 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 o Managed Agents é executado na infraestrutura da Anthropic. A maior parte da migração é 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-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)

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

O Agente e o Ambiente são criados uma vez e reutilizados entre 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 de o SDK despachá-lo para você.

Recursos que passam para o seu cliente

A contrapartida de a 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 os runtimes que seu agente precisa.
2. Porte seu prompt de sistema e seleção de ferramentas para uma definição de agente.
3. Substitua seu loop por sessions.create e sessions.stream.
4. Para quaisquer arquivos locais que o agente lê, faça upload deles via API de Arquivos e monte-os como resources.
5. Para quaisquer manipuladores 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 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 do Claude Managed Agents é tipicamente uma mudança de um campo: atualize model na 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 no nível do modelo documentadas no guia de migração da API de Mensagens não requer ação da sua parte:

• Mudanças de 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 de mensagem do assistente não existe no modelo de sessão baseado em eventos, portanto sua remoção em modelos mais novos é uma operação sem efeito.
• Escape de JSON de 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 API de Mensagens (o que o modelo faz de forma diferente) ainda se aplicam. As etapas de migração (como alterar o código de sua requisição) não se aplicam.