Claude Managed Agents vs Claude Agent SDK

Na semana passada eu tinha três abas abertas: a documentação do Managed Agents, o quickstart do Agent SDK e a referência da Messages API. Eu estava tentando descobrir qual caminho usar para um pipeline assíncrono de processamento de documentos. Quarenta minutos depois, percebi que a confusão não era sobre funcionalidades. Era sobre quem controla o runtime.

Esse é o cerne dessa decisão. Não qual é “melhor.” Qual fronteira de infraestrutura faz sentido para o que você está construindo agora. Este artigo documenta como os dois caminhos se comparam — e por que existe uma terceira opção que a maioria dos artigos comparativos ignora.

Dois Caminhos para Agentes com Claude

Agent SDK: você controla o loop, você gerencia o runtime

O Claude Agent SDK — renomeado a partir do Claude Code SDK no início deste ano — oferece as mesmas ferramentas, loop de agente e gerenciamento de contexto que alimentam o Claude Code, empacotados como uma biblioteca Python ou TypeScript. Você o instala, executa na sua infraestrutura e cuida do escalonamento, sandboxing e orquestração por conta própria.

O SDK inclui automaticamente o Claude Code CLI. Seu agente tem acesso a operações de arquivo, comandos bash, navegação web, execução de código — o conjunto completo de ferramentas do Claude Code — logo de cara. Você define quais ferramentas são permitidas, configura modos de permissão e implementa ferramentas personalizadas como servidores MCP em processo.

O que você obtém: controle total sobre o ambiente de execução. O que você também obtém: a responsabilidade de manter esse ambiente funcionando, seguro e observável.

Managed Agents: Anthropic controla o harness, você define a tarefa

O Claude Managed Agents, lançado em beta público em 8 de abril de 2026, inverte o modelo de propriedade. Você especifica o agente — modelo, system prompt, ferramentas, servidores MCP, guardrails — e a Anthropic o executa. O harness cuida da execução de ferramentas, sandboxing, persistência de sessão, compactação de contexto, cache de prompts e recuperação de falhas.

A equipe de engenharia da Anthropic o descreve como um “meta-harness” — projetado para acomodar futuros harnesses conforme os modelos evoluem em vez de codificar suposições fixas sobre o que o Claude pode ou não pode fazer. Se um container falha, a sessão sobrevive. Um novo container retoma a partir do log de sessão.

Você configura, a Anthropic opera.

Nenhum é universalmente melhor

A sobreposição de capacidades é alta. Ambos dão ao Claude acesso à execução de código, manipulação de arquivos, bash, navegação web e integrações MCP. A diferença é operacional: quem provisiona o ambiente, quem lida com falhas, quem escala os containers. Esta é uma decisão de infraestrutura, não de funcionalidades.

Comparação Central

Vale notar sobre cobrança: o Agent SDK não introduz uma taxa de runtime por sessão. Mas chamá-lo de “mais barato” sem qualificação é enganoso. Seu runtime auto-hospedado tem custos reais — servidores, orquestração de containers, monitoramento, resposta a incidentes, as horas de engenharia para manter tudo isso. As estruturas de custo são diferentes, não simplesmente ordenadas.

Quando Escolher Managed Agents

Tarefas de longa duração ou assíncronas onde a persistência de sessão importa

Se seu agente roda por 30 minutos a várias horas — processando documentos, fazendo pesquisas, executando fluxos de trabalho multi-etapa — você precisa de estado de sessão que sobreviva a desconexões e falhas de container. O Managed Agents armazena o histórico completo de eventos no servidor e o torna acessível via API. Construir durabilidade equivalente por conta própria é possível. Mas também são várias semanas de engenharia que não fazem parte do seu produto principal.

Equipes sem capacidade de infraestrutura para construir sandboxes seguros

Sandboxing de nível produção — isolamento, gerenciamento de credenciais, permissões com escopo, rastreamento de execução — é genuinamente difícil. A maioria das equipes subestima isso. Se sua equipe não tem capacidade de DevOps para construir e manter um ambiente seguro de execução de agentes, o Managed Agents remove toda essa superfície do seu roadmap.

Prototipagem rápida para produção: dias em vez de meses

O destaque da Anthropic é “chegue à produção 10x mais rápido.” Não verifiquei esse número em cenários suficientes para endossá-lo. Mas a direção é precisa: o gap entre “o agente funciona em testes locais” e “o agente roda de forma confiável em produção” é grande, e o Managed Agents o reduz. A Rakuten supostamente implantou agentes especialistas em menos de uma semana cada.

Quando compactação e cache integrados importam mais do que controle personalizado

O Managed Agents lida com cache de prompts e compactação de contexto automaticamente. Se você construiu seu próprio gerenciamento de contexto para agentes de longa duração, sabe quanto tentativa e erro isso envolve. A abordagem integrada não será ótima para todas as cargas de trabalho. Para a maioria, é suficientemente boa — e está disponível desde o primeiro dia.

Quando Escolher o Agent SDK

Lógica de orquestração personalizada que o Managed Agents não expõe

O SDK oferece hooks, ferramentas personalizadas como servidores MCP em processo, callbacks de permissão granulares e controle total sobre o loop do agente. Se seu agente precisa de estratégias de retry personalizadas, roteamento condicional de ferramentas ou modificação dinâmica de prompts durante a sessão — lógica que a superfície de configuração do Managed Agents não expõe — você precisa do SDK.

Integrações de ferramentas especializadas ou ambientes de execução personalizados

Se seu agente precisa rodar dentro de um ambiente específico — acesso a uma GPU, um driver de banco de dados específico, uma biblioteca proprietária — o SDK permite que você controle o ambiente de execução completamente. O Managed Agents oferece um container cloud com pacotes pré-instalados. Isso é suficiente para a maioria dos casos. Não para todos.

Requisitos de nuvem privada ou on-premise

O Managed Agents roda exclusivamente na infraestrutura da Anthropic. Não há opção on-premise, não há implantação na sua própria nuvem. Para organizações com requisitos estritos de soberania de dados ou restrições regulatórias que proíbem o envio de dados para infraestrutura de terceiros, o SDK é o único caminho. Esta é uma restrição rígida, não uma preferência.

Estrutura de custo em escala

O $0,08/hora de sessão é insignificante para a maioria das cargas de trabalho — um agente 24/7 custa aproximadamente $58/mês em runtime antes dos tokens. Mas para grandes frotas de agentes concorrentes de longa duração, as taxas de sessão se acumulam. Uma frota de 500 agentes rodando simultaneamente gera $40/hora apenas em overhead de sessão.

O Agent SDK não tem essa sobretaxa por sessão. Seus custos são tokens mais o que sua infraestrutura custa. Em alto volume, possuir o runtime pode ser mais barato em termos marginais — mas somente se você já absorveu o custo fixo de construí-lo e mantê-lo.

A Terceira Opção: Messages API

Quando nem o SDK nem o Managed Agents são necessários

Esta é a opção que a maioria dos artigos comparativos ignora, e é a resposta certa com mais frequência do que as pessoas pensam.

A Messages API oferece acesso direto ao modelo. Você envia um prompt, recebe uma resposta. Sem harness, sem loop de agente, sem runtime gerenciado. Você constrói tudo por conta própria — incluindo o loop de execução de ferramentas, se precisar.

Padrões simples de uso de ferramentas que não requerem um framework completo de agentes

Se seu caso de uso é: chamar o Claude, opcionalmente deixá-lo usar uma ou duas ferramentas, retornar um resultado — você não precisa de um framework de agentes. A Messages API com uso de ferramentas resolve isso de forma limpa. Adicionar o Agent SDK ou o Managed Agents introduz complexidade que não se paga em padrões simples de requisição-resposta.

Os SDKs Python e TypeScript da Anthropic suportam uso de ferramentas nativamente. Você implementa o loop de ferramentas por conta própria — um loop while que verifica stop_reason, executa ferramentas, envia resultados de volta. Para muitas cargas de trabalho em produção, isso é tudo que você precisa.

Já vi equipes recorrem a frameworks de agentes quando um loop de ferramentas de 20 linhas teria resolvido o problema. Verifique se sua tarefa realmente requer autonomia ou persistência de sessão antes de escolher uma abstração mais pesada.

Considerações de Migração

Começando no Managed Agents, migrando para o SDK: o que muda

A lógica do agente — system prompt, definições de ferramentas, estrutura de tarefas — transfere diretamente. O que não transfere: persistência de sessão, sandboxing, gerenciamento de contexto e recuperação de falhas. Você precisará construir tudo isso.

Mover do Managed Agents para o SDK significa passar de “Anthropic opera” para “você opera.” A capacidade é equivalente. O ônus operacional muda completamente para sua equipe.

Começando no SDK, migrando para o Managed Agents: o que muda

Mais fácil em alguns aspectos, mais difícil em outros. A lógica central do seu agente é portável. Ferramentas personalizadas implementadas como servidores MCP em processo podem precisar ser re-expostas como servidores MCP remotos. Hooks personalizados e callbacks de permissão precisam mapear para o modelo de configuração do Managed Agents.

O ganho: você para de manter o runtime. O custo: você perde controle granular sobre o ambiente de execução. Se esse tradeoff funciona depende de quanto da sua infraestrutura personalizada era realmente necessária versus herdada de decisões iniciais de prototipagem.

Não há guia oficial de migração entre os dois até abril de 2026. Planeje para testes de integração, não apenas portabilidade de código.

FAQ

Posso usar ambos no mesmo produto?

Sim. O SDK e o Managed Agents atendem a diferentes necessidades operacionais. Um padrão comum: Agent SDK para interações voltadas ao usuário e sensíveis à latência onde você precisa de controle total; Managed Agents para tarefas em segundo plano e assíncronas onde a persistência de sessão e a operação sem intervenção importam mais. Ambos compartilham os mesmos modelos Claude subjacentes e a estrutura de preços para custos de tokens.

O Managed Agents me prende à infraestrutura da Anthropic?

Sim. O runtime é construído especificamente para o Claude. Ele não rodará GPT, Gemini ou modelos de código aberto. A lógica do seu agente — prompts, definições de ferramentas, estrutura de tarefas — é portável. O runtime e o formato de sessão não são. O SDK oferece mais flexibilidade para abstrair a camada de modelo, embora também seja específico para o Claude.

Qual lida melhor com erros e retries?

O Managed Agents tem recuperação de falhas integrada — o log de sessão persiste, um novo container retoma de onde o anterior falhou. Com o SDK, você constrói seu próprio tratamento de erros. Se você já fez isso antes e tem bons padrões, o tratamento de erros do SDK pode ser ajustado com mais precisão para suas necessidades. Se não, os padrões do Managed Agents são um forte ponto de partida.

Posso migrar um agente SDK existente para o Managed Agents?

A lógica central do agente é transferível. System prompt, definições de ferramentas e estrutura de tarefas são compatíveis. O que requer retrabalho: hooks personalizados, servidores MCP em processo (podem precisar de equivalentes remotos), lógica de permissão personalizada e qualquer coisa que dependa do seu ambiente de execução específico. Ainda não existe ferramental oficial de migração.

Qual é mais econômico em alto volume?

Depende do que você considera. O Managed Agents adiciona $0,08/hora de sessão além dos tokens. O SDK não adiciona nenhuma sobretaxa por sessão — mas seu runtime auto-hospedado tem sua própria linha de custo: servidores, orquestração, monitoramento, manutenção de engenharia. Em volume baixo a moderado, o Managed Agents é tipicamente mais barato no custo total de propriedade. Em volume muito alto com muitas sessões longas concorrentes, a matemática pode inverter — mas somente se você já investiu na infraestrutura.

Essa é a comparação. A árvore de decisão: precisa de controle de infraestrutura ou não pode enviar dados para fora das suas instalações → SDK. Quer pular a infraestrutura → Managed Agents. Não precisa de um loop de agente → Messages API.

Execute um piloto em ambos se estiver em dúvida. O custo de troca é menor na fase de protótipo do que depois de comprometer-se com uma arquitetura de implantação.

Continuando na próxima semana — ainda testando padrões multi-agente no Managed Agents.

Posts anteriores: