SDK
Integre programaticamente o Claude Code em suas aplicações usando o SDK.
O SDK do Claude Code permite que desenvolvedores integrem programaticamente o Claude Code em suas aplicações. Ele possibilita executar o Claude Code como um subprocesso, fornecendo uma maneira de construir assistentes de codificação e ferramentas com IA que aproveitam as capacidades do Claude.
O SDK está disponível para uso em linha de comando, TypeScript e Python.
Autenticação
Para usar o SDK do Claude Code, recomendamos criar uma chave de API dedicada:
- Crie uma chave de API Anthropic no Console Anthropic
- Em seguida, defina a variável de ambiente
ANTHROPIC_API_KEY
. Recomendamos armazenar esta chave de forma segura (por exemplo, usando um secret do Github)
Uso básico do SDK
O SDK do Claude Code permite que você use o Claude Code no modo não interativo a partir de suas aplicações.
Linha de comando
Aqui estão alguns exemplos básicos para o SDK de linha de comando:
TypeScript
O SDK TypeScript está incluído no pacote principal @anthropic-ai/claude-code
no NPM:
O SDK TypeScript aceita todos os argumentos suportados pelo SDK de linha de comando, bem como:
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 |
Python
O SDK Python está disponível como claude-code-sdk
no PyPI:
Pré-requisitos:
- Python 3.10+
- Node.js
- CLI do Claude Code:
npm install -g @anthropic-ai/claude-code
Uso básico:
O SDK Python aceita todos os argumentos suportados pelo SDK de linha de comando através da classe ClaudeCodeOptions
:
Uso avançado
A documentação abaixo usa o SDK de linha de comando como exemplo, mas também pode ser usada com os SDKs TypeScript e Python.
Conversas de múltiplos turnos
Para conversas de múltiplos turnos, você pode retomar conversas ou continuar a partir da sessão mais recente:
Prompts de sistema personalizados
Você pode fornecer prompts de sistema personalizados para orientar o comportamento do Claude:
Você também pode anexar instruções ao prompt de sistema padrão:
Configuração MCP
O Model Context Protocol (MCP) permite que você estenda o Claude Code com ferramentas e recursos adicionais de servidores externos. Usando a flag --mcp-config
, você pode carregar servidores MCP que fornecem capacidades especializadas como acesso a banco de dados, integrações de API ou ferramentas personalizadas.
Crie um arquivo de configuração JSON com seus servidores MCP:
Em seguida, use-o com o Claude Code:
Ao usar ferramentas MCP, você deve permitir explicitamente seu uso com a flag --allowedTools
. Os nomes das 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 as 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 ao modelo permissões para invocar uma determinada ferramenta. Quando o modelo invoca uma ferramenta, o seguinte acontece:
- Primeiro verificamos as configurações de permissão: todos os arquivos settings.json, bem como
--allowedTools
e--disallowedTools
passados para o SDK; se uma dessas configurações permitir ou negar 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 a entrada, e deve retornar uma carga útil JSON-stringified com o resultado. A carga útil deve ser uma das seguintes:
Por exemplo, uma implementação de ferramenta de prompt de permissão MCP em TypeScript pode ser assim:
Para usar esta ferramenta, adicione seu servidor MCP (por exemplo, com --mcp-config
), então invoque o SDK assim:
Notas de uso:
- Use
updatedInput
para informar ao modelo que o prompt de permissão modificou sua entrada; caso contrário, definaupdatedInput
para a entrada original, como no exemplo acima. Por exemplo, se a ferramenta mostrar um diff de edição de arquivo ao usuário e permitir que eles editem o diff manualmente, a ferramenta de prompt de permissão deve retornar essa edição atualizada. - A carga útil deve ser JSON-stringified
Opções de CLI disponíveis
O SDK aproveita todas as opções de 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 pelo ID da sessão | claude --resume abc123 |
--continue , -c | Continuar a conversa mais recente | claude --continue |
--verbose | Ativar registro detalhado | claude --verbose |
--max-turns | Limitar turnos agênticos no modo não interativo | claude --max-turns 3 |
--system-prompt | Substituir o prompt do sistema (apenas com --print ) | claude --system-prompt "Instrução personalizada" |
--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 e recursos da CLI, consulte a documentação Uso da CLI.
Formatos de saída
O SDK suporta múltiplos formatos de saída:
Saída de texto (padrão)
Retorna apenas o texto da resposta:
Saída JSON
Retorna dados estruturados incluindo metadados:
Formato de resposta:
Saída JSON em streaming
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 do assistente, seguida por uma mensagem final do sistema result
com estatísticas. Cada mensagem é emitida como um objeto JSON separado.
Esquema de mensagem
As mensagens retornadas pela 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 do Claude Code para comunicar mudanças significativas neste formato.
Os tipos Message
e MessageParam
estão disponíveis nos SDKs da Anthropic. Por exemplo, veja os SDKs da Anthropic TypeScript e Python.
Exemplos
Integração simples de script
Processando arquivos com Claude
Gerenciamento de sessão
Melhores práticas
-
Use o formato de saída JSON para análise programática de respostas:
-
Trate erros com elegância - verifique códigos de saída e stderr:
-
Use gerenciamento de sessão para manter o contexto em conversas de múltiplos turnos
-
Considere timeouts para operações de longa duração:
-
Respeite os limites de taxa ao fazer múltiplas solicitações, adicionando atrasos entre as chamadas
Aplicações do mundo real
O SDK do Claude Code permite integrações poderosas com seu fluxo de trabalho de desenvolvimento. Um exemplo notável são as GitHub Actions do Claude Code, que usam o SDK para fornecer recursos automatizados de revisão de código, criação de PR e triagem de problemas diretamente em seu fluxo de trabalho do GitHub.
Recursos relacionados
- Uso e controles da CLI - Documentação completa da CLI
- Integração com GitHub Actions - Automatize seu fluxo de trabalho do GitHub com Claude
- Tutoriais - Guias passo a passo para casos de uso comuns