Modo headless e Agent SDK

Rode o Claude automaticamente em scripts e pipelines de CI/CD

⏱ Estim. ~6 min

01 · Ler

Tudo que você fez com o Claude Code até agora foi interativo — você digita, o Claude responde, você aprova. Mas e se quiser que o Claude rode sozinho? Num pipeline de CI/CD revisando cada pull request? Num script que conserta erros de lint toda noite?

Modo headless (claude -p) roda o Claude sem terminal interativo. Você passa um prompt, ele faz o trabalho e devolve o resultado. Sem digitação, sem diálogos de aprovação — só entrada e saída.

É assim que times integram o Claude em fluxos automatizados: bots de code review, corretores de teste, geradores de documentação e muito mais.

💡 Imagine assimO Claude interativo é como conversar com uma pessoa colega na sua mesa. O Claude headless é como mandar a tarefa por e-mail — você envia o pedido, ela executa, você recebe o resultado de volta. Sem ida e volta.

Pontos-chave

claude -p roda o Claude de forma não interativa (modo headless)
Perfeito para scripts, pipelines de CI/CD e automação
Sem diálogos de aprovação — você especifica antes quais ferramentas são permitidas
A saída pode ser texto, JSON ou JSON em streaming

02 · Exemplo de código

Abaixo estão padrões comuns de modo headless. A flag -p é o que torna o modo não interativo.

Uso básico do modo headless

# Simple query
claude -p "Find all TODO comments in this project"

# With allowed tools (auto-approved, no prompts)
claude -p "Run tests and fix failures" \
  --allowedTools "Bash(npm test*),Read,Edit"

# Structured JSON output
claude -p "List all API endpoints" \
  --output-format json

A flag -p (abreviação de 'print') roda o Claude de forma não interativa. --allowedTools pré-aprova ferramentas específicas para o Claude conseguir trabalhar sem prompts de permission. --output-format json devolve dados estruturados em vez de texto puro — útil quando outro programa precisa fazer parse do resultado.

03 · Exemplo de código

Abaixo está como os times usam modo headless em pipelines de CI/CD — um code reviewer automático que roda em cada pull request.

GitHub Actions — code review automático

# .github/workflows/claude-review.yml
name: Claude Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Review PR
        run: |
          claude -p "Review the changes in this PR. \
            Focus on bugs, security, and performance." \
            --allowedTools "Read,Grep,Glob" \
            --output-format text

Esse GitHub Action roda o Claude em modo headless em cada pull request. Só permite ferramentas read-only (Read, Grep, Glob), então o Claude consegue analisar código mas não pode mudar nada. A saída da review aparece no log do CI para o time ler.

04 · Ler

Para automações mais sofisticadas, a Anthropic oferece o Agent SDK — bibliotecas em Python e TypeScript para construir agents de produção com o suporte de ferramentas do Claude.

O Agent SDK te dá controle programático sobre tudo: quais ferramentas estão disponíveis, como lidar com resultados, gerenciamento de session (retomar conversas) e até conexões com servidores MCP. É o que sustenta as integrações mais sofisticadas com o Claude Code.

A CLI (claude -p) é boa para automação simples. O Agent SDK é para quando você quer controle programático total — tratamento de erro customizado, resultados em streaming, encadear várias chamadas do Claude ou construir um produto em cima das capacidades do Claude.

Pontos-chave

Agent SDK: bibliotecas em Python e TypeScript para agents de produção
Controle programático total sobre ferramentas, sessions e resultados
CLI (claude -p): automação simples e scripts
Agent SDK: aplicações complexas e sistemas de produção
Gerenciamento de session: capturar e retomar conversas via código

05 · Exemplo de código

Abaixo está um exemplo simples do Agent SDK em TypeScript que encontra e conserta bugs via código.

Agent SDK — bug fixer

import { query } from '@anthropic-ai/claude-agent-sdk';

for await (const msg of query({
  prompt: "Find and fix the failing test in auth.test.ts",
  options: {
    allowedTools: ["Read", "Edit", "Bash"],
  }
})) {
  if (msg.result) {
    console.log('Fix applied:', msg.result);
  }
}

O Agent SDK te dá uma interface em streaming — você itera pelas mensagens enquanto o Claude trabalha. O array allowedTools controla o que o Claude pode fazer. Quando o Claude termina, a mensagem de resultado traz um resumo do que foi feito. É assim que você constrói agents automáticos que leem, editam e rodam comandos.

06 · Quiz

Qual flag faz o Claude Code rodar de forma não interativa, sem terminal interativo?

claude --headless
claude --auto
claude -p
claude --batch

07 · Preencher

Para rodar o Claude num pipeline de CI/CD sem interação de usuário, use claude _____ "seu prompt".

08 · Combinar

Combine cada método de automação com o melhor uso.

(Esta seção é interativa — ative o JavaScript para usar.)

Outras lições deste capítulo

⚠ A experiência interativa completa precisa de JavaScript. Ative-o e recarregue a página.

※ Este é um projeto educacional independente — não é um produto oficial da Anthropic. Claude™ é uma marca registrada da Anthropic, PBC.