Claude Agent SDK vs Claude Code: 3 critérios

“Dá pra fazer tudo com o Claude Code” é a frase que mais ouço de quem está começando com agentes IA aqui no Brasil. É quase verdade. É também o motivo pelo qual muita gente paga mais caro do que precisa, e paga pelo tipo errado de ferramenta.

A Anthropic lançou, em setembro de 2025 (renomeando o antigo Claude Code SDK), o Claude Agent SDK em Python e TypeScript (doc oficial). O SDK ocupa outro espaço no catálogo: é uma ferramenta pensada para rodar sem você na frente da tela, com propósito distinto do CLI interativo.

Antes de assinar o Ultra por R$ 1.000/mês (≈ US$ 200/mo), vale decidir qual das duas você realmente precisa. Este post compara nos 3 critérios que, no fim, decidem a conta: ciclo de vida, custo por token, e onde ficam os hooks.

Critério 1: Ciclo de vida — quem controla o loop

O Claude Code é interativo. Você abre o terminal, digita claude, conversa, interrompe, redireciona. O loop de pensar/executar/esperar fica com o CLI. Você é o co-piloto.

O Claude Agent SDK é programático. Seu código Python chama query() ou ClaudeSDKClient, recebe mensagens via async for, e decide o que fazer com cada bloco. O loop fica no seu script.

from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        system_prompt="Você é um revisor de PRs sênior",
        permission_mode="acceptEdits",
    )
    async for message in query(prompt="Revise o PR #123", options=options):
        print(message)

Esse script roda sem ninguém na frente. Dá pra colocar num cron, num GitHub Action, num worker que escuta uma fila. Com Claude Code você até consegue um modo “pipe” (claude -p), mas o ciclo de vida continua pensado pra conversa.

Regra prática: se a tarefa cabe numa sessão em que você está presente para interromper, Claude Code. Se a tarefa precisa rodar às 3 horas da manhã sem supervisão, Agent SDK.

Critério 2: Custo por token — bundled vs direto

Aqui a conta muda de forma, não só de valor.

O Claude Code vem incluído no plano: você paga um teto e consome dentro da janela. Tarefa mais barata ou mais cara, o valor do mês continua o mesmo até estourar o limite. Previsível.

O Agent SDK não tem teto implícito. Cada chamada consome tokens no console da Anthropic, do mesmo pool que você usaria no Messages API. Isso é ótimo quando a tarefa é curta e esporádica (um agente que revisa 5 PRs/dia custa centavos de dólar), mas perigoso quando o loop fica preso num tool-call em círculo — a conta do mês pode dobrar sem ninguém notar.

Quem roda agente programático em produção precisa de limite por runtime no código:

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    max_turns=20,          # trava no 20º turno
    permission_mode="plan"  # pede confirmação antes de modificar arquivos
)

Sem isso, um agente que entrou em loop de retry custa mais num fim de semana do que o Ultra custa no mês.

Critério 3: Hooks e permissões — onde moram as regras

Essa diferença é a que mais chama atenção na prática.

No Claude Code, hooks e permissions moram em settings.json fora do código:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "eslint --fix $CLAUDE_FILE_PATHS" }
        ]
      }
    ]
  }
}

O CLI carrega, aplica, e o script cliente não precisa saber que existem. Isso é bom para quem quer que o time inteiro siga a mesma regra de review sem tocar em código.

No Agent SDK, hooks viram parâmetros da chamada:

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

async def allow_all(input_data, tool_use_id, context):
    return {
        "hookSpecificOutput": {
            "hookEventName": input_data["hook_event_name"],
            "permissionDecision": "allow",
        }
    }

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [HookMatcher(hooks=[allow_all])]}
)

A vantagem: hook agora é código versionado no repositório do agente, revisável no PR, testável com pytest. A desvantagem: cada equipe que usa seu SDK precisa importar a mesma função de hook (ou reimplementar), ou não compartilha nada.

Regra prática: se as regras precisam ficar fora da aplicação (time grande, governança separada), Claude Code. Se as regras são parte do produto (agente embarcado num SaaS), Agent SDK.

Decidindo caso a caso (visão BR)

Juntando os 3 critérios, o quadro de decisão fica mais claro.

Uma observação de quem paga em real: o Ultra em dólar fica em torno de R$ 1.000/mês (câmbio de novembro de 2026). Isso é muito mais que um salário mínimo e mais que um estagiário part-time em muitos municípios. A conta só fecha se você consegue trocar essas horas por entregas que valem mais que isso — o que é verdade para dev sênior em horário comercial, mas talvez não para automação noturna, onde o SDK pago por token raramente passa de US$ 30/mês mesmo rodando tarefas pesadas.

O erro mais comum é pagar Ultra e usar como se fosse SDK: deixar o Claude Code aberto numa pipeline. Mesmo sem a janela de 5h, você vai esbarrar nos limites semanais do plano, pagar por teto que não precisava, e ainda vai precisar ficar reiniciando a sessão. O caminho certo é SDK (API-key) com max_turns travado.

Onde cada ferramenta ainda vence em 2026

O Claude Code continua imbatível no “pair programmer que entende seu repositório”. Nenhum SDK consegue competir com o CLI num loop de conversa rápida: interrompi, redirecionei, voltei, pedi para olhar outro arquivo. Essa fluidez é o produto.

O Agent SDK vence no outro extremo: tarefas que precisam rodar sozinhas, com limite rígido de custo, hook versionado, e sem janela de 5h para atrapalhar. Isso cobre quase tudo que vai para produção.

A escolha certa é delimitar o território de cada um: Claude Code para o dia-a-dia de código com humano no loop, Agent SDK para tarefas automatizadas sem supervisão. Os dois são da Anthropic, mas têm propósitos diferentes; e o Brasil, em particular, não tem orçamento folgado para pagar o errado.

---

ken imoto · WebRTC & Voice AI engineer · kenimoto.dev · TabNews