Claude Managed Agents vs Agent SDK (2026): Qual Escolher

Você decidiu lançar um agente de IA em produção com Claude. A decisão prática é: usar Claude Managed Agents, deixando a Anthropic hospedar o loop, a sandbox e o estado da sessão, ou usar o Claude Agent SDK, mantendo o loop dentro da sua própria aplicação. A escolha muda arquitetura, custo, residência de dados, observabilidade e operação. Este guia compara as duas opções usando cenários reais: reembolso de pagamentos, triagem de tickets e operações internas.

Experimente o Apidog hoje

TL;DR

Use Claude Managed Agents quando você quiser um runtime hospedado para agentes longos ou assíncronos, com sandbox e estado de sessão gerenciados pela Anthropic.

Use Claude Agent SDK quando você precisar executar o agente dentro da sua própria infraestrutura, com controle total sobre ferramentas, permissões, dados, hooks e custo operacional.

Ambos usam modelos Claude e podem se integrar a ferramentas externas via MCP.

Introdução

Em 2026, construir um agente de IA em produção não é mais apenas colocar um while em volta de uma chamada de chat completion. O agente precisa chamar APIs, manter contexto, lidar com erros, executar ferramentas, registrar auditoria e operar com segurança.

A Anthropic oferece duas formas principais de executar esse loop:

• Claude Managed Agents: uma API REST hospedada. A Anthropic executa o loop do agente, a sandbox e o estado da sessão.
• Claude Agent SDK: uma biblioteca Python ou TypeScript. O loop roda dentro do seu processo e da sua infraestrutura.

A diferença parece pequena em uma demo, mas é grande em produção. Ela define:

• onde os dados ficam;
• quem opera a sandbox;
• como você audita ações;
• como ferramentas são executadas;
• como você prevê custo;
• quem recebe alerta quando uma API falha.

Na prática, agentes de produção chamam APIs: pagamentos, tickets, CRM, inventário, logs, serviços internos e servidores MCP. Por isso, a confiabilidade do agente depende diretamente da confiabilidade dessas APIs.

Antes de escolher o modelo de hospedagem, você precisa testar os endpoints que o agente vai chamar. Uma plataforma como o Apidog ajuda a simular dependências, validar contratos de API e testar servidores MCP da mesma forma que o agente fará. Para uma visão mais focada no runtime hospedado, veja também o guia do Claude Managed Agents.

O que são Claude Managed Agents

Claude Managed Agents é uma opção hospedada em que a Anthropic executa o agente em uma infraestrutura gerenciada. Em vez de você implementar o loop, a sandbox, o armazenamento de sessão e parte da execução operacional, você configura o agente e envia eventos.

Ele foi lançado em beta público em abril de 2026 e requer o cabeçalho beta:

anthropic-beta: managed-agents-2026-04-01

O SDK pode configurar esse cabeçalho para você.

Conceitos principais

O produto gira em torno de quatro entidades:

• Agente: modelo, prompt do sistema, ferramentas, servidores MCP e habilidades.
• Ambiente: template de contêiner com pacotes pré-instalados, como Python, Node.js e Go, além de regras de rede.
• Sessão: execução do agente dentro de um ambiente, com histórico, sistema de arquivos persistente e estado.
• Eventos: mensagens entre sua aplicação e o agente, transmitidas via SSE e persistidas no servidor.

O fluxo de uso é:

1. criar um agente;
2. configurar um ambiente;
3. iniciar uma sessão;
4. enviar eventos do usuário;
5. transmitir respostas e status;
6. recuperar o histórico completo para auditoria e debug.

Ferramentas disponíveis

Managed Agents oferece ferramentas integradas como:

• Bash;
• leitura, escrita e edição de arquivos;
• glob e grep;
• busca e recuperação web;
• conexões com servidores MCP.

Para ferramentas personalizadas, há uma diferença importante: o Claude decide chamar a ferramenta, mas sua aplicação executa a ação e retorna o resultado pelo fluxo de eventos. Ou seja, o loop e a sandbox são hospedados, mas a ação sensível ainda pode acontecer no seu ambiente.

Esse modelo é mais indicado para:

• tarefas assíncronas;
• execuções de minutos a horas;
• agentes que fazem muitas chamadas de ferramentas;
• equipes que não querem operar sandbox e armazenamento de sessão;
• fluxos em que o estado pode residir na infraestrutura da Anthropic ou na opção AWS disponível.

Alguns recursos, como resultados e multi-agente, são disponibilizados como prévia de pesquisa mediante solicitação. Portanto, verifique a documentação antes de projetar em cima deles.

Para entender o padrão arquitetural por trás disso, veja também a análise sobre arquitetura de IA com agentes.

O que é o Claude Agent SDK

Claude Agent SDK é uma biblioteca Python ou TypeScript que expõe o loop de agente, o gerenciamento de contexto e ferramentas integradas semelhantes às usadas pelo Claude Code.

Antes, ele era chamado de Claude Code SDK. A renomeação indica um escopo maior do que tarefas de codificação.

Instalação típica:

pip install claude-agent-sdk

ou:

npm install @anthropic-ai/claude-agent-sdk

A diferença em relação ao Client SDK comum é que você não precisa escrever manualmente um loop como:

while response.stop_reason == "tool_use":
    # executar ferramenta
    # enviar resultado de volta ao modelo

O Agent SDK já fornece essa mecânica.

O que o SDK entrega

Com o Agent SDK, você controla o agente dentro do seu processo. Isso inclui:

• Ferramentas integradas: Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, Monitor e AskUserQuestion.
• Hooks: callbacks como PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd e UserPromptSubmit.
• Subagentes: agentes especializados para subtarefas, com rastreabilidade via parent_tool_use_id.
• MCP: integração com bancos de dados, navegadores, APIs e ferramentas externas.
• Permissões: pré-aprovar ferramentas seguras, bloquear ações perigosas ou exigir aprovação humana.
• Sessões: capturar IDs, retomar contexto ou criar forks. O estado fica em JSONL no seu sistema de arquivos.

Exemplo conceitual de controle com hook:

def pre_tool_use(tool_name, tool_input):
    if tool_name == "refund_payment" and tool_input["amount"] > 500:
        raise PermissionError("Reembolso acima do limite exige aprovação humana")

    log_audit_event(tool_name, tool_input)

Esse tipo de política é uma das razões para escolher o SDK quando o agente toca sistemas sensíveis.

O SDK também lê configurações do Claude Code no sistema de arquivos, como:

• .claude/skills/;
• comandos de barra;
• CLAUDE.md;
• plugins.

A autenticação pode usar a API direta da Anthropic ou provedores como Amazon Bedrock, Claude Platform na AWS, Google Vertex AI e Azure AI Foundry. Isso é útil quando você precisa manter a inferência dentro de um contrato de nuvem existente.

Para começar com um loop funcional, veja o guia sobre configurar o Claude Agent SDK com um plano Claude e o passo a passo para construir seu próprio Claude Code.

Atenção à cobrança

A partir de 15 de junho de 2026, o uso do Agent SDK e claude -p em planos de assinatura será deduzido de um crédito mensal separado do Agent SDK, distinto dos limites de uso interativo.

Se sua previsão de custo assumia que chamadas do SDK compartilhavam o mesmo pool do uso interativo do Claude, revise o modelo. Sempre confirme os termos atuais diretamente com a Anthropic.

Managed Agents vs Agent SDK

Confirme valores atuais na página de preços da Anthropic e na documentação do Managed Agents antes de fechar orçamento.

Dimensão	Claude Managed Agents	Claude Agent SDK
Onde o loop roda	Infraestrutura gerenciada pela Anthropic	Seu processo e sua infraestrutura
Interface	API REST + eventos SSE	Biblioteca Python ou TypeScript
Controle do loop	Configurado por eventos	Controle direto com hooks, permissões e lógica em processo
Modelo de custo	Tokens Claude + taxa de runtime por hora de sessão ativa	Tokens Claude + sua computação e operação
Carga operacional	Menor: sandbox, sessão e escala são gerenciadas	Maior: você opera runtime, sandbox, logs e escala
Observabilidade	Log de eventos hospedado e recuperável	Hooks, logs e tracing que você instrumentar
Latência	Salto de rede para runtime hospedado	Loop local ao seu serviço e às suas dependências
Residência de dados	Sandbox e estado na infraestrutura da Anthropic ou opção AWS	Arquivos, ferramentas e estado ficam na sua infraestrutura
Ferramentas personalizadas	Claude solicita; sua aplicação executa e retorna resultado	Funções Python/TypeScript em processo
Melhor uso	Agentes assíncronos, longos e com baixa carga operacional	Agentes próximos a dados privados, VPCs e fluxos regulados

Como decidir

Escolha Claude Managed Agents se

Use Managed Agents quando:

• o agente roda por minutos ou horas;
• o trabalho é assíncrono;
• você não quer operar sandbox, workers e armazenamento de sessão;
• sua equipe é pequena e operação é o gargalo;
• você quer histórico de eventos hospedado;
• os dados podem residir no ambiente da Anthropic ou na opção AWS;
• você aceita usar uma funcionalidade em beta e validar disponibilidade de recursos.

Exemplo de arquitetura:

App
 └── envia eventos
      └── Claude Managed Agents
           ├── loop do agente
           ├── sandbox
           ├── estado da sessão
           └── chamadas MCP / ferramentas

Escolha Claude Agent SDK se

Use o SDK quando:

• o agente precisa rodar dentro da sua VPC;
• o agente acessa banco privado ou serviço interno;
• o estado da sessão não pode sair da sua infraestrutura;
• você precisa de hooks de auditoria e política;
• ferramentas sensíveis exigem aprovação humana;
• você quer controlar permissões no nível da chamada;
• você está prototipando localmente.

Exemplo de arquitetura:

Seu serviço
 ├── Claude Agent SDK
 ├── hooks de auditoria
 ├── permissões
 ├── servidores MCP internos
 └── APIs privadas

Testando as APIs que seus agentes chamam

A decisão de hospedagem não elimina o principal risco: APIs instáveis.

Um agente de reembolso pode raciocinar corretamente, mas ainda falhar se a API de pagamentos retornar um schema diferente, der timeout ou processar uma operação de forma ambígua.

Teste três camadas antes de produção.

1. Contratos das APIs

Toda ferramenta chamada pelo agente deve ter um contrato claro:

• request esperada;
• response esperada;
• erros previstos;
• timeouts;
• idempotência;
• campos obrigatórios;
• limites.

Com o Apidog, você pode simular APIs de pagamentos, tickets ou logs e criar testes de contrato contra os schemas.

Exemplo de contrato para uma ferramenta de reembolso:

{
  "transaction_id": "txn_123",
  "amount": 49.90,
  "currency": "BRL",
  "reason": "duplicate_charge"
}

Você deve testar cenários como:

200 OK        -> reembolso emitido
400 BadRequest -> payload inválido
409 Conflict -> reembolso já processado
504 Timeout   -> status desconhecido; verificar antes de repetir

O caso 504 é especialmente importante. Um agente não deve simplesmente repetir uma chamada de reembolso sem verificar se a operação anterior foi concluída.

Veja o guia sobre como testar agentes de IA que chamam APIs para uma abordagem mais estruturada.

2. Servidores MCP

Managed Agents e Agent SDK podem usar MCP. Um servidor MCP também precisa ser testado como qualquer serviço.

Teste:

• ferramentas expostas;
• schemas de entrada;
• schemas de saída;
• mensagens de erro;
• timeouts;
• permissões;
• comportamento em entradas inválidas.

Um erro comum é retornar prosa onde o agente esperava dados estruturados. Isso degrada o comportamento do agente de forma silenciosa.

O guia de teste de servidor MCP com Apidog mostra como enumerar ferramentas expostas e exercitar cada uma delas.

O Apidog também inclui um agente de IA e um depurador A2A para observar tráfego real de requisição e resposta gerado por agentes.

3. Comportamento real do agente

Agentes não usam APIs como humanos. Eles podem gerar padrões como:

• várias tentativas em sequência;
• leitura parcial de dados;
• chamadas repetidas ao mesmo endpoint;
• loops de consulta;
• retries sem backoff adequado;
• chamadas redundantes enquanto “raciocinam”.

Reproduza esse tráfego contra mocks antes de conectar APIs reais.

Fluxo recomendado:

1. Defina contratos das APIs
2. Crie mocks no Apidog
3. Conecte o agente aos mocks
4. Execute tickets ou tarefas históricas
5. Capture as chamadas reais
6. Ajuste permissões, prompts, ferramentas e retries
7. Só então conecte produção

A hospedagem muda a forma de observar o loop:

• com Managed Agents, você depende mais do log de eventos hospedado e dos testes de API;
• com Agent SDK, você pode instrumentar hooks, mas ainda precisa testar as dependências.

De qualquer forma, baixe o Apidog e coloque APIs e MCPs sob teste antes de expor o agente a clientes reais.

Casos de uso reais

1. Agente de reembolso de pagamentos

Cenário: uma fintech quer automatizar solicitações de reembolso. O agente deve:

1. ler o ticket;
2. consultar a transação;
3. validar política de reembolso;
4. chamar a API de pagamentos;
5. registrar a decisão;
6. responder no ticket.

Esse agente mexe com dinheiro. Portanto, precisa de:

• residência de dados controlada;
• auditoria;
• autorização humana para valores altos;
• idempotência;
• testes de contrato;
• logs detalhados.

Melhor escolha: Claude Agent SDK.

Motivos:

• roda dentro da VPC;
• acessa serviços privados;
• mantém estado da sessão internamente;
• permite hooks como PreToolUse;
• facilita bloqueio ou aprovação de ações sensíveis.

Exemplo de regra:

def validate_refund(tool_input):
    if tool_input["amount"] > 1000:
        return {
            "status": "requires_human_approval",
            "reason": "Valor acima do limite automático"
        }

    return {"status": "approved"}

Antes do lançamento, a equipe deve:

• simular pagamentos e contabilidade no Apidog;
• criar testes de contrato;
• reproduzir tickets históricos;
• validar comportamento em timeout;
• garantir que retries não dupliquem reembolsos.

Esse é um caso em que controle e governança pesam mais que conveniência operacional.

2. Agente assíncrono de triagem de tickets

Cenário: uma empresa SaaS recebe milhares de tickets por dia. O agente deve:

1. classificar o ticket;
2. buscar logs relacionados;
3. sugerir resposta;
4. resolver ou escalar;
5. registrar o histórico.

Os dados são de baixa sensibilidade, e cada tarefa leva alguns minutos.

Melhor escolha: Claude Managed Agents.

Motivos:

• execução assíncrona;
• muitas sessões independentes;
• equipe pequena;
• menor carga operacional;
• log de eventos hospedado por ticket;
• menos necessidade de manter workers próprios.

Mesmo assim, as dependências ainda precisam ser testadas:

• API de tickets;
• servidor MCP do sistema de suporte;
• API de logs;
• schemas de resposta;
• mudanças de contrato.

A hospedagem é gerenciada, mas a correção das APIs continua sendo sua responsabilidade.

3. Agente interno de operações de dados atrás do firewall

Cenário: uma equipe de plataforma quer um agente para responder solicitações como:

“Reprocessar os dados ETL que falharam ontem.”

O agente precisa:

• consultar APIs internas;
• executar scripts;
• verificar status;
• registrar auditoria;
• operar atrás do firewall.

Melhor escolha: Claude Agent SDK.

Motivos:

• APIs internas não estão na internet pública;
• dados são sensíveis;
• o estado da sessão não pode residir em sandbox externa;
• comandos precisam ser auditados;
• hooks podem alimentar o pipeline de auditoria existente.

Nesse caso, “rodar no seu processo” não é preferência arquitetural. É requisito.

Para entender por que agentes estão virando consumidores diretos de APIs, veja o artigo sobre agentes de IA como os novos consumidores de API.

Caminho prático de adoção

Um caminho comum é:

Protótipo local -> testes com mocks -> piloto controlado -> produção

Na prática:

1. Prototipe com Agent SDK

   • iteração local rápida;
   • controle do filesystem;
   • hooks fáceis de inspecionar.

2. Modele ferramentas e MCPs

   • defina schemas;
   • crie mocks;
   • escreva testes de contrato.

3. Execute tráfego histórico

   • tickets antigos;
   • solicitações reais anonimizadas;
   • casos de erro conhecidos.

4. Decida o runtime

   • mantenha SDK se dados, VPC ou controle forem críticos;
   • migre para Managed Agents se operação for o maior custo.

5. Planeje a migração

   • biblioteca e REST+SSE têm interfaces diferentes;
   • ferramentas personalizadas funcionam de forma diferente;
   • estado de sessão muda de local;
   • observabilidade muda.

Essa migração não é uma flag de configuração. Trate como projeto.

Se você também estiver avaliando modelos e agentes de codificação, veja a comparação Claude vs Codex para 2026.

Checklist de decisão

Use esta lista antes de escolher.

Dados e compliance

• O estado da sessão pode sair da sua infraestrutura?
• A sandbox pode ser hospedada por terceiros?
• Há exigência de VPC?
• Há dados regulados?
• Logs de eventos podem ser armazenados fora do seu ambiente?

Se a maioria das respostas aponta para restrição, escolha Agent SDK.

Operação

• Sua equipe quer operar workers?
• Você tem observabilidade pronta?
• Você consegue manter sandbox segura?
• Você quer escalar sessões longas?
• Você tem plantão para falhas de runtime?

Se operação for o gargalo, escolha Managed Agents.

Ferramentas

• As ferramentas são internas?
• Precisam de aprovação humana?
• Precisam de hooks de política?
• Precisam de auditoria detalhada?
• Chamam sistemas sensíveis?

Se sim, o Agent SDK tende a ser melhor.

Perfil da tarefa

• Tarefas longas e assíncronas: Managed Agents.
• Tarefas próximas a dados privados: Agent SDK.
• Protótipos locais: Agent SDK.
• Workloads com pouca sensibilidade e alto volume assíncrono: Managed Agents.

Conclusão

A decisão entre Claude Managed Agents e Claude Agent SDK é menos sobre API e mais sobre operação, governança e residência de dados.

Resumo prático:

• Managed Agents hospeda o loop e a sandbox.
• Agent SDK executa o loop no seu processo.
• Managed Agents reduz carga operacional.
• Agent SDK aumenta controle e isolamento.
• Managed Agents adiciona taxa de runtime por sessão ativa.
• Agent SDK transfere custo para sua infraestrutura e operação.
• Dados regulados ou VPC geralmente apontam para SDK.
• Workloads assíncronos e menos sensíveis geralmente apontam para Managed Agents.
• APIs e MCPs precisam ser testados em ambos os casos.

Antes de conectar um agente a qualquer fluxo que toque clientes, coloque suas dependências sob teste. Baixe o Apidog para simular endpoints, executar testes de contrato e depurar o tráfego real do agente.

FAQ

Qual é a principal diferença entre Claude Managed Agents e Claude Agent SDK?

Managed Agents é uma API REST hospedada em que a Anthropic executa o loop do agente, a sandbox e o estado da sessão. Agent SDK é uma biblioteca Python ou TypeScript que executa o loop dentro do seu processo e da sua infraestrutura.

O Claude Agent SDK é o mesmo que o antigo Claude Code SDK?

Sim. O Claude Code SDK foi renomeado para Claude Agent SDK para refletir um escopo mais amplo que tarefas de codificação. Ele expõe o loop, ferramentas integradas e gerenciamento de contexto usados pelo Claude Code.

Qual opção é mais barata?

Depende do workload. Managed Agents cobra tokens Claude mais uma taxa de runtime por hora de sessão ativa. O SDK não tem essa taxa de runtime da Anthropic, mas você paga pela infraestrutura, escala, observabilidade e operação. Confirme sempre os preços atuais na fonte.

Posso usar servidores MCP com ambos?

Sim. Ambos podem usar MCP para conectar ferramentas externas. Por isso, teste servidores MCP antes de conectá-los ao agente. O guia de teste de servidor MCP com Apidog mostra como exercitar ferramentas MCP como o agente faria.

Como manter dados do cliente fora da infraestrutura da Anthropic?

Use o Agent SDK e execute o loop dentro do seu ambiente. Com o SDK, execução de ferramentas e estado da sessão permanecem na sua infraestrutura. Com Managed Agents, sandbox e log de eventos residem no ambiente da Anthropic ou na opção AWS disponível, com ressalvas.

Claude Managed Agents está pronto para produção?

Ele foi lançado em beta público em abril de 2026 e requer o cabeçalho beta managed-agents-2026-04-01. A funcionalidade principal de sessão está disponível para contas de API, enquanto alguns recursos, como resultados e multi-agente, exigem solicitação separada de prévia de pesquisa. Verifique a documentação atual antes de adotar.

Como testar um agente antes de acessar APIs reais?

Simule todas as APIs e servidores MCP, escreva testes de contrato e execute tráfego realista contra mocks. O Apidog cobre esses fluxos, incluindo depuração de tráfego de agente e A2A. Veja o guia sobre como testar agentes de IA que chamam APIs.

Posso começar com um e mudar para o outro depois?

Sim, mas não é uma mudança simples de configuração. As interfaces são diferentes, a execução de ferramentas personalizadas muda e o estado da sessão passa de local para hospedado, ou vice-versa. Um caminho comum é prototipar com Agent SDK e migrar para Managed Agents se a economia operacional justificar.