API da Anthropic direto ou Claude Agent SDK: qual usar no seu projeto?

Fala aí, beleza? A escolha aqui não é entre duas APIs

é entre escrever o loop do agente você mesmo ou receber ele pronto

Você já entendeu o que a API da Anthropic é e o que ela faz, já sacou a diferença entre o chat e a API e agora bateu na decisão que realmente muda o seu código: a camada de integração do projeto

De um lado, a requisição HTTP crua, onde você monta tudo

Do outro, o Claude Agent SDK, que já vem com o miolo do agente montado

Bora destrinchar os dois e ver qual tipo de aplicação justifica cada um 🙂

O que é chamar a API da Anthropic direto

Na camada crua, você faz um POST na Messages API e pronto

São três cabeçalhos obrigatórios e um corpo com model, max_tokens e messages

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "<model-id>",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "Resuma este texto em 3 linhas" }
    ]
  }'

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

E o que é esse anthropic-version? Muita gente confunde com versão do modelo, e não é isso

O anthropic-version: 2023-06-01 é obrigatório em toda requisição e controla o comportamento da API HTTP

Quem escolhe o modelo é o campo model, lá no corpo

Tome cuidado com isso, porque é o tipo de detalhe que te faz perder uma tarde caçando erro no lugar errado

Quando você quer um recurso em beta, entra mais um cabeçalho: anthropic-beta, mandado junto com x-api-key, anthropic-version e content-type

E os SDKs cliente, entram onde?

A Anthropic mantém SDKs cliente de uso geral pra Messages API em Python, TypeScript, C#, Go, Java, PHP e Ruby

pip install anthropic
npm install @anthropic-ai/sdk

Se você conhece qualquer wrapper de API REST, é exatamente a mesma ideia: conveniência em cima da MESMA chamada

Eles montam o cabeçalho, tipam a resposta e te poupam do curl na unha

Mas o loop do agente continua sendo seu problema: se o modelo pedir uma ferramenta, quem executa e devolve o resultado é o seu código

O que o Claude Agent SDK entrega além da chamada

Aqui a conversa muda de nível

Ele entrega as mesmas ferramentas, o mesmo agent loop e o mesmo gerenciamento de contexto que rodam por trás do Claude Code, programáveis em Python e TypeScript

Ou seja: em vez de reimplementar o que o Claude Code já faz, tu importa isso como biblioteca

A instalação é next, next e finish:

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

pip install claude-agent-sdk

A autenticação é por variável de ambiente, com a chave de API que você pega no Console:

export ANTHROPIC_API_KEY=your-api-key

E aí vem a parte que economiza semana de trabalho: o SDK já vem com ferramentas embutidas de leitura de arquivos, execução de comandos e edição de código

A execução de ferramentas já vem implementada, então o agente começa a trabalhar sem você escrever a ponte entre o modelo e o sistema de arquivos

query(): o coração do SDK em TypeScript

No SDK em TypeScript, a função principal é query()

Ela recebe { prompt, options } e devolve um Query, que é um async generator emitindo mensagens conforme elas chegam

import { query } from "@anthropic-ai/claude-agent-sdk"

const q = query({
  prompt: "Leia os arquivos do projeto e liste os TODOs abertos",
  options: { includePartialMessages: true }
})

for await (const message of q) {
  console.log(message)
}

O objeto Query ainda expõe métodos de controle da execução, tipo interrupt(), setPermissionMode(), setModel() e setMaxThinkingTokens()

Isso é controle em tempo de execução, coisa que na API crua você teria que inventar do zero

Quer token parcial pingando na tela em tempo real? Precisa ligar includePartialMessages: true, e aí o SDK passa a emitir mensagens StreamEvent além de AssistantMessage e ResultMessage

Sessão e contexto longo

O SDK em TypeScript não tem um objeto cliente que segura a sessão como o ClaudeSDKClient do Python

A continuidade se faz na própria chamada: passa continue: true em cada query() seguinte e ele retoma a sessão mais recente do diretório atual

E tem a compaction automática, que resume o contexto mais antigo quando a coisa se aproxima do limite da janela

É o que estende conversa e tarefa longa sem você escrever rotina de sumarização na mão

Controle, extensão e segurança: hooks, subagentes e permissões

Se eu tivesse que apontar UM motivo pra subir de camada, seria este bloco aqui

O SDK oferece subagentes, agent skills, hooks, slash commands e plugins como recursos de extensão

Na API direta, nada disso existe: você escreveria equivalentes de tudo

Hooks: bloquear antes de acontecer

Hooks são funções de callback disparadas por eventos do agente

Uma ferramenta sendo chamada, uma sessão iniciando, a execução parando (PreToolUse, PostToolUse, SessionStart, por aí vai)

E o ponto forte: eles permitem BLOQUEAR operações perigosas antes de executarem

É o guardrail contra os rm -rf da vida, no lugar certo do fluxo

Subagentes: contexto isolado e paralelismo

Subagentes rodam com janela de contexto isolada, podem rodar em paralelo e podem ser limitados a ferramentas específicas

Dá pra ter um subagente que só lê (Read e Grep, por exemplo) enquanto outro faz o trabalho pesado

Separa o barulho da investigação do contexto principal, e ainda reduz a superfície do que cada pedaço consegue tocar

Permissões: modo, regra e o callback

O controle de permissões usa modos e regras pro que é liberado automaticamente

E tem o callback canUseTool pra decidir o resto em tempo de execução, caso a caso

É com essa peça que tu define o que o agente acessa nos arquivos e o que fica fora do alcance dele

MCP no meio do caminho

O SDK tem suporte de cliente MCP

E as ferramentas MCP seguem um padrão fixo de nome: mcp__<server>__<action>

Saber esse padrão importa na hora de escrever regra de permissão, porque é por esse nome que tu libera ou barra uma ferramenta de servidor externo

API direta x Claude Agent SDK: comparação linha a linha

Que tipo de projeto pede cada caminho

Tabela é bonita, mas decisão boa vem de caso concreto

Então vamos aos cenários que aparecem de verdade no dia a dia

Classificação, extração, resumo e geração de texto: API direta

Se o seu endpoint recebe um texto, manda pro modelo e devolve a resposta, para por aí

Uma chamada, uma resposta, sem ferramenta, sem iteração

O POST em /v1/messages (ou o SDK cliente da sua linguagem) resolve, e a superfície do seu sistema continua mínima

Colocar um harness de agente aqui é matar formiga com bazuca 😀

Automação que lê arquivo, roda comando e edita código: Claude Agent SDK

Agora inverte: a tarefa precisa OLHAR o repositório, rodar um comando, ver o resultado e decidir o próximo passo

Isso é loop, não é chamada

E loop com execução de ferramenta é exatamente o que essa camada já entrega implementado

Se você fosse fazer isso na API crua, ia acabar reescrevendo o mesmo agente, só que pior e sem os hooks

Preciso de aprovação humana antes do agente agir

Esse é o caso mais fácil de decidir

Quando a operação é sensível, tu quer poder barrar antes da execução, e não descobrir depois

É PreToolUse bloqueando, permission rules liberando o que é seguro e canUseTool decidindo o resto em tempo real

Na camada crua, isso é código seu do começo ao fim

Tarefa longa, que passa da janela de contexto

Tarefa que se arrasta acumula histórico, e histórico acumulado bate no limite da janela

O SDK faz compaction automática, resumindo o contexto mais antigo conforme se aproxima do limite

Se a sua tarefa é curta e cabe numa chamada, isso não te serve de nada

Se ela é longa, isso é a diferença entre funcionar e travar

Meu projeto tem que rodar em Bedrock, Vertex ou Foundry

Esse aparece dos dois lados, e a diferença é de configuração

O SDK pode rodar sobre provedores de nuvem em vez da API direta, ligado por variável de ambiente: CLAUDE_CODE_USE_BEDROCK=1 pra Amazon Bedrock, CLAUDE_CODE_USE_VERTEX=1 pro Google Cloud e CLAUDE_CODE_USE_FOUNDRY=1 pro Microsoft Foundry

Ou seja: exigência de nuvem corporativa não te obriga a descer pra camada crua

A terceira camada: Claude Managed Agents

E tem um caminho que quase ninguém lembra na hora de comparar

O Claude Managed Agents é um serviço hospedado na Claude Platform que roda o harness, o agent loop e a execução de ferramentas do lado da Anthropic

Ele suporta sessões longas e guarda o estado no servidor: histórico, sandbox e saídas

As requisições da API de Managed Agents exigem um cabeçalho beta específico: managed-agents-2026-04-01

A leitura prática é essa: se você NÃO quer manter infraestrutura de execução (onde o agente roda comando, onde ele guarda arquivo, quem limpa a sandbox), essa camada existe justamente pra tirar isso do seu prato

Renomeação e migração: o que quebra no código antigo

Se você pegou tutorial de 2025 e o import não bate, calma, não é você

O Claude Code SDK foi renomeado para Claude Agent SDK, com anúncio em 29 de setembro de 2025

E a migração traz mudanças que quebram código antigo de verdade:

• o SDK não usa mais o system prompt do Claude Code por padrão
• imports mudam de @anthropic-ai/claude-code para @anthropic-ai/claude-agent-sdk
• em Python, claude_code_sdk vira claude_agent_sdk
• e ClaudeCodeOptions vira ClaudeAgentOptions

Aquele primeiro item é o mais traiçoeiro: teu agente pode continuar rodando e simplesmente se comportar diferente, porque o comportamento padrão que ele herdava não vem mais de graça

E já que estamos falando de coisa que muda embaixo do pé: todo model ID do Claude é um snapshot fixo, inclusive os que não têm data no nome

A partir da geração 4.6 os IDs usam formato sem data, mas continuam sendo snapshot fixo, não um ponteiro que atualiza sozinho

Trocar de modelo é decisão explícita sua, nos dois caminhos

Veredito: qual caminho escolher (e quando trocar)

Vou ser direto

A API direta ganha em previsibilidade e superfície mínima

Você sabe exatamente o que sai e o que entra, o comportamento é o do seu código, e não tem harness nenhum tomando decisão por você

Pra tarefa de uma chamada, é o caminho certo e ponto

O Claude Agent SDK ganha no momento em que o custo de reimplementar loop, ferramentas, contexto, permissão e retomada de sessão fica MAIOR que o custo de adotar a camada

E esse momento chega mais rápido do que parece, geralmente na primeira vez que você precisa de "o agente rodou o comando, viu o erro e tentou de novo"

No eixo custo, um dado que dá pra usar como âncora: o Claude Sonnet 5 na API custa US$ 2 por milhão de tokens de entrada e US$ 10 por milhão de tokens de saída

Esse preço introdutório virou preço padrão em 10 de agosto de 2026, e o reajuste que estava marcado pra 1 de setembro de 2026 (US$ 3 / US$ 15) foi cancelado

Agora o ponto honesto: agente consome mais tokens por natureza

Ele lê arquivo, chama ferramenta, recebe resultado, decide de novo, e cada volta dessas passa pelo modelo

Não vou te dar número comparando o consumo de uma tarefa na API direta contra a mesma tarefa rodando no SDK, porque não tenho medição confiável pra isso, e chutar métrica é o tipo de coisa que eu acho zoado

O que dá pra afirmar sem medo: mais iteração é mais token, e isso entra na conta antes de você escolher a camada

Conclusão

Recapitulando o que importa na hora de decidir:

API direta é um POST em https://api.anthropic.com/v1/messages com x-api-key, anthropic-version: 2023-06-01 e content-type: application/json, e você escreve o resto

O Claude Agent SDK te entrega o agent loop, as ferramentas embutidas e o gerenciamento de contexto do Claude Code, em Python e TypeScript, mais hooks, subagentes, permissões e cliente MCP

E o Claude Managed Agents tira até a infraestrutura de execução das suas costas

Meu conselho de próximo passo é não começar pela camada mais chique

1. pegue o caso de uso MAIS simples do seu projeto e escreva ele na API direta primeiro
2. observe se ele precisou de ferramenta e de iteração pra fechar a tarefa, ou se uma chamada resolveu
3. se precisou, aí sim instale o SDK da sua linguagem: npm install @anthropic-ai/claude-agent-sdk ou pip install claude-agent-sdk
4. configure a chave com export ANTHROPIC_API_KEY=your-api-key e rode a primeira query()

Subir de camada com um caso real na mão é MUITO diferente de subir por hype

Bora testar? 🙂

até o próximo post!