Como usar os Claude Managed Agents: um guia de configuração passo a passo

Criar um agente de IA envolve muito mais do que apenas fazer uma chamada de modelo. Você precisa gerenciar o loop do agente, executar ferramentas, fornecer um ambiente de execução, manter o estado da sessão, lidar com permissões e observar o que o agente está fazendo.

Os Claude Managed Agents cuidam de grande parte dessa infraestrutura para você. Em vez de criar e operar seu próprio runtime de agente, você define o agente, configura onde ele será executado e cria sessões para que ele realize tarefas. O runtime gerenciado cuida das chamadas de modelo e da execução de ferramentas, enquanto sua aplicação interage com o agente por meio de eventos.

Neste guia, mostraremos como usar os Claude Managed Agents passo a passo desde a criação do seu primeiro agente e a configuração do seu ambiente até a execução de uma sessão, adição de ferramentas e servidores MCP, e o tratamento de eventos do agente.

Se você quiser uma base conceitual primeiro, consulte nosso guia sobre o que são os Claude Managed Agents e como a arquitetura funciona. Este guia pressupõe que você está pronto para colocar a mão na massa.

Pré-requisitos

Antes de criar um Managed Agent, você precisará de:

1. Uma conta no Claude Console
2. Uma chave de API da Anthropic
3. O SDK da Anthropic
4. Python, TypeScript ou outra linguagem compatível

Passo 1: Instale a CLI e o SDK

Para Python, instale o SDK:

Em seguida, defina sua chave de API como uma variável de ambiente:

A Anthropic também fornece uma ant CLI para gerenciar recursos de Agentes Gerenciados.

O SDK lê a chave do seu ambiente, portanto, você não precisa incluí-la diretamente no código da sua aplicação.

Habilite a API de Agentes Gerenciados

O Claude Managed Agents está disponível atualmente por meio da API beta da Anthropic. O beta de Agentes Gerenciados é identificado pelo:

managed-agents-2026-04-01cabeçalho beta.

Ao usar o SDK oficial, ele lida com esse cabeçalho para você quando você acessa as APIs de Agentes Gerenciados.

A configuração básica do seu cliente é assim:

Neste ponto, sua aplicação está pronta para trabalhar com a API de Agentes Gerenciados.

O próximo passo é criar o agente propriamente dito - definindo qual modelo do Claude ele usa, quais instruções ele segue e quais ferramentas ele pode acessar.

Passo 2: Defina seu Agente

Um agente é um arquivo Markdown. O frontmatter contém a configuração do agente, enquanto o corpo contém seu prompt de sistema.

Aqui está um exemplo de um agente que redige notas de lançamento a partir de um repositório:‍


Oagent_toolset_20260401 O conjunto de ferramentas dá ao agente acesso às ferramentas pré-criadas da Anthropic, incluindo recursos como comandos de shell e operações de arquivo. Você também pode configurar ferramentas individuais se não precisar do conjunto completo. Consulte a referência de ferramentas para ver as opções disponíveis.

Salve a configuração como release-notes-agent.md, e então aplique-a com a ant CLI:

ant apply release-notes-agent.md


Isso cria o agente e retorna seu ID.

O agente é um recurso persistente. Você o cria uma vez e então referencia seu ID sempre que iniciar uma sessão que o utilize — você não recria o agente para cada tarefa.

Em seguida, você criará o ambiente onde as sessões do seu agente serão executadas.

Passo 3: Criar um Ambiente

O ambiente define o sandbox onde as sessões do seu agente serão executadas.

Crie um arquivo environment.yaml :‍


Depois, aplique-o:

ant apply environment.yaml


Você também pode aplicar o agente e o ambiente juntos:

Onetworking: unrestricted define que o sandbox tenha acesso irrestrito à rede. Para agentes que trabalham com sistemas internos ou dados confidenciais, use uma configuração de rede mais restritiva.

Agora você tem os dois recursos necessários para executar um agente:

• Agente: define o que o agente é e o que ele pode fazer.
• Ambiente: define onde o agente é executado.

Em seguida, você criará uma sessão que os conecta.

Passo 4: Iniciar uma sessão

Uma sessão é uma instância em execução do seu agente trabalhando em uma tarefa específica.

Crie uma sessão passando os IDs do seu agente e do seu ambiente:

O ID da sessão identifica esta execução específica. Você o usará para enviar mensagens, transmitir eventos e continuar interagindo com o agente.

O mesmo agente pode ter várias sessões. Por exemplo, seu Release Notes Agent poderia executar uma sessão separada para cada lançamento, mantendo a mesma configuração de agente.

Passo 5: Enviar uma mensagem e transmitir a resposta

Com a sessão em execução, envie uma tarefa para o agente.

Abra o fluxo de eventos primeiro e, em seguida, envie a mensagem do usuário:‍


Por trás desta chamada, o runtime gerenciado provisiona o sandbox a partir da configuração do seu ambiente, inicia o loop do agente, permite que o Claude selecione e execute ferramentas e transmite os eventos de volta para sua aplicação.

Os três tipos de eventos acima são aqueles que você normalmente tratará primeiro:

• agent.message — o agente envia uma resposta.
• agent.tool_use — o agente utiliza uma ferramenta.
• session.status_idle — o agente concluiu seu trabalho atual.

Para a lista completa de eventos, incluindo mudanças de status e erros, consulte a referência de eventos e streaming.

Neste ponto, você tem um Agente Gerenciado funcional: você o definiu, forneceu um ambiente de execução, iniciou uma sessão e enviou uma tarefa para ele.

A seguir, veremos como direcionar um agente em execução e lidar com sessões de longa duração.

Passo 6: Direcionar um agente em execução

Você não precisa esperar que um agente termine para mudar sua direção.

Você pode enviar um user.interrupt evento para interromper o turno atual, seguido por um user.message com a nova instrução:

A interrupção interrompe a resposta atual do modelo e devolve o controle à sessão. Se o agente estiver no meio de uma chamada de ferramenta, a interrupção pode levar mais tempo para ser aplicada enquanto essa ferramenta é concluída. Assim que a interrupção é processada, a sessão retorna ao estado idle, e a seguinte user.message inicia o próximo turno.

Isso é útil para tarefas de longa duração em que você percebe que o agente está seguindo na direção errada. Em vez de encerrar a sessão e começar tudo de novo, você pode reutilizar a mesma sessão e redirecioná-la com contexto adicional.

Você também pode interromper uma sessão em execução sem enviar imediatamente uma nova instrução:‍


A sessão permanece disponível após a interrupção, para que você possa inspecionar o que aconteceu e decidir o que enviar em seguida.

A seguir, você verá como lidar com o que acontece quando sua aplicação perde a conexão com uma sessão em execução.

Passo 7: Lidar com desconexões e retomar sessões

Uma conexão de streaming pode cair enquanto um agente ainda está trabalhando. Isso não significa que a sessão ou seu trabalho foram perdidos.

O Managed Agents mantém o histórico de eventos da sessão no servidor, para que sua aplicação possa se reconectar à mesma sessão em vez de reiniciar a tarefa.

O importante é persista o ID da sessão ao criar a sessão:‍

Se sua aplicação perder a conexão, use o mesmo session_id para reconectar e continuar interagindo com a sessão.

Isso é importante para agentes de longa duração. O fechamento de uma aba do navegador, a reinicialização de um processo ou uma falha temporária de rede não devem forçar o agente a iniciar a tarefa do zero.

Para aplicações em produção, trate o ID da sessão como um estado durável da aplicação: armazene-o em um local onde sua aplicação possa recuperá-lo após a reinicialização de um processo, em vez de mantê-lo apenas na memória.

O fluxo de eventos é apenas a conexão entre sua aplicação e a sessão em execução. A sessão em si continua a existir independentemente dessa conexão.

A seguir, veremos como dar ao seu agente capacidades adicionais com servidores e ferramentas MCP.

Executando em sua própria infraestrutura

O sandbox na nuvem é o padrão, e é o motivo pelo qual algumas equipes não conseguem implementar isso. Se regras de residência de dados ou conformidade impedirem a execução hospedada pela Anthropic, sandboxes auto-hospedados permitem que as sessões sejam executadas na infraestrutura que você controla, enquanto a Anthropic continua operando o loop.

Observe o que muda e o que não muda: a execução vai para sua infraestrutura, a orquestração permanece com a Anthropic.

Agendamento de execuções recorrentes

Para agentes que devem ser executados periodicamente em vez de sob demanda, implantações agendadas executam uma sessão em um cronograma. Uma triagem noturna ou um relatório semanal se encaixam aqui sem que você precise configurar um agendador.

Mantendo a fatura sob controle

O Claude Managed Agents cobra com base em duas dimensões: tokens de modelo e uma taxa de execução de aproximadamente US$ 0,08 por hora de sessão, que cobre o tempo de container.

Três coisas importantes para saber desde o início:

O tempo ocioso é gratuito, portanto, uma sessão aguardando uma interação humana não gera custos de execução. Não há desconto para processamento em lote, então o trabalho que você normalmente processaria dessa forma custa o mesmo aqui. Além disso, a pesquisa na web é cobrada separadamente do conjunto de ferramentas.

A cobrança por hora de sessão costuma ser o valor menor. Os tokens predominam, e a quantidade de tokens que uma execução consome depende de como o sistema gerencia o contexto, e não de algo que você possa configurar. Detalhamos a estrutura completa de custos em preços do Claude Managed Agents.

Onde as equipes atingem limites

Duas limitações costumam surgir após o funcionamento do protótipo. O modelo é da Anthropic, portanto, não é possível mudar para um mais barato conforme seu volume aumenta. E o loop é operado pela Anthropic, então a estratégia de contexto não é algo que você possa ajustar.

Se você está apenas avaliando e ainda não se comprometeu, alternativas ao Claude Managed Agents cobre o cenário.

TrueForge: Uma alternativa de código aberto aos agentes gerenciados do Claude, até 75% mais barata

TrueForgeé o harness de agentes de código aberto e agnóstico a fornecedores da TrueFoundry, voltado para equipes que desejam mais controle sobre como seus agentes operam em produção. Em vez de vincular o runtime a um único provedor de modelo, o TrueForge permite que você utilize seus próprios modelos, servidores MCP e infraestrutura, enquanto gerencia o loop do agente, execução de ferramentas, gerenciamento de contexto, aprovações e sandboxing.

Onde um agente auto-hospedado como o Hermes deixa grande parte da infraestrutura de produção a cargo do desenvolvedor, o TrueForge fornece o plano de controle necessário para operar agentes entre equipes e ambientes. Isso inclui acesso centralizado a MCP e credenciais, aprovações humanas, execução em sandbox, observabilidade e governança.

Você pode executá-lo localmente comnpx @truefoundry/trueforgeou implantá-lo para uma equipe usando Docker Compose ou Helm.

O TrueForge também separa o runtime do agente da camada de modelo. Isso significa que as equipes podem trocar de modelos ou rotear cargas de trabalho para diferentes provedores sem precisar reconstruir o agente. Combinado com o AI Gateway da TrueFoundry, as equipes também podem aplicar roteamento de modelos e controles de custo para evitar o uso de modelos de ponta caros em tarefas que não os exigem. O resultado é um meio-termo entre um runtime totalmente gerenciado e a construção de toda a infraestrutura do agente por conta própria:um harness de agentes de código aberto com os controles operacionais necessários para executar agentes em produção em escala.‍

No benchmark da TrueFoundry comparado aos agentes gerenciados do Claude, o TrueForge alcançou aproximadamente a mesma precisão de tarefa usando cerca de 40% do número de tokens quando ambos foram executados no Opus 4.8, tornando-o cerca de 30% mais barato por execução. Quando o mesmo benchmark foi executado com o GLM-5.2 no TrueForge, ele alcançou a mesma pontuação de ~11/14 por cerca de US$ 2,90 por execução, contra US$ 11,80 dos agentes gerenciados do Claude, aproximadamente75% menos custo.

A TrueFoundry também oferece uma segunda alavanca para reduzir os custos de modelo por meio doAuto Routing doAI Gateway. Em vez de enviar todas as solicitações para um modelo de ponta, o Auto Routing classifica as solicitações por complexidade e as direciona para diferentes níveis de modelo. No benchmark da TrueFoundry com 550 prompts, o roteamento entre Haiku, Sonnet e Opus reduziu o custo em 69%, mantendo 98% da qualidade original, e a latência média caiu de 7,6 segundos para 4,0 segundos. Em tráfego real de produção, a redução geral de custos chegou a 80%.

Essas duas camadas abordam partes diferentes da equação de custos.O TrueForge reduz a sobrecarga de executar o próprio agente, enquantoo roteamento de modelos permite que você evite usar um modelo caro quando a tarefa não exige um.. Para equipes que executam agentes em escala, ter ambos os controles pode ser mais importante do que apenas o preço do modelo.

O TrueForge é de código aberto elicenciado sob MIT,enquanto o AI Gateway da TrueFoundry adiciona a camada operacional que as equipes precisam ao passar de agentes individuais para a produção: acesso centralizado a modelos, orçamentos, proteções (guardrails), gerenciamento de credenciais e rastreamento unificado.

Se você está comparando o Claude Managed Agents com uma arquitetura mais configurável, vale a pena considerar a TrueFoundry quandoflexibilidade de modelo, controle de infraestrutura e otimização de custos de agentesimportam tanto quanto o próprio tempo de execução do agente.

An Open-Source Alternative to Claude Managed Agents, Up to 75% Cheaper

Run production-ready AI agents on your own infrastructure with TrueForge, using your choice of models, tools, and sandbox providers.

View on GitHub

Docs

O que os Agentes Gerenciados de Camada não cobrem

Os Agentes Gerenciados controlam muito bem o tempo de execução de um único agente. O que eles não fazem é controlar umafrota, que é o problema que surge por volta do quinto agente, quando o financeiro pergunta quanto tudo isso custa e a segurança pergunta quem aprovou as credenciais.

Um ambiente de agente controlacomo um agente funciona. Um Gateway de IA controlacomo esse agente acessa modelos.

Por exemplo, uma organização pode executar agentes usando o Claude Managed Agents ou o TrueForge enquanto roteia as solicitações de modelo por meio de um Gateway de IA.
OGateway de IAfica à frente de cada chamada de modelo e de MCP que um agente faz, aplicando acesso centralizado a modelos, orçamentos por equipe, limites de taxa, diretrizes de segurança, gerenciamento de credenciais e rastreamento unificado — independentemente dos agentes e frameworks que suas equipes estejam executando. Ele suporta mais de 1.000 LLMs por meio de uma única API compatível com OpenAI, adiciona cerca de 3 a 4 ms de sobrecarga e lida com mais de 350 RPS em uma única vCPU, para que possa permanecer no caminho crítico de um agente de longa execução sem se tornar um gargalo. Ele é executado em sua própria VPC, localmente ou em ambientes isolados (air-gapped).

Isso se torna particularmente útil quando uma organização executa agentes em vários modelos, em vez de depender de um único provedor de modelos.

Tempo de execução do agente:gerencia o loop, as ferramentas, o estado e a execução do agente.

Gateway de IA:gerencia o acesso a modelos, roteamento, políticas, observabilidade e abstração de provedores.

Essa separação permite que as equipes alterem ou adicionem modelos sem precisar reprojetar o agente em si.

Perguntas frequentes

P: Como usar os Claude Managed Agents?

R: Instale a ant CLI e o SDK da Anthropic, defina um agente em um arquivo markdown com seu modelo, system prompt e ferramentas, declare um ambiente em YAML para o sandbox, crie uma sessão referenciando ambos e transmita seus eventos. Agentes e ambientes são criados uma vez e reutilizados; as sessões são por tarefa. Todo o processo leva cerca de dez minutos.

P: É necessário usar a CLI ant ou posso fazer tudo pelo SDK?

R: A CLI é uma conveniência, não uma exigência. A Anthropic documenta caminhos via cURL e SDK nativo para cada etapa no guia de início rápido, abrangendo Python, TypeScript, Java, Go, C#, Ruby e PHP. O que a CLI adiciona é o ant applyeclaude-lock.json, que mantém os IDs de agentes e ambientes versionados junto com seu código, em vez de colados em alguma configuração.

P: Os Claude Managed Agents podem ser executados na minha própria infraestrutura?

R: Em parte. Sandboxes auto-hospedados permitem que as sessões sejam executadas em infraestrutura sob seu controle, o que geralmente é suficiente para requisitos de residência de dados. A camada de orquestração permanece com a Anthropic de qualquer forma, portanto, isso não é o mesmo que executar toda a pilha por conta própria.

P: Ele se integra à minha stack de observabilidade existente?

R: A camada de gateway da TrueFoundry é compatível com OpenTelemetry e se integra ao Grafana, Datadog, Prometheus ou qualquer ferramenta que você já utilize, rastreando cada solicitação desde o prompt até a execução da ferramenta e do modelo. Isso é importante quando agentes de diferentes frameworks precisam ser monitorados em um só lugar.

P: Como faço para governar modelos e servidores MCP em muitos agentes?

R: Através de um gateway, quando as chaves de API por equipe deixam de ser escaláveis. O Gateway de IA da TrueFoundry coloca mais de 1.000 LLMs atrás de uma única API compatível com OpenAI, com aproximadamente 3 a 4 ms de latência adicional e mais de 350 RPS em uma única vCPU, com RBAC, orçamentos, guardrails e rotação de credenciais. Agentes em Claude Managed Agents, LangGraph ou qualquer outro são governados da mesma forma.

Leituras relacionadas

• O que são os Claude Managed Agents?: a arquitetura por trás das etapas acima
• Preços dos Claude Managed Agents: o detalhamento completo de custos com um exemplo prático
• Claude Agent SDK vs. Claude Managed Agents: qual executar em produção
• Alternativas ao Claude Managed Agents: o cenário, caso você ainda esteja avaliando
• Melhores práticas para o ambiente de testes de agentesdez regras que se aplicam independentemente do harness que você escolher

Conclusão

Saber como usar os Claude Managed Agents resume-se basicamente a conhecer quatro objetos e a ordem em que você os cria: agente, ambiente, sessão e eventos. A configuração é realmente rápida. As partes que merecem atenção são aquelas que o guia de início rápido ignora, nomeadamente o tratamento de desconexões, a configuração de rede no seu ambiente e a compreensão de qual parte da sua fatura você realmente pode influenciar.

Se você chegar ao ponto em que a escolha do modelo e a estratégia de contexto começam a importar mais do que a velocidade de configuração, esse é o sinal para considerar um harness aberto. npx @truefoundry/trueforge executa um localmente em cerca de um minuto, ou agende uma demonstração se você preferir testá-lo com a sua carga de trabalho.