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

Índice

Principais Conclusões
O que é o Claude Code SDK?
SDK Claude Code vs. SDK Anthropic Client: Quando Usar Cada Um
Instalar o Claude Agent SDK
Passo 1: Configurar Autenticação
Passo 2: Executar Sua Primeira Consulta de Agente
Passo 3: Controlar Permissões com allowedTools
Passo 4: Usar Hooks para Controle do Ciclo de Vida
Passo 5: Retomar Trabalho com Sessões
Passo 6: Delegar Tarefas com Subagentes
Passo 7: Conectar Sistemas Externos via MCP
Usar Novita AI como Backend do Modelo
SDK Claude Code em Pipelines CI/CD
Solução de Problemas
FAQ
Artigos Recomendados

O Claude Code SDK, renomeado para Claude Agent SDK no lançamento do SDK de agente da Anthropic, é uma biblioteca Python e TypeScript para 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 várias etapas sem 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 pesos abertos suportados, oferecendo às equipes um caminho de escolha de modelo e controle de custos além do backend padrão da Anthropic. Para a comparação entre assinatura e API, veja Preço da API Claude vs. planos de assinatura.

Este guia cobre tudo que os desenvolvedores precisam para começar: instalação, a API central query(), ferramentas integradas, hooks, sessões, subagentes, integração 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 você precisaria com o Anthropic Client SDK.
As ferramentas integradas cobrem leitura de arquivos, edição, execução bash, pesquisa na web e mais — sem necessidade de implementação.
As sessões permitem que os agentes retomem o trabalho em várias chamadas com o contexto completo preservado.
Os 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 pesos abertos de alta qualidade com o mesmo código do 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 a partir do seu próprio código. Para regras e escopo no nível do projeto, veja Regras do Claude Code e CLAUDE.md.

A Anthropic o renomeou para Claude Agent SDK a partir da geração 4.6, mas o termo de pesquisa 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 multiagente onde um coordenador delega subtarefas a trabalhadores especializados
Qualquer fluxo de trabalho onde você deseja que Claude execute ações autônomas em várias 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 Anthropic Client SDK é mais apropriado.

SDK Claude Code vs. SDK Anthropic Client: 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 da conversa você mesmo
Melhor para	Pipelines agenticos, CI/CD, operações de arquivo	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 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 pip relatar No matching distribution found for claude-agent-sdk, seu interpretador Python é anterior ao 3.10.

Passo 1: Configurar Autenticação

Defina sua chave de API Anthropic como uma 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 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údo de arquivos com regex
WebSearch	Pesquisa na web por informações atuais
WebFetch	Busca e analisa conteúdo de páginas web
Monitor	Observa 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 este código para problemas de segurança e 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.

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 que retorna { block: true } impedirá completamente a chamada de ferramenta — útil para aplicar políticas como “nunca excluir arquivos” em contextos automatizados.

Passo 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 — em 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 de inicialização SystemMessage e 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 o 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 o 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 o trabalho focado. Os resultados retornam ao contexto principal.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Revise este código: use o agente auditor-de-segurança para arquivos de autenticação e o agente verificador-de-estilo para todo o resto",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "auditor-de-seguranca": 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"],
                ),
                "verificador-de-estilo": 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 quey, ClaudeAgentOptions

async def main():
    async for message in quey(
        prompt="Abra https://exemple.com e descreva a estrutra da pagiana",
        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 por 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 pesos abertos econômicos — 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 agentes 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 de sandbox isolada — útil para execução de código agentico onde você não quer que o agente toque no sistema de arquivos do host — Sandbox de Agente Novita fornece um ambiente de execução compatível com E2B projetado para agentes construídos no Claude Agent SDK.

SDK Claude Code em Pipelines CI/CD

As restrições 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 automatizada de código
  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 para 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 as alterações antes que 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 sai antes de concluir Certifique-se de await o loop completo do iterador. O SDK precisa processar todos os eventos de mensagem antes que seu processo termine.

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

Mensagens de subagente não aparecem na saída Filtre por mensagens onde parent_tool_use_id está definido para identificar a saída do subagente separadamente da 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 Claude Code SDK e o Anthropic SDK?

O Claude Agent SDK (anteriormente Claude Code SDK) fornece um agente autônomo que lida com a execução de ferramentas automaticamente. O Anthropic Client SDK fornece acesso bruto à API onde você implementa o loop de ferramentas. Use o Agent SDK para pipelines agenticos; 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 posterior. O pacote não será instalado no Python 3.9 ou anterior.

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 modelos que não são 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 hospede — incluindo modelos de pesos abertos da Kimi, GLM, MiniMax ou Qwen.

Como o Agent SDK é diferente do 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 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 depois de ter um agente funcional.

Artigos Recomendados

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

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

Principais Conclusões

O que é o Claude Code SDK?

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

Instalar o Claude Agent SDK

Passo 1: Configurar Autenticação

Passo 2: Executar Sua Primeira Consulta de Agente

Passo 3: Controlar Permissões com allowedTools

Passo 4: Usar Hooks para Controle do Ciclo de Vida

Passo 5: Retomar Trabalho com Sessões

Passo 6: Delegar Tarefas com Subagentes

Passo 7: Conectar Sistemas Externos via MCP

Usar Novita AI como Backend do Modelo

SDK Claude Code em Pipelines CI/CD

Solução de Problemas

FAQ

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

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

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

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

Como o Agent SDK é diferente do Managed Agents?

O Claude Agent SDK suporta saída em streaming?

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

Qual documentação do anthropic claude agent sdk devo ler primeiro?

Artigos Recomendados

Product

RESOURCES

Partners

Company

Principais Conclusões

O que é o Claude Code SDK?

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

Instalar o Claude Agent SDK

Passo 1: Configurar Autenticação

Passo 2: Executar Sua Primeira Consulta de Agente

Passo 3: Controlar Permissões com allowedTools

Passo 4: Usar Hooks para Controle do Ciclo de Vida

Passo 5: Retomar Trabalho com Sessões

Passo 6: Delegar Tarefas com Subagentes

Passo 7: Conectar Sistemas Externos via MCP

Usar Novita AI como Backend do Modelo

SDK Claude Code em Pipelines CI/CD

Solução de Problemas

FAQ

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

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

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

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

Como o Agent SDK é diferente do Managed Agents?

O Claude Agent SDK suporta saída em streaming?

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

Qual documentação do anthropic claude agent sdk devo ler primeiro?

Artigos Recomendados

Posts relacionados

Product

RESOURCES

Partners

Company