Guia de Início Rápido para Claude Managed Agents 2026

Na primeira vez que tentei executar uma sessão de Managed Agents, recebi um erro 400 logo no primeiro curl. Não na criação do agente. Não no ambiente. No endpoint de stream. Copiei meu cabeçalho da requisição de criação — anthropic-beta: managed-agents-2026-04-01 — e a API de streaming o rejeitou. Acontece que o endpoint de streaming estava, naquele momento na documentação, referenciando um cabeçalho beta diferente. Perdi quarenta minutos com isso.

Se você está tentando colocar sua primeira sessão de Managed Agents funcionando de ponta a ponta hoje, este é o caminho que eu realmente percorri. Olá, sou a Dora! Primeiro o cabeçalho beta, porque é aí que metade das falhas acontece. Depois agente, ambiente, sessão, stream. E um ponto de verificação de custo no final, porque o tempo de execução da sessão continua acumulando enquanto você depura.

Antes de Começar

Você precisa de uma chave de API da Anthropic com acesso ao Managed Agents. Não há lista de espera no momento — qualquer chave existente funciona na versão beta pública.

O cabeçalho beta é obrigatório. Todo endpoint de Managed Agents requer anthropic-beta: managed-agents-2026-04-01. De acordo com a visão geral do Managed Agents da Anthropic, o SDK define isso automaticamente. Se você estiver usando curl puro, adicione-o a cada requisição manualmente. Essa é a causa mais comum de erros 400 que já vi em relatórios da comunidade.

Se você usar o SDK oficial (anthropic para Python, @anthropic-ai/sdk para TypeScript), verifique se está em uma versão que inclui suporte a agentes beta. Versões mais antigas não terão client.beta.agents ou client.beta.sessions.

A escolha do modelo importa aqui. O Opus 4.7 é mais inteligente para raciocínio de agente em horizontes longos. O Sonnet 4.6 é mais barato e rápido por token. Para uma execução de início rápido, o Sonnet 4.6 é suficiente. Se sua carga de trabalho real envolve depuração, planejamento ou cadeias longas de ferramentas, o Opus 4.7 justifica seu preço.

Etapa 1 — Defina Seu Agente

Um agente, no Managed Agents, é um objeto de configuração, não um processo. Você define nome, modelo, prompt de sistema e acesso a ferramentas uma vez, e reutiliza em várias sessões.

Definição mínima viável do quickstart oficial:

python

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-opus-4-7",
    system="You are a helpful coding agent.",
    tools=[{"type": "agent_toolset_20260401"}],
)

O tipo de ferramenta agent_toolset_20260401 desbloqueia o conjunto completo de ferramentas integradas — bash, leitura/escrita de arquivos, pesquisa na web, busca na web, execução de código. Você pode restringir o escopo mais tarde. Para uma primeira execução, deixe amplo para ver o que o agente realmente escolhe usar.

Salve agent.id. Toda sessão o referencia.

Etapa 2 — Crie um Ambiente

Um ambiente define o contêiner isolado. Para a maioria das primeiras execuções:

python

env = client.beta.environments.create(
    name="quickstart-env",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

Salve env.id. Se seu agente acessa apenas seu próprio sistema de arquivos, "networking": {"type": "limited"} é mais seguro e está bem documentado no cookbook para resposta a incidentes SRE.

Etapa 3 — Inicie uma Sessão

Uma sessão vincula um agente a um ambiente. Criar uma sessão não inicia o trabalho. Apenas provisiona. O trabalho começa quando você envia um evento de usuário.

python

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=env.id,
    title="Quickstart session",
)

Esse padrão — criar e depois conduzir com eventos — é onde o modelo de máquina de estados da referência de sessões faz sentido. A sessão persiste. Você pode enviar mais eventos depois. O sistema de arquivos sobrevive entre as rodadas.

Etapa 4 — Transmita Eventos

Abra o stream, envie a mensagem do usuário, leia os eventos até session.status_idle:

python

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": "Generate first 20 Fibonacci numbers, save to fib.txt"}],
        }],
    )
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    print(block.text, end="")
            case "agent.tool_use":
                print(f"\n[tool: {event.name}]")
            case "session.status_idle":
                break

Os nomes de eventos seguem o padrão {domínio}.{ação}. O esquema completo está na documentação de eventos e streaming. O campo processed_at importa: se for null, o evento está na fila, ainda não executado. Eu errei isso na minha primeira execução e achei que as ferramentas estavam falhando silenciosamente.

Pontos de Verificação de Custo

O Managed Agents cobra duas coisas: taxas padrão de token mais $0,08 por hora de sessão de tempo de execução ativo. De acordo com a página oficial de preços, o tempo de execução acumula por milissegundo — mas apenas enquanto o status for running. Tempo ocioso e sessões encerradas não são cobrados.

O que isso significa na prática:

• Uma sessão que você esqueceu de fechar durante a depuração: ainda acumulando (se estiver em execução).
• Pesquisa na web: $10 por 1.000 chamadas, cobrado separadamente. Agentes de pesquisa atingem esse limite rapidamente.
• Verifique as sessões ativas no rastreamento do Console antes de encerrar o dia. Verifique você mesmo o caminho atual da interface — o layout do Console tem sido atualizado.

Erros Comuns

Cabeçalho beta ausente ou incorreto. Erro 400, frequentemente com uma mensagem sobre endpoints não suportados. Solução: confirme managed-agents-2026-04-01 em cada chamada HTTP direta. Se você estiver usando o SDK e ainda assim enfrentar isso, atualize o SDK.

Limites de taxa. Os endpoints de criação têm limite de 60 rpm; endpoints de leitura, 600 rpm. Os limites de nível da organização ainda se aplicam adicionalmente. Erros 429 significam esperar com jitter, não tentar novamente imediatamente.

Loop silencioso de ferramentas. O agente continua chamando ferramentas, mas não produz nenhuma mensagem final. Verifique os rastreamentos da sessão — geralmente é um requires_action não tratado que nunca recebeu uma resposta de volta.

Perguntas Frequentes

P1: Como habilito a coordenação multi-agente no Managed Agents?

Multi-agente (junto com memória e resultados) ainda é um recurso de visualização de pesquisa. Você solicita acesso separadamente pelo Claude Console. O padrão de coordenação — orquestrador delegando para agentes chamáveis — está documentado em sessões multiagente, mas você não pode usá-lo até que o sinalizador de visualização esteja ativado para sua organização.

P2: Posso inspecionar quais ferramentas o agente chamou durante uma sessão?

Sim. Use client.beta.sessions.events.list(session.id) para acesso programático, ou a visualização de rastreamento do Console para uma linha do tempo cronológica com tokens e timestamps por evento.

P3: Onde fica o cookbook oficial do Managed Agents?

Os tutoriais ficam no site do Claude Cookbook — o notebook iterate-fix-failing-tests é a melhor primeira leitura. O notebook operate-in-production cobre vaults, MCP e webhooks depois que você passar do estágio hello-world.

P4: Existe uma forma de testar sem incorrer em custos de tempo de execução de sessão?

Não existe uma camada gratuita dedicada ao Managed Agents. Os créditos gratuitos padrão da API cobrem isso. Mantenha as sessões curtas durante o desenvolvimento e feche-as quando parar de trabalhar. Sessões ociosas não são cobradas, mas as em execução sim — e “em execução” inclui agentes em loop silencioso.

P5: Qual é o melhor modelo para tarefas de longa duração no Managed Agents?

Depende do que “longa duração” significa. Para raciocínio de várias horas com uso intenso de ferramentas, Opus 4.7. Para loops de alto volume e mais simples, o Sonnet 4.6 com cache de prompt reduz drasticamente o custo. Ainda estou testando o Opus 4.7 em sessões de 2 horas ou mais. É até aí que chegam meus dados. Mais informações em breve.

Ainda verificando como a compactação se comporta além da marca de duas horas. Execute você mesmo — isso vai te dizer mais do que eu posso.

Posts anteriores:

• Godmod3 AI Explicado
• Claude Opus 4.7 Modelo Unificado & Camada de API
• Fiação de Ferramentas para Fluxo de Trabalho Agêntico: Padrões e Armadilhas
• GLM-5V Turbo vs GPT-4o Vision UI & Codificação
• Como Configurar o G0DM0D3 OpenRouter 2026