SDK Claude Code (Claude Agent SDK): Guia para Python e TypeScript

O SDK Claude Code, renomeado para Claude Agent SDK no lançamento do SDK de agente da Anthropic, é uma biblioteca para Python e TypeScript que permite executar agentes de codificação autônomos dentro da sua aplicação. Ele lida com leitura de arquivos, comandos, edições de código, chamadas de ferramentas e iteração em múltiplas etapas sem a necessidade de um loop de ferramentas construído manualmente. Com o endpoint compatível com Anthropic da Novita AI, o mesmo SDK também pode executar modelos de peso aberto suportados, oferecendo às equipes um caminho de escolha de modelo e controle de custos além do backend padrão da Anthropic.

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

Principais Conclusões

• O SDK Claude Code agora se chama 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 SDK do Cliente Anthropic.
• Ferramentas integradas cobrem leitura de arquivos, edição, execução de bash, pesquisa na web e muito mais — sem necessidade de implementação.
• Sessões permitem que agentes retomem trabalho em múltiplas chamadas com contexto completo preservado.
• Hooks 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 do SDK.

O Que é o SDK Claude Code?

O SDK Claude Code é 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 a CLI Claude Code usa interativamente — mas como uma biblioteca que você importa e chama a partir 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 de 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ê deseja que Claude execute ações autônomas em múltiplas etapas, não apenas responda a um prompt

Para 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 SDK do Cliente Anthropic é mais adequado.

SDK Claude Code vs. SDK do Cliente Anthropic: Quando Usar Cada Um

Ambos os SDKs utilizam Claude, mas resolvem problemas diferentes.

	Claude Agent SDK	SDK do Cliente Anthropic
Execução de ferramentas	Gerenciada autonomamente por 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 da conversa você mesmo
Melhor para	Pipelines agentivos, CI/CD, operações com arquivos	Aplicativos de chat, saída estruturada, controle refinado

Se você quer que Claude descubra quais arquivos ler e os edite autonomamente: Agent SDK. Se você quer que 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 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 é anterior à versão 3.10.

Passo 1: Configurar Autenticação

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

export ANTHROPIC_API_KEY=sua-chave-api

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

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
# mais credenciais AWS padrão

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
# mais GOOGLE_CLOUD_PROJECT e credenciais gcloud

# Microsoft Azure AI Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
# mais credenciais do Azure

Passo 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="Liste todos os arquivos Python neste diretório",
        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: "Liste todos os arquivos Python neste diretório",
  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 depois

Passo 3: Controlar Permissões com allowedTools

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

Ferramenta	O que faz
Read	Lê qualquer arquivo no diretório de trabalho
Write	Cria novos arquivos
Edit	Faz edições direcionadas em arquivos existentes
Bash	Executa comandos shell, scripts, operações git
Glob	Encontra arquivos por padrão (**/*.ts, src/**/*.py)
Grep	Pesquisa conteúdos de arquivos com regex
WebSearch	Pesquisa na web por informações atuais
WebFetch	Busca e interpreta conteúdo de páginas web
Monitor	Monitora um script em segundo plano e reage a linhas de saída
AskUserQuestion	Pergunta ao usuário perguntas esclarecedoras durante a tarefa
Agent	Invoca 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="Revise esta base de código em busca de problemas de segurança e más práticas",
    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.

Passo 4: Usar Hooks para Controle do Ciclo de Vida

Hooks 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 hook 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", "desconhecido")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now().isoformat()}: modificado {file_path}\n")
    return {}

async def main():
    async for message in query(
        prompt="Refatore auth.py para usar 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 ?? "desconhecido";
  await appendFile("./audit.log", `${new Date().toISOString()}: modificado ${filePath}\n`);
  return {};
};

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

Um hook PreToolUse retornando { block: true } impedirá completamente a chamada da ferramenta — útil para impor políticas como “nunca excluir arquivos” em contextos automatizados.

Passo 5: Retomar Trabalho com Sessões

Sessões preservam o contexto completo do agente — quais arquivos ele leu, o que encontrou, o histórico da conversa — entre múltiplas chamadas de query(). Isso permite dividir uma tarefa longa em etapas ou continuar trabalho que foi interrompido.

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

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

async def main():
    session_id = None

    # Primeira consulta: ler e analisar a base de código
    async for message in query(
        prompt="Leia o módulo de autenticação e identifique todas as dependências externas",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            session_id = message.data["session_id"]

    # Segunda consulta: continuar com contexto completo da primeira
    async for message in query(
        prompt="Agora verifique se alguma dessas dependências tem vulnerabilidades conhecidas",
        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.

Passo 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; subagentes fazem trabalho focado. 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="Revise esta base de código: use o agente security-auditor para arquivos de autenticação e o style-checker para todo o resto",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "security-auditor": AgentDefinition(
                    description="Especialista em segurança de autenticação e autorização.",
                    prompt="Audite código relacionado a autenticação para vulnerabilidades OWASP Top 10. Seja específico sobre números de linha e gravidade do risco.",
                    tools=["Read", "Glob", "Grep"],
                ),
                "style-checker": AgentDefinition(
                    description="Revisor de estilo de código e manutenibilidade.",
                    prompt="Verifique o código quanto a convenções de nomenclatura, complexidade e lacunas de documentação.",
                    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.

Passo 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 servidor MCP Playwright:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Abra https://example.com e descreva a estrutura da página",
        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 de 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 com boa relação custo-benefício — sem alterações no código.

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

https://api.novita.ai/anthropic

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

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_API_KEY="sua-chave-api-novita"

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 API LLM Novita AI para o catálogo atual de modelos e preços.

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

SDK Claude Code 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: Executar revisão de código automatizada
  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="Revise todos os arquivos Python modificados neste PR quanto à correção e lacunas de cobertura de teste. Gere um relatório JSON.",
        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 hook PostToolUse que valida 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 em seu shell ou arquivo .env antes de executar.

Agente TypeScript encerra antes de completar Certifique-se de usar await no loop completo do iterador. O SDK precisa processar todos os eventos de mensagem antes que seu processo seja encerrado.

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

Mensagens de subagente não aparecendo na saída Filtre por 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 session_id do SystemMessage com subtype === "init" no início da primeira consulta, não de uma mensagem de resultado.

FAQ

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

O Claude Agent SDK (anteriormente SDK Claude Code) fornece um agente autônomo que lida com a execução de ferramentas automaticamente. O SDK do Cliente Anthropic fornece acesso direto à API onde você implementa o loop de ferramentas por conta própria. Use o Agent SDK para pipelines agentivos; use o Client SDK para chamadas diretas de 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 inferior.

Preciso instalar a CLI Claude Code 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 dependência opcional.

O Claude Agent SDK pode usar modelos que não sejam o Claude da Anthropic?

Definindo ANTHROPIC_BASE_URL para um endpoint compatível com Anthropic como https://api.novita.ai/anthropic, você pode usar qualquer modelo que esse provedor hospede — incluindo modelos de peso aberto de 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 fornece 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 hooks assim que tiver um agente funcionando.

Artigos Recomendados

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

---

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