Skip to main content
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 em modo não interativo, passe -p com seu prompt e qualquer opção de CLI:
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: Este exemplo faz uma pergunta ao Claude sobre sua base de código e imprime a resposta:

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:
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: 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. Amazon Bedrock, Google Cloud’s Agent Platform e Microsoft Foundry usam suas credenciais de provedor usuais.
--bare é o modo recomendado para chamadas com script e SDK, e se tornará o padrão para -p em uma versão futura.

Tarefas em segundo plano ao sair

Se Claude iniciar uma tarefa Bash em segundo plano durante uma execução de claude -p, por exemplo um servidor de desenvolvimento ou uma compilação de observação, essa tarefa será encerrada cerca de cinco segundos após Claude retornar seu resultado final e stdin ter sido fechado. O período de carência permite que uma tarefa que termina logo após o resultado ainda entregue sua saída. Antes da v2.1.163, um processo em segundo plano que nunca sairia manteria a invocação de claude -p aberta indefinidamente. Subagentos em segundo plano e fluxos de trabalho estão isentos do período de carência de cinco segundos porque seu resultado faz parte da saída final, então claude -p aguarda sua conclusão. A partir da v2.1.182, essa espera é limitada a dez minutos por padrão para que um agente em segundo plano travado não possa manter o processo aberto indefinidamente. Ajuste o limite com CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, ou defina-o como 0 para aguardar sem limite.

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.

Canalizar dados através do Claude

O modo não interativo lê stdin, então você pode canalizar dados e redirecionar a resposta como qualquer outra ferramenta de linha de comando. Este exemplo canaliza um log de compilação para Claude e escreve a explicação em um arquivo:
Com --output-format json, a carga de resposta inclui total_cost_usd e um detalhamento de custo por modelo, para que os chamadores com script possam rastrear gastos por invocação sem consultar o painel de uso.
A partir do Claude Code v2.1.128, stdin canalizado é limitado a 10MB. Se você exceder o limite, Claude Code sai com um erro claro e um status diferente de zero. Para trabalhar com entradas maiores, escreva o conteúdo em um arquivo e faça referência ao caminho do arquivo em seu prompt em vez de canalizá-lo.

Adicionar Claude a um script de compilação

Você pode envolver uma chamada não interativa em um script para usar Claude como um linter ou revisor específico do projeto. Este script package.json canaliza o diff contra main para Claude e pede que ele relate erros de digitação. Canalizar o diff significa que Claude não precisa de permissão Bash para lê-lo, e as aspas duplas escapadas mantêm o script portável para Windows:

Obter saída estruturada

Use --output-format para controlar como as respostas são retornadas:
  • text (padrão): saída de texto simples
  • json: JSON estruturado com resultado, ID de sessão e metadados
  • stream-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:
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:
Se o valor não for um JSON Schema válido, claude sai com Error: --json-schema is not a valid JSON Schema seguido pelo diagnóstico do validador. Claude Code aceita esquemas que usam a palavra-chave format, como "format": "email", mas trata format como uma anotação e não a impõe. Antes da v2.1.205, Claude Code ignorava silenciosamente um esquema inválido e retornava texto não estruturado, e tratava qualquer esquema contendo format como inválido.
Use uma ferramenta como jq para analisar a resposta e extrair campos específicos:

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:
A última linha do stream é uma mensagem result com o texto de resposta final, custo e metadados de sessão. Antes da v2.1.208, canalizar uma resposta grande poderia truncar a linha final e omitir a mensagem result. 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:
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. 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 eventos de inicialização o precedam: O evento também carrega uma matriz capabilities opcional de strings nomeando os comportamentos do protocolo que esta versão do Claude Code implementa, como interrupt_receipt_v1. Verifique-a para detectar recursos em vez de comparar strings de versão, e ignore valores que você não reconheça. O campo requer Claude Code v2.1.205 ou posterior e está ausente em versões anteriores. Consulte SDKSystemMessage para a lista de capacidades. Use os campos de plugin para falhar CI quando um plugin não foi carregado: 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. 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:
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. AskUserQuestion, ferramentas de conector que sua organização definiu como ask, e ferramentas MCP marcadas requiresUserInteraction são negadas mesmo quando uma regra de permissão corresponde. 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:

Criar um commit

Este exemplo revisa as alterações preparadas e cria um commit com uma mensagem apropriada:
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.
Skills invocadas pelo usuário e comandos personalizados funcionam no modo -p: inclua /skill-name na string de prompt e Claude Code o expande antes de executar. Comandos integrados que abrem um diálogo interativo, como /login, não estão disponíveis no modo -p. /model, /effort, /fast, /color e /rename aceitam o valor como um argumento, por exemplo /model sonnet, e /mcp sem argumento imprime um resumo de texto do status do servidor; essas formas requerem Claude Code v2.1.205 ou posterior e seguem as notas de disponibilidade de cada comando](/pt/commands#all-commands). Para alterar uma configuração de uma invocação -p, passe key=value para /config, por exemplo /config thinking=false.

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:
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:
Se você estiver executando várias conversas, capture o ID da sessão para retomar uma específica:
Execute ambos os comandos do mesmo diretório: a busca de ID de sessão é limitada ao diretório do projeto atual e seus git worktrees. Consulte Resume a session para as regras de escopo completas.

Próximas etapas