Claude Agent SDK: Guia Definitivo — O Motor do Claude Code nas Suas Mãos

TL;DR: O Claude Agent SDK é o motor open-source extraído do Claude Code — mesmo agent loop, mesmas ferramentas, mesmo gerenciamento de contexto — empacotado como biblioteca para Python e TypeScript. Você instala com pip install claude-agent-sdk ou npm install @anthropic-ai/claude-agent-sdk, aponta um prompt, e tem um agente autônomo com 10+ tools built-in, conexão com MCP servers, hooks de ciclo de vida e capacidade de spawnar subagentes. Desde junho de 2026 a Anthropic separou créditos de uso do Agent SDK dos limites de chat interativo. Este guia cobre da instalação ao deploy em produção — com tutorial hands-on, deep dive na arquitetura e comparativo com 7 outros frameworks.

O que é o Claude Agent SDK — e qual a relação com o Claude Code?

Se você já usou o Claude Code — aquele agente de terminal que lê arquivos, roda comandos, edita código e raciocina sobre seu codebase inteiro — então já experimentou o que o Agent SDK faz por baixo dos panos. A diferença é simples: o Claude Code é o produto finalizado que você usa interativamente; o Claude Agent SDK é o motor extraído que você embute nas suas próprias aplicações.

A Anthropic resume assim na documentação oficial:

“The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript.”

Ou seja, tudo que faz o Claude Code ser eficaz — o loop agêntico que decide quando parar, as ferramentas de filesystem e shell, o gerenciamento de janela de contexto com compactação automática, o sistema de permissões, os hooks — agora é uma biblioteca que você importa com uma linha.

Isso não é um wrapper fino sobre a API de mensagens. O SDK spawna um binário Claude Code como subprocesso, e a sua aplicação se comunica via stdin/stdout com um stream JSON estruturado. O subprocesso é dono do loop: ele chama tools, recebe resultados, decide se precisa mais ações, gerencia o token budget e emite mensagens estruturadas para você consumir como eventos. Sua aplicação vira uma observadora e interceptadora desse loop — não a implementadora.

Essa arquitetura tem implicações profundas:

• Persistência nativa: Sessões ficam em disco como JSONL — sobrevivem a restarts e podem ser resumidas por session ID.
• Hooks como compensação: Quando o loop não é seu, você precisa de pontos de interceptação ricos — e o SDK oferece 30+ eventos de hook.
• Isolamento de contexto: Subagentes rodam em processos separados com contexto limpo, sem poluir a janela do agente pai.

Contexto de mercado

O SDK foi originalmente chamado “Claude Code SDK” e renomeado em 2026 para refletir seu escopo mais amplo. Está disponível como open-source nos repos claude-agent-sdk-python e claude-agent-sdk-typescript.

Desde 15 de junho de 2026, o uso do Agent SDK em planos de assinatura consome um crédito mensal separado — diferente do limite de chat interativo. Valores vão de $20 (Pro) a $200 (Max 20x), metered a taxas de API.

A Microsoft integrou o Claude Agent SDK ao seu Agent Framework, permitindo orquestrar agentes Claude junto com agentes Azure OpenAI, GitHub Copilot e outros em workflows sequenciais, concorrentes e de handoff.

Tutorial: Do Zero ao Primeiro Agente

Vamos construir um agente funcional passo a passo. O objetivo: criar um agente que analisa um codebase, encontra TODOs e gera um relatório.

1. Instalação

Python (3.10+):

pip install claude-agent-sdk

TypeScript/Node.js:

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

O pacote TypeScript já embute o binário nativo do Claude Code para sua plataforma — não precisa instalar nada separado.

2. Configurar a API Key

Pegue sua chave na Console da Anthropic e exporte:

export ANTHROPIC_API_KEY=sk-ant-api03-sua-chave-aqui

O SDK também suporta autenticação via Amazon Bedrock (CLAUDE_CODE_USE_BEDROCK=1), Google Vertex AI (CLAUDE_CODE_USE_VERTEX=1) e Microsoft Azure Foundry (CLAUDE_CODE_USE_FOUNDRY=1).

3. Criar o primeiro agente

Python:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="What files are in this directory? List them organized by type.",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob", "Read"]),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

TypeScript:

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

const messages = query({
  prompt: "What files are in this directory? List them organized by type.",
  options: { allowedTools: ["Bash", "Glob", "Read"] },
});

for await (const message of messages) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Rode e observe: o agente usa Glob para encontrar arquivos, Read para inspecionar alguns, e retorna um resultado estruturado.

4. Adicionar tools customizadas

O poder real aparece quando você conecta ferramentas externas via MCP:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Open the project README on GitHub and summarize it",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "WebFetch"],
            mcp_servers={
                "playwright": {
                    "command": "npx",
                    "args": ["@playwright/mcp@latest"]
                }
            }
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

5. Agente com subagentes

Agora vamos criar algo mais sofisticado — um agente que delega tarefas para subagentes especializados:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
    async for message in query(
        prompt="Analyze this codebase: find all TODOs, review security patterns, and generate a report",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "todo-finder": AgentDefinition(
                    description="Finds all TODO/FIXME/HACK comments in the codebase.",
                    prompt="Search for TODO, FIXME, and HACK comments. List each with file path and line.",
                    tools=["Grep", "Glob"],
                ),
                "security-reviewer": AgentDefinition(
                    description="Reviews code for common security anti-patterns.",
                    prompt="Look for hardcoded secrets, SQL injection risks, and missing input validation.",
                    tools=["Read", "Grep", "Glob"],
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

O agente pai orquestra: ele decide quando chamar cada subagente, coleta os resultados e sintetiza o relatório. Os subagentes rodam com contexto isolado — não veem a conversa do pai.

6. Executar com controles de custo

Em produção, você precisa de limites:

async for message in query(
    prompt="Refactor the authentication module for better testability",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash", "Glob", "Grep"],
        max_turns=30,
        max_budget_usd=2.00,
        effort="high",
        permission_mode="acceptEdits",
    ),
):
    if hasattr(message, "result"):
        print(f"Custo total: ${message.total_cost_usd:.4f}")
        print(f"Turns: {message.num_turns}")

Deep Dive: A Arquitetura por Dentro

Se o tutorial mostra o como, esta seção explica o porquê. Entender a arquitetura interna te permite tomar decisões informadas sobre quando e como usar cada feature.

O Agent Loop — O Coração de Tudo

O loop agêntico segue um padrão cíclico: reunir contexto → agir → verificar → repetir. Cada iteração é um “turn” — uma ida-e-volta completa onde Claude recebe input, avalia, chama zero ou mais tools, e produz uma resposta.

O loop termina quando:

• Claude produz uma resposta sem tool calls (sucesso)
• max_turns é atingido
• O budget (max_budget_usd) estoura
• A janela de contexto força compactação

A compactação automática é um detalhe que muitas integrações erram. Quando o agente se aproxima do limite de contexto, o SDK resume turns anteriores em uma representação comprimida e re-injeta os arquivos CLAUDE.md do zero. O evento compact_boundary sinaliza isso — aplicações que parsam histórico de mensagens sem tratar esse boundary veem contagens inconsistentes.

Para uma exploração mais profunda sobre como loops agênticos funcionam em diferentes frameworks, veja nosso guia sobre harness e arquitetura de loops de agentes.

Tools Built-in — O Arsenal Completo

O SDK vem com 10+ ferramentas prontas para uso imediato, sem implementação sua:

A diferença fundamental entre o Agent SDK e o Client SDK da Anthropic mora aqui: com o Client SDK, você implementa o tool loop. Com o Agent SDK, Claude cuida disso autonomamente:

# Client SDK: você implementa o loop
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)
    response = client.messages.create(tool_result=result, **params)

# Agent SDK: Claude cuida das tools autonomamente
async for message in query(prompt="Fix the bug in auth.py"):
    print(message)

Para uma visão abrangente do ecossistema de ferramentas e protocolos MCP, confira nosso artigo sobre ferramentas, tools e MCP servers.

Context Management — Memória em Camadas

O SDK implementa um sistema hierárquico de injeção de contexto via arquivos CLAUDE.md:

1. Managed Policy (organizacional) — aplica a todos os usuários
2. User (~/.claude/CLAUDE.md) — preferências pessoais cross-projeto
3. Project (./CLAUDE.md) — convenções do time, commitado no repo
4. Local (./CLAUDE.local.md) — overrides pessoais, gitignored
5. Subdirectory (src/api/CLAUDE.md) — instruções específicas por pasta, carregadas sob demanda

Esse carregamento lazy é elegante: instruções específicas de um diretório só aparecem no contexto quando Claude está efetivamente trabalhando ali. Você não paga tokens por contexto irrelevante.

A Auto Memory persiste em ~/.claude/projects/<path>/memory/ e é compartilhada entre worktrees do mesmo repo — o agente não perde conhecimento acumulado ao trocar de branch.

MCP — Estendendo a Superfície de Ação

O Model Context Protocol é o padrão da Anthropic para conectar agentes a ferramentas externas: databases, browsers, APIs, e centenas de integrações.

O SDK trata MCP como cidadão de primeira classe:

options = ClaudeAgentOptions(
    mcp_servers={
        "postgres": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-postgres"],
            "env": {"DATABASE_URL": "postgresql://..."}
        },
        "github": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-github"],
            "env": {"GITHUB_TOKEN": "ghp_..."}
        }
    }
)

Tools MCP aparecem com namespace mcp__<server>__<tool>. O SDK faz deferred loading — schemas são carregados sob demanda via ToolSearch, não pré-carregados na janela de contexto. Isso permite trabalhar com catálogos grandes de ferramentas sem desperdiçar tokens.

Cada subagente pode ter sua própria configuração MCP — um agente de pesquisa com web search, um agente de código com sandbox local, um agente de comunicação com Slack, todos isolados.

Multi-Agent — Subagentes e Teams

O SDK oferece dois modelos de coordenação:

Subagentes (hierárquico): O agente pai delega tarefas. Subagentes executam com contexto isolado e reportam de volta. Máximo 2 níveis de profundidade — subagentes não podem spawnar outros subagentes.

Tipos built-in:

• Explore — modelo rápido (Haiku), somente leitura, para exploração de codebase
• Plan — somente leitura, mas usa o modelo principal para qualidade de raciocínio
• general-purpose — herda todas as tools e o modelo do pai

Agent Teams (peer-to-peer): Habilitado via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Teammates compartilham uma lista de tarefas, se auto-atribuem trabalho e se comunicam diretamente via SendMessage. Diferente de subagentes, teammates são persistentes — mantêm contexto entre tarefas.

Hooks — Interceptar Toda Ação

Os hooks são onde a capacidade de produção mora. 30+ eventos nomeados cobrem cada momento significativo:

• PreToolUse / PostToolUse — antes/depois de cada tool call
• Stop — quando o agente termina (retornar exit code 2 manda ele continuar!)
• SessionStart / SessionEnd — lifecycle da sessão
• PreCompact / PostCompact — ao redor da compactação de contexto

Exemplo prático — auditoria de mudanças em arquivos:

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
from datetime import datetime


async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now()}: modified {file_path}\n")
    return {}


async def main():
    async for message in query(
        prompt="Refactor utils.py to improve readability",
        options=ClaudeAgentOptions(
            permission_mode="acceptEdits",
            hooks={
                "PostToolUse": [
                    HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
                ]
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

Permissões — 6 Níveis de Autonomia

Regras de permissão usam matchers granulares: Bash(npm run *) pré-aprova npm run. WebFetch(domain:example.com) aprova fetches daquele domínio.

Spider Chart: Claude Agent SDK vs. 7 Frameworks

Avaliação comparativa em 8 eixos (escala 1-10):

                    Claude Agent SDK
                         9.5
                          ★
                         /|\
                        / | \
            Tools/     /  |  \    Facilidade
          Builtins    /   |   \   de Início
             9.0  ───★    |    ★─── 8.0
                  /   \   |   /   \
                 /     \  |  /     \
    Multi-      /       \ | /       \    Model
    Agent   ───★         \|/         ★─── Lock-in
      8.5      |          ★          |     4.0
               |     Observa-        |
    MCP/       |     bilidade        |
    Extensi- ──★─────────────────────★── Comunidade/
    bilidade   9.0        9.0           Ecossistema
      9.5      |                     |     7.0
               |                     |
               ★─────────────────────★
           Produção/              Custo/
           Deploy                 Pricing
             8.5                    6.5

Comparativo rápido com outros frameworks

Para um comparativo mais profundo entre harnesses de agentes, leia nosso artigo sobre agent frameworks vs coding agents.

Prós e Contras

✅ Prós

• Motor battle-tested: Mesmo runtime que alimenta o Claude Code usado por milhões de devs
• Zero boilerplate de tools: Filesystem, shell, web search, code editing — tudo pronto
• Hooks extremamente granulares: 30+ pontos de interceptação para audit, policy, transforms
• MCP nativo: Centenas de integrações disponíveis sem código adicional
• Sessões persistentes: Resume de onde parou; transcripts em disco; fork de sessões
• Multi-agent real: Subagentes isolados + Teams peer-to-peer com lista de tarefas compartilhada
• Worktree isolation: Agentes paralelos sem conflito de filesystem
• Observabilidade: OpenTelemetry, cost tracking, transcript JSONL — pronto para produção
• Dual-language: Python e TypeScript com APIs quase idênticas
• Microsoft Agent Framework: Integração oficial para orquestrar com outros providers

❌ Contras

• Model lock-in: Exclusivo para modelos Claude — não funciona com GPT, Gemini, Llama etc.
• Créditos separados desde jun/2026: Uso programático consome crédito à parte; custos podem escalar rápido
• Subprocesso opaco: O loop não é seu código — debugging requer entender o modelo mental
• Sem self-host do modelo: Depende da API da Anthropic (ou Bedrock/Vertex/Foundry)
• Teams ainda experimental: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 — API pode mudar
• Compactação pode perder nuances: Resumos de contexto nem sempre capturam detalhes finos
• Cold start: Spawnar o subprocesso tem latência inicial perceptível

Quando Usar o Claude Agent SDK

Use quando:

• Você já está no ecossistema Claude/Anthropic
• Precisa de agentes que manipulam filesystem e shell de verdade (não simulação)
• Quer construir pipelines CI/CD com agentes (code review, fix automático, testes)
• Precisa de multi-agent com isolamento real (worktrees)
• Quer estender com MCP sem reimplementar tool execution
• Raciocínio complexo é mais importante que custo mínimo por call
• Precisa de audit trail completo (hooks + transcripts + OpenTelemetry)

Considere alternativas quando:

• Model flexibility é requisito (múltiplos providers) → OpenAI Agents SDK ou LangGraph
• Custo é a prioridade absoluta → Pydantic AI com modelos locais
• Já tem stack LangChain em produção → LangGraph como evolução natural
• Precisa de orquestração visual low-code → n8n ou CrewAI
• Frontend-first com streaming React → Vercel AI SDK

Caso de uso ideal:

O Claude Agent SDK brilha em cenários onde você quer o mesmo poder do Claude Code, mas integrado programaticamente — automação de code review em CI, agentes de documentação, pipelines de refactoring, e qualquer workflow onde raciocínio profundo + ação no filesystem se encontram.

Próximos Passos

1. Instale e rode o quickstart — 5 minutos para o primeiro agente funcional
2. Explore os example agents oficiais — email assistant, research agent, code reviewer
3. Conecte seu primeiro MCP server — Playwright para browser automation é ótimo para começar
4. Implemente hooks — comece com um audit log simples em PostToolUse
5. Leia sobre sessions — resumir e forkar sessões abre padrões avançados de testing
6. Considere Routines para automação que roda sem terminal aberto

Recursos

• Documentação oficial do Agent SDK
• SDK Python no GitHub
• SDK TypeScript no GitHub
• Microsoft Agent Framework + Claude
• MCP Servers Registry

Leia Também

• Claude Code: O Que É e Como Funciona
• Agent Frameworks vs Coding Agents: Entendendo as Diferenças
• Harness e Loop: A Arquitetura por Trás dos Agentes
• Ferramentas, Tools e MCP Servers: O Ecossistema Completo

Quer receber análises técnicas como esta toda semana? Assine a newsletter em ft.ia.br — sem spam, só conteúdo denso sobre IA aplicada, agentes e automação.