Agentes Gerenciados do Claude: Configuração, aplicação e Trade-offs do SDK

Claude Managed Agents é o harness de agente hospedado da Anthropic, em beta no momento da escrita. Executa o loop do agente, a sandbox e o log de sessão do lado da Anthropic, e cobra o tempo de execução a $0,08 por hora de sessão além dos tokens, com tempo ocioso gratuito. Você envia eventos e faz stream dos resultados em vez de manter essa camada você mesmo. Este post é um passo a passo documentado do que o serviço hospeda, como o fluxo de trabalho baseado em arquivo ant apply se comporta, e onde o Agent SDK ainda é a melhor opção.

Nota: Managed Agents é um serviço em beta no momento da escrita. Trate tudo aqui de acordo.

O que os Agentes Gerenciados do Claude Hospedam para Você

A versão curta: a Anthropic executa o harness do agente, o sandbox de computação, e o log de sessão. Você envia eventos e transmite resultados de volta via HTTP. É isso. Você não gerencia o ciclo de vida do contêiner, o ambiente de execução de ferramentas, ou a lógica de retry para falhas transitórias.

Mais especificamente, aqui está o que fica do lado da Anthropic:

• O loop do agente. Claude decide quando chamar uma ferramenta, processa o resultado e itera sem você escrever a orquestração.
• Ferramentas integradas. Bash, operações de arquivo, busca na web, todas acessíveis através do tipo de ferramenta agent_toolset_20260401. Você não configura estas por conta própria.
• Sandboxes por sessão. Cada sessão obtém seu próprio ambiente de execução isolado. Sem vazamento entre sessões.
• Logs de sessão duráveis. Se sua aplicação cair da stream, a sessão não desapareceu. Você reconecta e se atualiza.
• Integração MCP. Ferramentas customizadas se anexam como servidores MCP. Claude dispara a ferramenta; seu serviço retorna resultados sobre o protocolo. Nada para agrupar em seu deploy.
• Cache de prompt. Integrado no nível da plataforma, o que importa uma vez que seus prompts de sistema ficam longos.

O que você mantém do seu lado: a definição do agente, suas implementações de servidor MCP, e qualquer lógica de negócio que decide quando iniciar ou parar uma sessão. Essa é uma superfície muito menor para possuir do que um harness completo.

Hatchworks cobre a divisão de infraestrutura claramente: a inferência pode começar antes de um contêiner ser provisionado, o que frequentemente resulta em mais rápido para agentes cold-start mesmo que cada chamada de ferramenta cruze um limite de serviço.

Quando Escolher Agentes Gerenciados, o Agent SDK, ou Claude Code

A confusão que mais vejo é pessoas tratando esses três como intercambiáveis. Eles não são.

Claude Code é uma ferramenta de terminal. Ótima para um desenvolvedor executando tarefas localmente. Não é algo que você incorpora em um produto.

O [Agent SDK](/blog/claude-agent-sdk-guide-2026/) executa o loop do agente dentro do seu próprio processo, na sua própria infraestrutura. Acesso direto ao sistema de arquivos, conectividade de rede privada, controle total sobre o ambiente de execução. Você escolhe o SDK quando precisa de coisas como gravações de arquivos locais sem limite de serviço, infraestrutura existente que você já pagou, ou flexibilidade multi-provedor no nível do modelo (embora você esteja preso ao Claude de qualquer forma com o SDK por enquanto).

Managed Agents é a resposta hospedada. Você obtém sessões duráveis, computação isolada em sandbox e observabilidade integrada sem construir nada disso. O modelo de custo é por hora de sessão, não apenas por token, portanto recompensa sessões curtas e focadas e penaliza as longas e ociosas.

Aqui está a tabela de decisão:

Uma coisa vale a pena destacar: conforme observado no guia do SDK em hidekazu-konishi.com, um caminho comum é fazer protótipo localmente com o SDK e migrar para Managed Agents assim que quiser sandboxes hospedadas que prefira não operar.

Se seu desafio específico é construir o produto agentic completo em torno disso, nosso trabalho de engenharia agentic pode poupar você de alguns erros.

Criar um agente e inspecionar uma sessão

Este é um passo a passo documentado, não uma execução de produção verificada. Estou descrevendo o procedimento da documentação oficial; considere qualquer código aqui ilustrativo até executá-lo com sua própria chave.

Para chegar a um agente em funcionamento são necessárias quatro etapas.

1. Crie uma definição de agente. É aqui que você descreve o que o agente pode fazer: quais ferramentas integradas ele tem acesso, quais servidores MCP pode chamar e qual é seu prompt de sistema.
2. Crie um ambiente de execução. A plataforma provisiona um sandbox com escopo para sua definição de agente.
3. Inicie uma sessão. Você envia um evento de início com a entrada do seu usuário. A ID da sessão volta imediatamente.
4. Transmita eventos. Chamadas de ferramentas, resultados intermediários e a resposta final chegam no fluxo. Você as processa em sua aplicação.

Nos sete SDKs oficiais (Python, TypeScript, Go, Java, C#, Ruby, PHP), a forma do fluxo é consistente mesmo que a sintaxe difira. O tipo de ferramenta agent_toolset_20260401 é o que desbloqueia o conjunto de ferramentas integradas completo em uma única declaração. Você não enumera bash, operações de arquivo e busca na web individualmente.

Quando uma sessão está em execução, você pode inspecioná-la através do endpoint de log de sessão. É aqui que o benefício de durabilidade se mostra concretamente. Abandone o fluxo, reconecte e o log é reproduzido de onde você parou. Para tarefas de longa duração onde o cliente pode se desconectar, isso importa muito.

Gerenciar recursos com ant apply e claude-lock.json

A CLI ant é uma ferramenta separada do próprio SDK. Instale via Homebrew. Ela fornece um fluxo de trabalho baseado em arquivo para declarar seus recursos de agente (agentes, ambientes, registros de servidor MCP) em arquivos de configuração e depois aplicá-los à plataforma.

A documentação do ant apply descreve o comando central:

ant apply

Antes de tocar em produção, execute a flag de dry-run:

A CLI ant é uma ferramenta separada do próprio SDK. Instale via Homebrew. Ela fornece um fluxo de trabalho baseado em arquivo para declarar seus recursos de agente (agentes, ambientes, registros de servidor MCP) em arquivos de configuração e depois aplicá-los à plataforma.

Isso mostra o que o apply faria. Ressalva importante da documentação oficial: --dry-run pode retornar exit 0 mesmo em um plano que seria bloqueado na hora do apply. Não trate um dry-run limpo como garantia de que o apply completo terá sucesso. Verifique o apply real em um ambiente de staging primeiro.

O arquivo claude-lock.json é o lockfile que registra o estado atual de seus recursos implantados. Pense nele como um package-lock.json — ele fixa versões de recursos e previne desvios entre o que você declarou e o que a plataforma está executando. Após qualquer ant apply, o lockfile se atualiza para refletir o novo estado. Faça commit dele. Trate mudanças nele como significativas na revisão de código.

Um ponto de serialização que confunde as pessoas: applies parciais. Se ant apply falhar no meio do caminho, alguns recursos estarão no novo estado e outros não. O lockfile refletirá a atualização parcial. Antes de executar ant apply novamente, verifique o lockfile contra o que realmente foi implantado, reconcilie manualmente se necessário e depois execute novamente. Rodar um segundo apply sobre um estado parcial quebrado sem verificar primeiro pode deixar recursos em uma condição intermediária confusa.

Isso é diferente de ferramentas como Terraform que têm um step plan separado na CLI. Não há ant plan. O dry-run é o que você tem para preview. Projete sua CI de acordo.

Revise Mudanças na CI e Trate Falhas Parciais

Para equipes rodando múltiplos desenvolvedores contra o mesmo ambiente Managed Agents, aplicar mudanças da CI em vez de máquinas locais é fortemente recomendado. Caso contrário você terá race conditions no lockfile.

Aqui está o workflow que eu sugeriria:

1. PR abre. CI executa ant apply --dry-run e posta o output como comentário na PR.
2. Reviewer verifica o diff, incluindo mudanças no lockfile.
3. Ao fazer merge para main, CI executa ant apply contra o ambiente staging.
4. Promova para production apenas depois que o apply de staging tiver sucesso e as sessions se comportarem corretamente.

O requisito de serialização é a principal restrição operacional. Você não pode rodar duas chamadas ant apply em paralelo contra o mesmo ambiente. Se seu sistema de CI conseguir fazer queue de múltiplos merges rapidamente, force um lock no nível do pipeline (a maioria das plataformas de CI tem uma configuração de concurrency group exatamente para isso).

Para tratamento de falha parcial, o checklist fica assim:

• Verifique o lockfile imediatamente após um apply falhado. Anote quais recursos atualizaram e quais não.
• Não execute ant apply cegamente. Leia o erro primeiro.
• Se o estado parcial é seguro deixar enquanto você investiga, deixe. Se recursos estão em um estado intermediário quebrado, você pode precisar fazer rollback manual antes de aplicar novamente.
• Uma vez resolvido, execute ant apply --dry-run novamente antes do apply completo para confirmar que o plano ficou correto.

Porque --dry-run pode retornar exit 0 em um plano bloqueado, não pule o passo de revisão mesmo se o dry-run parecer limpo.

Limitações Beta, Custos e um Checklist de Implantação

Managed Agents é um serviço beta. Essa designação importa para qualquer coisa crítica para produção. Features podem mudar. Preços podem mudar. Garantias de disponibilidade em beta não são as mesmas que GA.

Custos. A taxa publicada é $0,08 por hora de sessão, medida apenas enquanto a sessão está em execução (tempo ocioso não é cobrado), com tokens cobrados no topo nas taxas de modelo padrão. Isso torna relativamente previsível para sessões curtas e focadas em tarefas. Para sessões de longa duração com uso substancial de ferramentas, você vai querer monitorar a duração da sessão ativamente. O guia vibecodingacademy coloca isso em contexto: a competitividade de custo depende do tempo de engenharia que você gastaria construindo infraestrutura auto-gerenciada equivalente, que é real e frequentemente subestimado.

Restrições atuais em beta:

• Ferramentas customizadas roteiadas por servidores MCP, não por funções in-process. Se seu tooling customizado é fortemente acoplado ao runtime da sua aplicação, você precisará extrair ele em um servidor MCP primeiro.
• Observabilidade de session é através do endpoint de session log. Não há um equivalente de dashboard built-in ao que você construiria você mesmo em cima do SDK.
• aplicações parciais com falha semântica exigem reconciliação manual. Não há rollback automático.
• Aplicações serializadas significam que a taxa de transferência do pipeline é limitada pela duração da aplicação.

Checklist pré-implantação:

1. Definição do agente revisada e prompt do sistema finalizado
2. Servidores MCP registrados e testados independentemente antes de conectar ao agente
3. claude-lock.json commitado e tratado como um artefato revisado
4. Saída de ant apply --dry-run revisada por uma segunda pessoa antes de qualquer aplicação em produção
5. Monitoramento de duração de sessão em vigor (fique atento a sessões inesperadamente longas)
6. Procedimento de recuperação de falha parcial documentado para seu time
7. Ambiente de staging validado antes da promoção para produção
8. Alertas de orçamento configurados no nível da conta dado que o preço em beta pode mudar

Uma última coisa sobre a questão build-vs-buy. O Agent SDK oferece mais controle, sim. Mas controle significa propriedade. Como ksred observa sobre o SDK, sessões agentic que executam trabalho substancial podem ficar caras rapidamente, e a recuperação de falhas é inteiramente seu design no SDK. Managed Agents troca parte desse controle por sessões duráveis e infraestrutura que você não opera. Nenhum dos dois está errado. A escolha depende do que seu time realmente pode manter.

Saída de ant apply --dry-run revisada por uma segunda pessoa antes de qualquer aplicação em produção

Managed Agents funciona com qualquer modelo Claude, ou está restrito a versões específicas?

A documentação oficial não lista restrições de modelo específicas dentro de Managed Agents no momento da redação. Dado o status beta, a disponibilidade de modelos pode mudar. Verifique a página de visão geral diretamente antes de se comprometer com uma versão de modelo específica em uma definição de agente em produção.

Posso executar a mesma definição de agente localmente com o SDK para testar antes de implantar em Managed Agents?

Não diretamente. O SDK executa o loop em seu próprio processo contra seu ambiente local; Managed Agents o executa na sandbox da Anthropic. Você pode prototipar o comportamento do agente com o SDK, mas o contexto de execução é suficientemente diferente que você deve testar a implantação real de Managed Agents em um ambiente de staging antes de promover para produção.

Como Managed Agents lida com autenticação para servidores MCP que precisam de credenciais?

A documentação oficial descreve ferramentas personalizadas como conectando através de servidores MCP, com Claude acionando a ferramenta e seu serviço retornando resultados. O tratamento de credenciais para esses servidores MCP é sua responsabilidade no nível do servidor. Managed Agents não injeta credenciais em chamadas MCP em seu nome de acordo com a documentação atual.

Existe uma forma de limitar gastos por sessão em Managed Agents da mesma forma que o parâmetro max_budget_usd do SDK funciona?

O parâmetro max_budget_usd do SDK em query() é um controle de nível SDK que não se traduz diretamente para a API REST de Managed Agents. Controles de orçamento dentro de Managed Agents não estão documentados com a mesma granularidade na beta atual. Alertas de gastos no nível da conta são o melhor backstop agora.

O que acontece com uma sessão em execução se a região ou sandbox sofrer uma interrupção?

Logs de sessão durável são um recurso de design central de Managed Agents, mas as especificidades da recuperação de sessão através de uma interrupção de infraestrutura não são detalhadas na documentação beta atual. Dado o designo beta, trate a garantia de durabilidade como best-effort até que Anthropic publique um SLA para o serviço.

O resumo honesto: Managed Agents é um serviço genuinamente útil que elimina uma grande classe de trabalho de infraestrutura. O fluxo de trabalho ant apply é direto uma vez que você entende as ressalvas do dry-run e o requisito de serialização. Mas é beta, a semântica de falha parcial requer cuidado, e não é a resposta certa se você precisa de acesso ao sistema de arquivos local ou já tem infraestrutura de agente com a qual está satisfeito. Comece com a tabela de decisão, escolha com base no que seu time realmente quer possuir, e trate o lockfile tão seriamente quanto você trataria qualquer outro arquivo de estado.