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

> Guia completo do Claude Agent SDK: o runtime open-source que move o Claude Code, agora programável em Python e TypeScript. Tutorial, deep dive no agent...

Source: https://agentify.ia.br/blog/claude-agent-sdk/

> **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](/blog/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](https://github.com/anthropics/claude-agent-sdk-python) e [claude-agent-sdk-typescript](https://github.com/anthropics/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](https://devblogs.microsoft.com/agent-framework/build-ai-agents-with-claude-agent-sdk-and-microsoft-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](https://platform.claude.com/) 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=,
 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](/blog/harness-e-loop-arquitetura-agentes).

### Tools Built-in — O Arsenal Completo

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

 Tool
 O que faz

 Read
 Lê qualquer arquivo (inclusive imagens, PDFs, notebooks)

 Write
 Cria ou sobrescreve arquivos

 Edit
 Edições precisas via string replacement

 Bash
 Executa comandos shell (timeout padrão: 2min)

 Monitor
 Roda processos em background e reage a cada linha de output

 Glob
 Encontra arquivos por pattern ( **/*.ts , src/**/*.py )

 Grep
 Busca conteúdo em arquivos com regex (usa ripgrep por baixo)

 WebSearch
 Busca na web com summarização automática

 WebFetch
 Busca e parseia uma URL específica

 Agent
 Spawna subagentes para subtarefas

 AskUserQuestion
 Pausa para perguntar ao usuário (múltipla escolha)

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](/blog/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:

- **Managed Policy** (organizacional) — aplica a todos os usuários

- **User** (`~/.claude/CLAUDE.md`) — preferências pessoais cross-projeto

- **Project** (`./CLAUDE.md`) — convenções do time, commitado no repo

- **Local** (`./CLAUDE.local.md`) — overrides pessoais, gitignored

- **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](https://modelcontextprotocol.io) é o padrão da Anthropic para conectar agentes a ferramentas externas: databases, browsers, APIs, e [centenas de integrações](https://github.com/modelcontextprotocol/servers).

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

 Modo
 Comportamento

 default
 Leitura auto-aprovada, edições pedem permissão

 acceptEdits
 Edições e writes auto-aprovados, Bash arbitrário pede permissão

 plan
 Somente leitura — sem modificações

 auto
 Classificador AI decide em tempo real o que é seguro

 dontAsk
 Auto-nega tudo que não está na allowlist explícita

 bypassPermissions
 Auto-aprova tudo (exceto rm -rf / e rm -rf ~ )

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
```

 Eixo
 Score
 Justificativa

 Agent Loop
 9.5
 Loop battle-tested do Claude Code; compactação automática; budget caps

 Tools/Builtins
 9.0
 10+ ferramentas prontas (filesystem, shell, web, code intelligence)

 Facilidade de Início
 8.0
 3 linhas para rodar; porém requer entender o modelo mental de subprocesso

 Multi-Agent
 8.5
 Subagentes + Teams experimentais; isolamento por worktree

 MCP/Extensibilidade
 9.5
 MCP como cidadão de primeira classe; deferred loading; hooks ricos

 Observabilidade
 9.0
 OpenTelemetry, hooks em 30+ eventos, transcripts JSONL, cost tracking

 Produção/Deploy
 8.5
 Sessões persistentes, Routines remotas, hosting guides oficiais

 Comunidade/Ecossistema
 7.0
 Crescendo rápido; docs excelentes; mas menos maduro que LangChain

 Custo/Pricing
 6.5
 Créditos separados desde jun/2026; Claude-only; API rates

 Model Lock-in
 4.0
 Exclusivo para modelos Claude (Bedrock/Vertex amenizam parcialmente)

### Comparativo rápido com outros frameworks

 Framework
 Melhor para
 Limitação principal

 Claude Agent SDK
 Tool-use agents com raciocínio complexo
 Claude-only

 OpenAI Agents SDK
 Simplicidade para começar; ecossistema OpenAI
 Menos tools built-in

 LangGraph
 Workflows stateful e multi-step em produção
 Curva de aprendizado íngreme

 CrewAI
 Multi-agent rápido com pouco código
 Menos controle fino

 Google ADK
 Integração nativa com Gemini e GCP
 Ecossistema mais jovem

 Pydantic AI
 Type safety e validação rigorosa
 Escopo mais limitado

 Microsoft Agent Framework
 Orquestração multi-provider (Azure, Claude, OpenAI)
 Complexidade enterprise

 Vercel AI SDK
 Frontend-first com streaming React
 Foco em UI, menos backend

Para um comparativo mais profundo entre harnesses de agentes, leia nosso artigo sobre [agent frameworks vs coding agents](/blog/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

- **Instale e rode o quickstart** — 5 minutos para o primeiro agente funcional

- **Explore os [example agents](https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-overview)** oficiais — email assistant, research agent, code reviewer

- **Conecte seu primeiro MCP server** — Playwright para browser automation é ótimo para começar

- **Implemente hooks** — comece com um audit log simples em `PostToolUse`

- **Leia sobre sessions** — resumir e forkar sessões abre padrões avançados de testing

- **Considere Routines** para automação que roda sem terminal aberto

### Recursos

- [Documentação oficial do Agent SDK](https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-overview)

- [SDK Python no GitHub](https://github.com/anthropics/claude-agent-sdk-python)

- [SDK TypeScript no GitHub](https://github.com/anthropics/claude-agent-sdk-typescript)

- [Microsoft Agent Framework + Claude](https://devblogs.microsoft.com/agent-framework/build-ai-agents-with-claude-agent-sdk-and-microsoft-agent-framework/)

- [MCP Servers Registry](https://github.com/modelcontextprotocol/servers)

---

## Leia Também

- [Claude Code: O Que É e Como Funciona](/blog/claude-code)

- [Agent Frameworks vs Coding Agents: Entendendo as Diferenças](/blog/agent-frameworks-vs-coding-agents)

- [Harness e Loop: A Arquitetura por Trás dos Agentes](/blog/harness-e-loop-arquitetura-agentes)

- [Ferramentas, Tools e MCP Servers: O Ecossistema Completo](/blog/ferramentas-tools-e-mcp-servers)

---

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

-->