Claude Platform Docs
Managed AgentsPrimeiros passos

Migração

Mova um agente existente criado com a Messages API ou com o Claude Agent SDK para o Claude Managed Agents.

O Claude Managed Agents substitui seu loop de agente escrito à mão por infraestrutura gerenciada. Esta página aborda o que muda quando você migra de um loop personalizado construído sobre a Messages API ou a partir do Claude Agent SDK.

A partir de um loop de agente da Messages API

Se você construiu um agente chamando client.messages.create() em um loop, executando as chamadas de ferramentas você mesmo e anexando os resultados ao histórico da conversa, a maior parte desse código deixa de ser necessária.

O que você deixa de gerenciar

AntesDepois
Você mantém o array do histórico da conversa e o envia de volta a cada turno.A sessão armazena o histórico no lado do servidor. Envie eventos, receba eventos.
Você itera sobre os blocos de conteúdo tool_use, executa cada ferramenta e retorna ao loop com mensagens tool_result.As ferramentas pré-construídas são executadas automaticamente dentro do sandbox. Você só lida com ferramentas personalizadas por meio de eventos agent.custom_tool_use.
Você provisiona seu próprio sandbox para executar código gerado pelo agente.O sandbox da sessão cuida da execução de código, das operações de arquivo e do bash.
Você decide quando o loop termina.A sessão emite session.status_idle quando o agente não tem mais nada a fazer.

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-5-5",
        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-5-5",
    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: Os mesmos campos, agora na definição do agente.
  • Ferramentas personalizadas: Ainda declaradas com JSON Schema. A execução passa do tratamento inline para a resposta a eventos agent.custom_tool_use. Consulte Fluxo de eventos da sessão.
  • Configurações de pesquisa na web e busca na web: Os mesmos campos allowed_domains, blocked_domains, max_content_tokens e user_location, agora definidos uma única vez nas entradas web_search e web_fetch do array configs do conjunto de ferramentas do agente, em vez de em cada requisição. Os campos max_uses, citations e cache_control não estão disponíveis. Consulte Diferenças em relação às ferramentas da Messages API.
  • Contexto: Você ainda pode injetar contexto por meio do prompt do sistema, de recursos de arquivo ou de skills.

A partir 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 é executado em um processo que você opera, enquanto o Managed Agents é executado na infraestrutura da Anthropic. A maior parte da migração consiste em mapear os objetos de configuração do SDK para seus equivalentes no lado da API.

O que muda

Agent SDKManaged Agents
ClaudeAgentOptions(...) construído a cada execuçãoclient.beta.agents.create(...) uma única vez; o Agent é persistido e versionado no servidor. Consulte Configuração do agente.
async with ClaudeSDKClient(...) ou query(...)client.beta.sessions.create(...) e, em seguida, envie e receba eventos.
Funções definidas com @tool, despachadas automaticamente pelo SDKDeclare como {"type": "custom", ...} no Agent; seu cliente trata os eventos agent.custom_tool_use e responde com user.custom_tool_result. Consulte Ferramentas.
Ferramentas integradas são executadas no seu processo, sobre o seu sistema de arquivos{"type": "agent_toolset_20260401"} executa as mesmas ferramentas dentro do sandbox da sessão, sobre /workspace.
cwd, add_dirs apontam para caminhos locaisFaça upload ou monte arquivos como recursos da sessão.
system_prompt e a hierarquia de CLAUDE.mdUma única string system no Agent. Cada atualização que altera o agente produz uma nova versão no lado do servidor; fixe as sessões em uma versão específica para promover ou reverter sem um deploy. Consulte Configuração do agente.
mcp_servers configurados e autenticados em um só lugarDeclare os servidores no Agent; forneça as credenciais por meio de um Vault na Session.
permission_mode, can_use_toolpermission_policy por ferramenta (always_allow, always_ask ou auto); envie eventos user.tool_confirmation para chamadas que pausam aguardando sua aprovação.

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-5-5",
    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-5-5",
    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": "limited", "allow_package_managers": True},
    },
)

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 event in stream:
        match event.type:
            case "agent.message":
                print(
                    "".join(
                        block.text for block in event.content if block.type == "text"
                    )
                )
            case "agent.custom_tool_use":
                result = get_weather(**event.input)
                client.beta.sessions.events.send(
                    session.id,
                    events=[
                        {
                            "type": "user.custom_tool_result",
                            "custom_tool_use_id": event.id,
                            "content": [{"type": "text", "text": result}],
                        }
                    ],
                )
            case "session.status_idle":
                if event.stop_reason and event.stop_reason.type == "end_turn":
                    break

O Agent e o Environment são criados uma única vez e reutilizados entre sessões. A função da ferramenta ainda é executada 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 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 passam a ser responsabilidade do seu cliente.

Recurso do SDKAbordagem no Managed Agents
"Plan mode" (modo de planejamento)Execute primeiro uma sessão apenas de planejamento e, em seguida, uma segunda sessão para executar o plano.
"Output styles" (estilos de saída), "slash commands" (comandos de barra)Aplique-os no seu cliente antes de enviar user.message ou depois de receber agent.message.
Hooks PreToolUse / PostToolUseSeu cliente já vê cada evento agent.custom_tool_use antes de responder; coloque a lógica ali. Para ferramentas integradas, use permission_policy: always_ask para revisar cada chamada. auto permite que o servidor avalie cada chamada em seu lugar, mas, se o servidor avaliar uma chamada como segura, ela é executada sem chegar ao seu cliente.
max_turnsConte os turnos no lado do cliente.

Checklist de migração

  1. Crie um ambiente com a rede e os runtimes de que seu agente precisa.
  2. Porte seu prompt do sistema e sua seleção de ferramentas para uma definição de agente.
  3. Substitua seu loop: crie uma sessão com client.beta.sessions.create() e faça streaming dos seus eventos com client.beta.sessions.events.stream().
  4. Para quaisquer arquivos locais que o agente lê, faça upload deles por meio 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 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 normalmente é uma alteração de um único campo: atualize model na sua definição de agente e a alteração entra em vigor na próxima sessão que você criar.

ant apply agent.md
agent.md
---
name: Task Runner
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a task automation agent. Complete the task you are given end to end.

A maioria das mudanças de comportamento no nível do modelo documentadas no guia de migração da Messages API não exige nenhuma ação da sua parte:

  • Mudanças nos 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.
  • O preenchimento prévio de mensagens do assistente não existe no modelo de sessão baseado em eventos, portanto sua remoção em modelos mais novos não tem efeito.
  • O escape de JSON nos argumentos de ferramentas é analisado pelo runtime antes de você receber os 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.

Was this page helpful?