Claude Code SDK
Construa agentes de IA personalizados com o Claude Code SDK
Por que usar o Claude Code SDK?
O Claude Code SDK fornece todos os blocos de construção necessários para criar agentes prontos para produção:
- Integração otimizada com Claude: Cache automático de prompts e otimizações de desempenho
- Ecossistema rico de ferramentas: Operações de arquivo, execução de código, busca na web e extensibilidade MCP
- Permissões avançadas: Controle refinado sobre as capacidades do agente
- Essenciais para produção: Tratamento de erros integrado, gerenciamento de sessão e monitoramento
O que você pode construir com o SDK?
Aqui estão alguns tipos de agentes de exemplo que você pode criar:
Agentes de codificação:
- Agentes SRE que diagnosticam e corrigem problemas de produção
- Bots de revisão de segurança que auditam código em busca de vulnerabilidades
- Assistentes de engenharia de plantão que fazem triagem de incidentes
- Agentes de revisão de código que aplicam estilo e melhores práticas
Agentes de negócios:
- Assistentes jurídicos que revisam contratos e conformidade
- Consultores financeiros que analisam relatórios e previsões
- Agentes de suporte ao cliente que resolvem problemas técnicos
- Assistentes de criação de conteúdo para equipes de marketing
O SDK está atualmente disponível em TypeScript e Python, com uma interface de linha de comando (CLI) para prototipagem rápida.
Início rápido
Tenha seu primeiro agente funcionando em menos de 5 minutos:
Instalar o SDK
Instale @anthropic-ai/claude-code
do NPM:
Instale @anthropic-ai/claude-code
do NPM:
Instale @anthropic-ai/claude-code
do NPM:
Instale claude-code-sdk
do PyPI e @anthropic-ai/claude-code
do NPM:
(Opcional) Instale IPython para desenvolvimento interativo:
Definir sua chave de API
Obtenha sua chave de API do Console Anthropic e defina a variável de ambiente ANTHROPIC_API_KEY
:
Criar seu primeiro agente
Crie um destes agentes de exemplo:
Executar o agente
Copie e cole o comando acima diretamente no seu terminal.
Copie e cole o comando acima diretamente no seu terminal.
- Configurar projeto:
-
Adicione
"type": "module"
ao seu package.json -
Salve o código acima como
legal-agent.ts
, depois execute:
Salve o código acima como legal-agent.py
, depois execute:
Para notebooks IPython/Jupyter, você pode executar o código diretamente em uma célula:
Cada exemplo acima cria um agente funcional que irá:
- Analisar o prompt usando as capacidades de raciocínio do Claude
- Planejar uma abordagem de múltiplas etapas para resolver o problema
- Executar ações usando ferramentas como operações de arquivo, comandos bash e busca na web
- Fornecer recomendações acionáveis baseadas na análise
Uso principal
Visão geral
O Claude Code SDK permite que você faça interface com o Claude Code em modo não interativo a partir de suas aplicações.
Pré-requisitos
- Node.js 18+
@anthropic-ai/claude-code
do NPM
Uso básico
A interface principal de linha de comando para o Claude Code é o comando claude
. Use a flag --print
(ou -p
) para executar em modo não interativo e imprimir o resultado final:
Configuração
O SDK aproveita todas as opções CLI disponíveis no Claude Code. Aqui estão as principais para uso do SDK:
Flag | Descrição | Exemplo |
---|---|---|
--print , -p | Executar em modo não interativo | claude -p "consulta" |
--output-format | Especificar formato de saída (text , json , stream-json ) | claude -p --output-format json |
--resume , -r | Retomar uma conversa por ID de sessão | claude --resume abc123 |
--continue , -c | Continuar a conversa mais recente | claude --continue |
--verbose | Habilitar log detalhado | claude --verbose |
--append-system-prompt | Anexar ao prompt do sistema (apenas com --print ) | claude --append-system-prompt "Instrução personalizada" |
--allowedTools | Lista separada por espaços de ferramentas permitidas, ou string de lista separada por vírgulas de ferramentas permitidas | claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem" |
--disallowedTools | Lista separada por espaços de ferramentas negadas, ou string de lista separada por vírgulas de ferramentas negadas | claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github" |
--mcp-config | Carregar servidores MCP de um arquivo JSON | claude --mcp-config servers.json |
--permission-prompt-tool | Ferramenta MCP para lidar com prompts de permissão (apenas com --print ) | claude --permission-prompt-tool mcp__auth__prompt |
Para uma lista completa de opções CLI e recursos, consulte a documentação de referência CLI.
Pré-requisitos
- Node.js 18+
@anthropic-ai/claude-code
do NPM
Uso básico
A interface principal de linha de comando para o Claude Code é o comando claude
. Use a flag --print
(ou -p
) para executar em modo não interativo e imprimir o resultado final:
Configuração
O SDK aproveita todas as opções CLI disponíveis no Claude Code. Aqui estão as principais para uso do SDK:
Flag | Descrição | Exemplo |
---|---|---|
--print , -p | Executar em modo não interativo | claude -p "consulta" |
--output-format | Especificar formato de saída (text , json , stream-json ) | claude -p --output-format json |
--resume , -r | Retomar uma conversa por ID de sessão | claude --resume abc123 |
--continue , -c | Continuar a conversa mais recente | claude --continue |
--verbose | Habilitar log detalhado | claude --verbose |
--append-system-prompt | Anexar ao prompt do sistema (apenas com --print ) | claude --append-system-prompt "Instrução personalizada" |
--allowedTools | Lista separada por espaços de ferramentas permitidas, ou string de lista separada por vírgulas de ferramentas permitidas | claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem" |
--disallowedTools | Lista separada por espaços de ferramentas negadas, ou string de lista separada por vírgulas de ferramentas negadas | claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github" |
--mcp-config | Carregar servidores MCP de um arquivo JSON | claude --mcp-config servers.json |
--permission-prompt-tool | Ferramenta MCP para lidar com prompts de permissão (apenas com --print ) | claude --permission-prompt-tool mcp__auth__prompt |
Para uma lista completa de opções CLI e recursos, consulte a documentação de referência CLI.
Pré-requisitos
- Node.js 18+
@anthropic-ai/claude-code
do NPM
Para visualizar o código-fonte do SDK TypeScript, visite a página @anthropic-ai/claude-code
no NPM.
Uso básico
A interface principal via SDK TypeScript é a função query
, que retorna um iterador assíncrono que transmite mensagens conforme chegam:
Configuração
O SDK TypeScript aceita todos os argumentos suportados pela linha de comando, bem como as seguintes opções adicionais:
Argumento | Descrição | Padrão |
---|---|---|
abortController | Controlador de aborto | new AbortController() |
cwd | Diretório de trabalho atual | process.cwd() |
executable | Qual runtime JavaScript usar | node quando executando com Node.js, bun quando executando com Bun |
executableArgs | Argumentos para passar ao executável | [] |
pathToClaudeCodeExecutable | Caminho para o executável Claude Code | Executável que vem com @anthropic-ai/claude-code |
permissionMode | Modo de permissão para a sessão | "default" (opções: "default" , "acceptEdits" , "plan" , "bypassPermissions" ) |
Pré-requisitos
- Python 3.10+
claude-code-sdk
do PyPI- Node.js 18+
@anthropic-ai/claude-code
do NPM
Para visualizar o código-fonte do SDK Python, consulte o repositório claude-code-sdk
.
Para desenvolvimento interativo, use IPython: pip install ipython
Uso básico
O SDK Python fornece duas interfaces principais:
- A classe
ClaudeSDKClient
(Recomendada)
Melhor para transmitir respostas, conversas de múltiplas rodadas e aplicações interativas:
O SDK também suporta passar mensagens estruturadas e entradas de imagem:
Os exemplos Python nesta página usam asyncio
, mas você também pode usar anyio
.
- A função
query
Para consultas simples e únicas:
Configuração
Como o SDK Python aceita todos os argumentos suportados pela linha de comando através da classe ClaudeCodeOptions
.
Autenticação
Chave de API Anthropic
Para autenticação básica, recupere uma chave de API Anthropic do Console Anthropic e defina a variável de ambiente ANTHROPIC_API_KEY
, conforme demonstrado no Início rápido.
Credenciais de API de terceiros
O SDK também suporta autenticação via provedores de API de terceiros:
- Amazon Bedrock: Defina a variável de ambiente
CLAUDE_CODE_USE_BEDROCK=1
e configure as credenciais AWS - Google Vertex AI: Defina a variável de ambiente
CLAUDE_CODE_USE_VERTEX=1
e configure as credenciais Google Cloud
Para instruções detalhadas de configuração para provedores de terceiros, consulte a documentação do Amazon Bedrock e Google Vertex AI.
Conversas de múltiplas rodadas
Para conversas de múltiplas rodadas, você pode retomar conversas ou continuar da sessão mais recente:
Usando Modo de Planejamento
O Modo de Planejamento permite que o Claude analise código sem fazer modificações, útil para revisões de código e planejamento de mudanças.
O Modo de Planejamento restringe edição, criação de arquivos e execução de comandos. Consulte modos de permissão para detalhes.
Prompts de sistema personalizados
Prompts de sistema definem o papel, expertise e comportamento do seu agente. É aqui que você especifica que tipo de agente está construindo:
Uso Avançado
Ferramentas personalizadas via MCP
O Model Context Protocol (MCP) permite que você dê aos seus agentes ferramentas e capacidades personalizadas. Isso é crucial para construir agentes especializados que precisam de integrações específicas de domínio.
Configurações de ferramentas de agente de exemplo:
Exemplos de uso:
Ao usar ferramentas MCP, você deve explicitamente permiti-las usando a flag --allowedTools
. Nomes de ferramentas MCP seguem o padrão mcp__<serverName>__<toolName>
onde:
serverName
é a chave do seu arquivo de configuração MCPtoolName
é a ferramenta específica fornecida por esse servidor
Esta medida de segurança garante que ferramentas MCP sejam usadas apenas quando explicitamente permitidas.
Se você especificar apenas o nome do servidor (ou seja, mcp__<serverName>
), todas as ferramentas desse servidor serão permitidas.
Padrões glob (por exemplo, mcp__go*
) não são suportados.
Ferramenta de prompt de permissão personalizada
Opcionalmente, use --permission-prompt-tool
para passar uma ferramenta MCP que usaremos para verificar se o usuário concede ou não permissões ao modelo para invocar uma determinada ferramenta. Quando o modelo invoca uma ferramenta, acontece o seguinte:
- Primeiro verificamos configurações de permissão: todos os arquivos settings.json, bem como
--allowedTools
e--disallowedTools
passados para o SDK; se uma dessas permite ou nega a chamada da ferramenta, prosseguimos com a chamada da ferramenta - Caso contrário, invocamos a ferramenta MCP que você forneceu em
--permission-prompt-tool
A ferramenta MCP --permission-prompt-tool
recebe o nome da ferramenta e entrada, e deve retornar um payload JSON-stringified com o resultado. O payload deve ser um dos seguintes:
Exemplos de implementação:
Notas de uso:
- Use
updatedInput
para dizer ao modelo que o prompt de permissão mutou sua entrada; caso contrário, definaupdatedInput
para a entrada original, como no exemplo acima. Por exemplo, se a ferramenta mostra um diff de edição de arquivo para o usuário e permite que eles editem o diff manualmente, a ferramenta de prompt de permissão deve retornar essa edição atualizada. - O payload deve ser JSON-stringified
Formatos de saída
O SDK suporta múltiplos formatos de saída:
Saída de texto (padrão)
Saída JSON
Retorna dados estruturados incluindo metadados:
Formato de resposta:
Saída JSON de transmissão
Transmite cada mensagem conforme é recebida:
Cada conversa começa com uma mensagem inicial do sistema init
, seguida por uma lista de mensagens do usuário e assistente, seguida por uma mensagem final do sistema result
com estatísticas. Cada mensagem é emitida como um objeto JSON separado.
Esquema de mensagem
Mensagens retornadas da API JSON são estritamente tipadas de acordo com o seguinte esquema:
Em breve publicaremos esses tipos em um formato compatível com JSONSchema. Usamos versionamento semântico para o pacote principal Claude Code para comunicar mudanças que quebram compatibilidade neste formato.
Os tipos Message
e MessageParam
estão disponíveis nos SDKs Anthropic. Por exemplo, consulte os SDKs Anthropic TypeScript e Python.
Formatos de entrada
O SDK suporta múltiplos formatos de entrada:
Entrada de texto (padrão)
Entrada JSON de transmissão
Um fluxo de mensagens fornecido via stdin
onde cada mensagem representa uma rodada do usuário. Isso permite múltiplas rodadas de uma conversa sem relançar o binário claude
e permite fornecer orientação ao modelo enquanto ele está processando uma solicitação.
Cada mensagem é um objeto JSON ‘Mensagem do usuário’, seguindo o mesmo formato que o esquema de mensagem de saída. Mensagens são formatadas usando o formato jsonl onde cada linha de entrada é um objeto JSON completo. Entrada JSON de transmissão requer -p
e --output-format stream-json
.
Atualmente isso é limitado a mensagens de usuário apenas de texto.
Exemplos de integração de agentes
Bot de resposta a incidentes SRE
Revisão de segurança automatizada
Assistente jurídico de múltiplas rodadas
Melhores Práticas Específicas do Python
Padrões Principais
Dicas IPython/Jupyter
Melhores práticas
-
Use formato de saída JSON para análise programática de respostas:
-
Trate erros graciosamente - verifique códigos de saída e stderr:
-
Use gerenciamento de sessão para manter contexto em conversas de múltiplas rodadas
-
Considere timeouts para operações de longa duração:
-
Respeite limites de taxa ao fazer múltiplas solicitações adicionando atrasos entre chamadas
Recursos relacionados
- Uso e controles CLI - Documentação completa da CLI
- Integração GitHub Actions - Automatize seu fluxo de trabalho GitHub com Claude
- Fluxos de trabalho comuns - Guias passo a passo para casos de uso comuns