Executar Claude Code programaticamente
Use o Agent SDK para executar Claude Code programaticamente a partir da CLI, Python ou TypeScript.
O Agent SDK oferece as mesmas ferramentas, loop de agente e gerenciamento de contexto que alimentam Claude Code. Está disponível como uma CLI para scripts e CI/CD, ou como pacotes Python e TypeScript para controle programático completo.
Para executar Claude Code programaticamente a partir da CLI, passe -p com seu prompt e qualquer opção de CLI:
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
Esta página aborda o uso do Agent SDK via CLI (claude -p). Para os pacotes SDK Python e TypeScript com saídas estruturadas, callbacks de aprovação de ferramentas e objetos de mensagem nativos, consulte a documentação completa do Agent SDK.
Uso básico
Adicione o sinalizador -p (ou --print) a qualquer comando claude para executá-lo de forma não interativa. Todas as opções de CLI funcionam com -p, incluindo:
--continuepara continuar conversas--allowedToolspara aprovar ferramentas automaticamente--output-formatpara saída estruturada
Este exemplo faz uma pergunta ao Claude sobre sua base de código e imprime a resposta:
claude -p "What does the auth module do?"
Comece mais rápido com modo bare
Adicione --bare para reduzir o tempo de inicialização pulando a descoberta automática de hooks, skills, plugins, servidores MCP, memória automática e CLAUDE.md. Sem ele, claude -p carrega o mesmo contexto que uma sessão interativa carregaria, incluindo qualquer coisa configurada no diretório de trabalho ou ~/.claude.
O modo bare é útil para CI e scripts onde você precisa do mesmo resultado em cada máquina. Um hook no ~/.claude de um colega de trabalho ou um servidor MCP no .mcp.json do projeto não serão executados, porque o modo bare nunca os lê. Apenas os sinalizadores que você passa explicitamente têm efeito.
Este exemplo executa uma tarefa de resumo única em modo bare e pré-aprova a ferramenta Read para que a chamada seja concluída sem um prompt de permissão:
claude --bare -p "Summarize this file" --allowedTools "Read"
No modo bare, Claude tem acesso às ferramentas Bash, leitura de arquivo e edição de arquivo. Passe qualquer contexto que você precise com um sinalizador:
| Para carregar | Use |
|---|---|
| Adições de prompt do sistema | --append-system-prompt, --append-system-prompt-file |
| Configurações | --settings <file-or-json> |
| Servidores MCP | --mcp-config <file-or-json> |
| Agentes personalizados | --agents <json> |
| Um diretório de plugin | --plugin-dir <path> |
O modo bare pula leituras de OAuth e keychain. A autenticação do Anthropic deve vir de ANTHROPIC_API_KEY ou um apiKeyHelper no JSON passado para --settings. Bedrock, Vertex e Foundry usam suas credenciais de provedor usuais.
Exemplos
Estes exemplos destacam padrões comuns de CLI. Para CI e outras chamadas com script, adicione --bare para que não captem o que quer que esteja configurado localmente.
Obter saída estruturada
Use --output-format para controlar como as respostas são retornadas:
text(padrão): saída de texto simplesjson: JSON estruturado com resultado, ID de sessão e metadadosstream-json: JSON delimitado por quebra de linha para streaming em tempo real
Este exemplo retorna um resumo do projeto como JSON com metadados de sessão, com o resultado de texto no campo result:
claude -p "Summarize this project" --output-format json
Para obter saída em conformidade com um esquema específico, use --output-format json com --json-schema e uma definição de JSON Schema. A resposta inclui metadados sobre a solicitação (ID de sessão, uso, etc.) com a saída estruturada no campo structured_output.
Este exemplo extrai nomes de funções e os retorna como uma matriz de strings:
claude -p "Extract the main function names from auth.py" \
--output-format json \
--json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
Respostas de stream
Use --output-format stream-json com --verbose e --include-partial-messages para receber tokens conforme são gerados. Cada linha é um objeto JSON representando um evento:
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
O exemplo a seguir usa jq para filtrar deltas de texto e exibir apenas o texto de streaming. O sinalizador -r produz strings brutas (sem aspas) e -j une sem quebras de linha para que os tokens façam streaming continuamente:
claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
Quando uma solicitação de API falha com um erro que pode ser repetido, Claude Code emite um evento system/api_retry antes de tentar novamente. Você pode usar isso para exibir o progresso de repetição ou implementar lógica de backoff personalizada.
| Campo | Tipo | Descrição |
|---|---|---|
type |
"system" |
tipo de mensagem |
subtype |
"api_retry" |
identifica isso como um evento de repetição |
attempt |
inteiro | número da tentativa atual, começando em 1 |
max_retries |
inteiro | total de repetições permitidas |
retry_delay_ms |
inteiro | milissegundos até a próxima tentativa |
error_status |
inteiro ou nulo | código de status HTTP, ou null para erros de conexão sem resposta HTTP |
error |
string | categoria de erro: authentication_failed, oauth_org_not_allowed, billing_error, rate_limit, invalid_request, server_error, max_output_tokens, ou unknown |
uuid |
string | identificador único do evento |
session_id |
string | sessão à qual o evento pertence |
O evento system/init relata metadados de sessão incluindo o modelo, ferramentas, servidores MCP e plugins carregados. É o primeiro evento no stream a menos que CLAUDE_CODE_SYNC_PLUGIN_INSTALL esteja definido, caso em que eventos plugin_install o precedem. Use os campos de plugin para falhar CI quando um plugin não foi carregado:
| Campo | Tipo | Descrição |
|---|---|---|
plugins |
array | plugins que foram carregados com sucesso, cada um com name e path |
plugin_errors |
array | erros de tempo de carregamento de plugin, como uma versão de dependência insatisfeita, cada um com plugin, type e message. Os plugins afetados são rebaixados e ausentes de plugins. A chave é omitida quando não há erros |
Quando CLAUDE_CODE_SYNC_PLUGIN_INSTALL está definido, Claude Code emite eventos system/plugin_install enquanto plugins do marketplace instalam antes da primeira volta. Use estes para exibir o progresso de instalação em sua própria UI.
| Campo | Tipo | Descrição |
|---|---|---|
type |
"system" |
tipo de mensagem |
subtype |
"plugin_install" |
identifica isso como um evento de instalação de plugin |
status |
"started", "installed", "failed", ou "completed" |
started e completed envolvem a instalação geral; installed e failed relatam marketplaces individuais |
name |
string, opcional | nome do marketplace, presente em installed e failed |
error |
string, opcional | mensagem de falha, presente em failed |
uuid |
string | identificador único do evento |
session_id |
string | sessão à qual o evento pertence |
Para streaming programático com callbacks e objetos de mensagem, consulte Stream responses in real-time na documentação do Agent SDK.
Aprovar ferramentas automaticamente
Use --allowedTools para permitir que Claude use certas ferramentas sem solicitar. Este exemplo executa um conjunto de testes e corrige falhas, permitindo que Claude execute comandos Bash e leia/edite arquivos sem pedir permissão:
claude -p "Run the test suite and fix any failures" \
--allowedTools "Bash,Read,Edit"
Para definir uma linha de base para toda a sessão em vez de listar ferramentas individuais, passe um modo de permissão. dontAsk nega qualquer coisa não em suas regras permissions.allow ou no conjunto de comandos somente leitura, o que é útil para execuções de CI bloqueadas. acceptEdits permite que Claude escreva arquivos sem solicitar e também aprova automaticamente comandos comuns do sistema de arquivos, como mkdir, touch, mv e cp. Outros comandos de shell e solicitações de rede ainda precisam de uma entrada --allowedTools ou uma regra permissions.allow, caso contrário a execução é abortada quando uma é tentada:
claude -p "Apply the lint fixes" --permission-mode acceptEdits
Criar um commit
Este exemplo revisa as alterações preparadas e cria um commit com uma mensagem apropriada:
claude -p "Look at my staged changes and create an appropriate commit" \
--allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"
O sinalizador --allowedTools usa sintaxe de regra de permissão. O * à direita habilita correspondência de prefixo, então Bash(git diff *) permite qualquer comando começando com git diff. O espaço antes de * é importante: sem ele, Bash(git diff*) também corresponderia a git diff-index.
Personalizar o prompt do sistema
Use --append-system-prompt para adicionar instruções mantendo o comportamento padrão do Claude Code. Este exemplo envia um diff de PR para Claude e o instrui a revisar vulnerabilidades de segurança:
gh pr diff "$1" | claude -p \
--append-system-prompt "You are a security engineer. Review for vulnerabilities." \
--output-format json
Consulte system prompt flags para mais opções, incluindo --system-prompt para substituir completamente o prompt padrão.
Continuar conversas
Use --continue para continuar a conversa mais recente, ou --resume com um ID de sessão para continuar uma conversa específica. Este exemplo executa uma revisão e depois envia prompts de acompanhamento:
# First request
claude -p "Review this codebase for performance issues"
# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue
Se você estiver executando várias conversas, capture o ID da sessão para retomar uma específica:
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"
Próximas etapas
- Agent SDK quickstart: construa seu primeiro agente com Python ou TypeScript
- CLI reference: todos os sinalizadores e opções de CLI
- GitHub Actions: use o Agent SDK em fluxos de trabalho do GitHub
- GitLab CI/CD: use o Agent SDK em pipelines do GitLab