Claude Code SDK: Guia para Desenvolvedores em Python e TypeScript

O Claude Code SDK — agora oficialmente chamado de Claude Agent SDK — é uma biblioteca Python e TypeScript que permite executar o Claude como um agente autônomo dentro da sua própria aplicação. Você fornece um prompt, e ele cuida do resto: ler arquivos, executar comandos, editar código e iterar até que a tarefa seja concluída. Sem necessidade de escrever um loop de ferramentas, sem ter que gerenciar streaming.

Este guia aborda tudo o que os desenvolvedores precisam para começar: instalação, a API principal query(), ferramentas integradas, ganchos, sessões, subagentes, integração com MCP e como usar a API LLM da Novita AI como backend do modelo.

Principais Conclusões

• O Claude Code SDK agora é chamado de Claude Agent SDK (claude-agent-sdk para Python, @anthropic-ai/claude-agent-sdk para TypeScript).
• Uma única função query() substitui o loop manual de execução de ferramentas que seria necessário com o Anthropic Client SDK.
• Ferramentas integradas cobrem leitura de arquivos, edição, execução bash, pesquisa na web e muito mais — sem necessidade de implementação.
• Sessões permitem que agentes retomem trabalho em várias chamadas com o contexto intacto.
• Ganchos permitem validar, registrar ou bloquear chamadas de ferramentas em pontos específicos do ciclo de vida.
• O endpoint compatível com Anthropic da Novita AI (https://api.novita.ai/anthropic) permite usar modelos de peso aberto de alta qualidade com o mesmo código SDK.

O que é o Claude Code SDK?

O Claude Code SDK é uma interface programática para as capacidades de agente do Claude Code. Ele expõe as mesmas ferramentas, loop de raciocínio e gerenciamento de contexto que o Claude Code CLI usa interativamente — mas como uma biblioteca que você importa e chama do seu próprio código.

A Anthropic o renomeou para Claude Agent SDK a partir da geração 4.6, mas o termo de busca original ‘claude code sdk’ ainda descreve com precisão o que é: a camada SDK que fica sobre o Claude Code e permite automatizar tarefas de agente em software.

Para que serve:

• Revisão automatizada de código, refatoração ou geração de testes em CI/CD
• Agentes que leem e modificam arquivos, executam scripts ou pesquisam na web em seu nome
• Pipelines multi-agente onde um coordenador delega subtarefas a trabalhadores especializados
• Qualquer fluxo de trabalho onde você queira que o Claude tome ações autônomas de múltiplas etapas, não apenas responda a um prompt

Para o que não serve: Se você precisa de controle direto sobre cada mensagem, saída estruturada de uma única chamada ou respostas em streaming para uma interface de chat, o Anthropic Client SDK é mais adequado.

Claude Code SDK vs. Anthropic Client SDK: Quando Usar Cada Um

Ambos os SDKs são baseados no Claude, mas resolvem problemas diferentes.

	Claude Agent SDK	Anthropic Client SDK
Execução de ferramentas	Gerenciada autonomamente pelo Claude	Você implementa o loop de ferramentas
Interface	query() retorna um iterador assíncrono	client.messages.create() retorna um objeto de resposta
Ferramentas integradas	Read, Write, Edit, Bash, Grep, Glob, WebSearch e mais	Nenhuma — você define e executa todas as ferramentas
Sessões	Integradas — retome com um ID de sessão	Manual — gerencie o histórico de conversas você mesmo
Melhor para	Pipelines agentivos, CI/CD, operações de arquivos	Aplicativos de chat, saída estruturada, controle refinado

Se você quer que o Claude descubra quais arquivos ler e os edite autonomamente: Agent SDK. Se você quer que o Claude responda a um prompt específico e retorne um valor que você processa: Client SDK.

Instalar o Claude Agent SDK

Python (requer Python 3.10+):

pip install claude-agent-sdk

TypeScript / Node.js:

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

O pacote TypeScript inclui um binário nativo do Claude Code para sua plataforma como uma dependência opcional. Você não precisa instalar o Claude Code separadamente.

Para verificar sua versão do Python antes de instalar:

python3 --version  # macOS/Linux
py --version       # Windows

Se o pip relatar No matching distribution found for claude-agent-sdk, seu interpretador Python é mais antigo que 3.10.

Etapa 1: Configurar Autenticação

Defina sua chave de API da Anthropic como uma variável de ambiente:

export ANTHROPIC_API_KEY=your-api-key

O SDK também suporta Amazon Bedrock, Google Vertex AI e Azure AI Foundry para equipes que roteiam por provedores de nuvem:

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
# plus standard AWS credentials

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
# plus GOOGLE_CLOUD_PROJECT and gcloud credentials

# Microsoft Azure AI Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
# plus Azure credentials

Etapa 2: Executar Sua Primeira Consulta de Agente

Toda a superfície do SDK é construída em torno de uma única função: query(). Ela aceita um prompt e opções, e retorna um iterador assíncrono de eventos de mensagem.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="List all Python files in this directory",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

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

for await (const message of query({
  prompt: "List all Python files in this directory",
  options: { allowedTools: ["Bash", "Glob"] }
})) {
  if ("result" in message) console.log(message.result);
}

O iterador produz vários tipos de mensagem. Os dois mais úteis:

• ResultMessage (ou mensagens com um campo result) — a resposta final do agente
• SystemMessage com subtype === "init" — carrega o session_id para retomar mais tarde

Etapa 3: Controlar Permissões com allowedTools

O SDK vem com ferramentas pré-implementadas. Você declara quais o agente pode usar; o Claude cuida da execução.

Ferramenta	O que faz
Read	Ler qualquer arquivo no diretório de trabalho
Write	Criar novos arquivos
Edit	Fazer edições direcionadas em arquivos existentes
Bash	Executar comandos shell, scripts, operações git
Glob	Encontrar arquivos por padrão (**/*.ts, src/**/*.py)
Grep	Pesquisar conteúdo de arquivos com regex
WebSearch	Pesquisar na web por informações atuais
WebFetch	Buscar e analisar conteúdo de páginas web
Monitor	Observar um script em segundo plano e reagir a linhas de saída
AskUserQuestion	Perguntar ao usuário perguntas esclarecedoras durante a tarefa
Agent	Invocar um subagente definido

A combinação de Bash + Read + Edit é suficiente para a maioria das tarefas automatizadas de código. Adicione WebSearch ou WebFetch quando o agente precisar de dados externos.

allowed_tools (Python) / allowedTools (TypeScript) pré-aprova ferramentas específicas sem solicitação. Restringir o conjunto de ferramentas também limita o que o agente pode fazer involuntariamente — uma proteção útil para pipelines automatizados.

Agente de revisão de código somente leitura:

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Review this codebase for security issues and code smell",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
    ),
):
    if hasattr(message, "result"):
        print(message.result)

Agente de edição completa (pré-aprova gravações de arquivos):

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Edit", "Bash"],
    permission_mode="acceptEdits",
)

permission_mode="acceptEdits" aprova automaticamente edições de arquivos sem um prompt interativo, o que é necessário ao executar em CI.

Etapa 4: Usar Ganchos para Controle do Ciclo de Vida

Os ganchos permitem executar código personalizado em pontos definidos da execução do agente. Você pode registrar ações, validar entradas, bloquear operações perigosas ou atualizar estado externo.

Eventos de gancho disponíveis: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStop, SubagentStart, PreCompact, Notification, PermissionRequest

Este exemplo escreve um log de auditoria toda vez que o agente edita ou cria um arquivo:

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

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().isoformat()}: modified {file_path}\n")
    return {}

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

asyncio.run(main())

import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
import { appendFile } from "fs/promises";

const logFileChange: HookCallback = async (input) => {
  const filePath = (input as any).tool_input?.file_path ?? "unknown";
  await appendFile("./audit.log", `${new Date().toISOString()}: modified ${filePath}\n`);
  return {};
};

for await (const message of query({
  prompt: "Refactor auth.ts to use interfaces",
  options: {
    permissionMode: "acceptEdits",
    hooks: {
      PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

Um gancho PreToolUse que retorna { block: true } impedirá a chamada da ferramenta completamente — útil para aplicar políticas como ‘nunca deletar arquivos’ em contextos automatizados.

Etapa 5: Retomar Trabalho com Sessões

As sessões preservam o contexto completo do agente — quais arquivos ele leu, o que encontrou, o histórico da conversa — entre várias chamadas query(). Isso permite dividir uma tarefa longa em etapas ou continuar um trabalho que foi interrompido.

Para retomar uma sessão, capture o session_id do evento init do SystemMessage e depois passe-o para resume:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage

async def main():
    session_id = None

    # First query: read and analyze the codebase
    async for message in query(
        prompt="Read the authentication module and identify all external dependencies",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            session_id = message.data["session_id"]

    # Second query: continue with full context from the first
    async for message in query(
        prompt="Now check if any of those dependencies have known vulnerabilities",
        options=ClaudeAgentOptions(
            resume=session_id,
            allowed_tools=["Read", "Bash", "WebSearch"],
        ),
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

asyncio.run(main())

O segundo prompt usa ‘essas dependências’ — uma referência que só faz sentido porque a sessão carrega o contexto da primeira chamada. Sem resume, Claude não teria ideia do que você está se referindo.

Etapa 6: Delegar Tarefas com Subagentes

Subagentes são agentes especializados que seu agente principal pode invocar através da ferramenta Agent. O agente principal coordena; os subagentes fazem trabalho focado. Os resultados fluem de volta para o contexto principal.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Review this codebase: use the security-auditor agent for auth files and the style-checker agent for everything else",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "security-auditor": AgentDefinition(
                    description="Specialist in authentication and authorization security.",
                    prompt="Audit auth-related code for OWASP Top 10 vulnerabilities. Be specific about line numbers and risk severity.",
                    tools=["Read", "Glob", "Grep"],
                ),
                "style-checker": AgentDefinition(
                    description="Code style and maintainability reviewer.",
                    prompt="Check code for naming conventions, complexity, and documentation gaps.",
                    tools=["Read", "Glob"],
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Inclua "Agent" em allowed_tools para pré-aprovar invocações de subagentes. Mensagens de um subagente incluem um campo parent_tool_use_id para que você possa rastrear qual saída veio de qual subagente.

Etapa 7: Conectar Sistemas Externos via MCP

O Model Context Protocol (MCP) permite adicionar capacidades externas ao agente — bancos de dados, navegadores, APIs internas — sem escrever ferramentas personalizadas. O agente trata as ferramentas MCP da mesma forma que as ferramentas integradas.

Este exemplo adiciona automação de navegador via o servidor MCP Playwright:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Open https://example.com and describe the page structure",
        options=ClaudeAgentOptions(
            mcp_servers={
                "playwright": {
                    "command": "npx",
                    "args": ["@playwright/mcp@latest"]
                }
            }
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

A opção mcp_servers aceita qualquer servidor que siga a especificação MCP. O registro comunitário MCP em github.com/modelcontextprotocol/servers lista centenas de integrações incluindo Postgres, Puppeteer, Slack, GitHub e variantes de sistema de arquivos.

Usar Novita AI como Backend do Modelo

O Claude Agent SDK usa como padrão a API da Anthropic, mas você pode apontá-lo para o endpoint compatível com Anthropic da Novita AI para usar modelos de peso aberto econômicos — sem nenhuma alteração de código.

O endpoint da Novita AI espelha o formato da API Anthropic:

https://api.novita.ai/anthropic

Defina essas duas variáveis de ambiente antes de executar seu agente:

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_API_KEY="your-novita-api-key"

Suas chamadas query() existentes funcionam sem modificação. O SDK lê ANTHROPIC_BASE_URL automaticamente.

A Novita AI hospeda uma variedade de modelos — incluindo Kimi K2.5, GLM 5.2, MiniMax M2.1 e Qwen 3.5 — que são acessíveis através deste endpoint. Para equipes que constroem pipelines de agente que executam milhares de tarefas, a diferença de custo por token pode ser significativa. Veja Novita AI LLM API para o catálogo de modelos atual e preços.

Se você precisar implantar seu agente em infraestrutura de sandbox isolada — útil para execução de código agentivo onde você não quer que o agente toque no sistema de arquivos do host — o Novita Agent Sandbox fornece um ambiente de execução compatível com E2B construído especificamente para agentes construídos com o Claude Agent SDK.

Claude Code SDK em Pipelines CI/CD

As restrições de permission_mode="acceptEdits" e allowed_tools do SDK tornam prático executar agentes sem supervisão em CI. Um padrão típico do GitHub Actions:

- name: Run automated code review
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    python review_agent.py

Onde review_agent.py contém algo como:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Review all changed Python files in this PR for correctness and test coverage gaps. Output a JSON report.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Bash"],
            permission_mode="acceptEdits",
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Para agentes que escrevem de volta no repositório (refatoração automatizada, geração de documentação), combine isso com um gancho PostToolUse que valide as alterações antes que elas cheguem ao git.

Solução de Problemas

No matching distribution found for claude-agent-sdk Sua versão do Python é inferior a 3.10. Execute python3 --version e atualize se necessário.

ANTHROPIC_API_KEY is not set O SDK requer a variável de ambiente. Exporte-a no seu shell ou arquivo .env antes de executar.

Agente TypeScript sai antes de concluir Certifique-se de usar await no loop completo do iterador. O SDK precisa processar todos os eventos de mensagem antes que seu processo saia.

Agente usa ferramentas inesperadas Use allowed_tools para restringir explicitamente o conjunto de ferramentas. Se você não especificar, o agente terá acesso a todas as ferramentas integradas.

Mensagens de subagente não aparecem na saída Filtre mensagens onde parent_tool_use_id está definido para identificar a saída do subagente separadamente do agente principal.

Sessão não retomando corretamente Capture o session_id do SystemMessage com subtype === "init" no início da primeira consulta, não de uma mensagem de resultado.

Perguntas Frequentes

Qual é a diferença entre o Claude Code SDK e o Anthropic SDK?

O Claude Agent SDK (anteriormente Claude Code SDK) fornece um agente autônomo que gerencia a execução de ferramentas automaticamente. O Anthropic Client SDK fornece acesso bruto à API onde você implementa o loop de ferramentas você mesmo. Use o Agent SDK para pipelines agentivos; use o Client SDK para chamadas diretas ao modelo com controle preciso.

Qual versão do Python é necessária para o claude-agent-sdk?

Python 3.10 ou superior. O pacote não será instalado no Python 3.9 ou mais antigo.

Preciso instalar o Claude Code CLI para usar o SDK TypeScript?

Não. O pacote @anthropic-ai/claude-agent-sdk inclui seu próprio binário nativo do Claude Code como uma dependência opcional.

O Claude Agent SDK pode usar outros modelos além do Claude da Anthropic?

Ao definir ANTHROPIC_BASE_URL para um endpoint compatível com Anthropic como https://api.novita.ai/anthropic, você pode usar qualquer modelo que esse provedor hospeda — incluindo modelos de peso aberto da Kimi, GLM, MiniMax ou Qwen.

Como o Agent SDK é diferente do Claude Managed Agents?

Managed Agents é uma API REST hospedada onde a Anthropic executa o agente em sua infraestrutura. O Agent SDK é uma biblioteca que executa o loop do agente em seu próprio processo, em seu próprio sistema de arquivos. O Agent SDK é melhor para desenvolvimento local e agentes que precisam acessar seus arquivos ou serviços privados.

O Claude Agent SDK suporta saída em streaming?

A função query() retorna um iterador assíncrono que produz mensagens à medida que o agente trabalha. Isso oferece um comportamento semelhante a streaming — você vê resultados intermediários antes da resposta final.

Posso usar o Agent SDK com Amazon Bedrock ou Vertex AI?

Sim. Defina CLAUDE_CODE_USE_BEDROCK=1 mais credenciais AWS para Bedrock, ou CLAUDE_CODE_USE_VERTEX=1 mais credenciais do Google Cloud para Vertex AI.

Qual documentação do Anthropic Claude Agent SDK devo ler primeiro?

A documentação oficial está em code.claude.com/docs/en/agent-sdk/overview. Comece com o quickstart, depois leia os guias de sessões e ganchos assim que tiver um agente funcionando.

Artigos Recomendados

• Documentação do Claude Code CLI: Configuração, Comandos Slash e Integração com API LLM
• Vercel AI SDK: Guia Completo para Desenvolvedores na Criação de Aplicações de IA
• Como Implantar e Hospedar o Claude Agent SDK com Novita Sandbox

---

Fontes verificadas em 3 de julho de 2026: Documentação do Claude Agent SDK, API LLM da Novita AI