Modalità headless e Agent SDK

Esegui Claude automaticamente in script e pipeline CI/CD

⏱ Stima ~6 min

01 · Leggi

Tutto ciò che hai fatto finora con Claude Code è interattivo — tu scrivi, Claude risponde, tu approvi. Ma e se volessi che Claude girasse in automatico? In una pipeline CI/CD che revisiona ogni pull request? In uno script che corregge gli errori di lint ogni notte?

La modalità headless (claude -p) esegue Claude senza un terminale interattivo. Gli dai un prompt, fa il suo lavoro e restituisce il risultato. Niente digitazione, niente finestre di approvazione — solo input e output.

È così che i team integrano Claude nei flussi automatizzati: bot per la code review, fixer di test, generatori di documentazione e molto altro.

💡 Immagina cosìClaude in modalità interattiva è come parlare con un collega alla tua scrivania. Claude in modalità headless è come mandargli un task per email — invii la richiesta, lui la esegue e ricevi il risultato. Niente botta e risposta.

Punti chiave

claude -p esegue Claude in modo non interattivo (modalità headless)
Ideale per script, pipeline CI/CD e automazione
Niente finestre di approvazione — specifica in anticipo gli strumenti consentiti
L'output può essere testo, JSON o JSON in streaming

02 · Esempio di codice

Ecco i pattern comuni della modalità headless. Il flag -p la rende non interattiva.

Uso base della modalità 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

Il flag -p (abbreviazione di 'print') fa girare Claude in modo non interattivo. --allowedTools pre-approva strumenti specifici, così Claude può lavorare senza prompt di permission. --output-format json restituisce dati strutturati invece di testo normale — utile quando altri programmi devono fare il parsing del risultato.

03 · Esempio di codice

Ecco come i team usano la modalità headless in una pipeline CI/CD — un code reviewer automatico che gira su ogni pull request.

GitHub Actions — code review automatica

# .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

Questa GitHub Action esegue Claude in modalità headless su ogni pull request. Consente solo strumenti in sola lettura (Read, Grep, Glob), così Claude può analizzare il codice senza modificare nulla. L'output della review appare nei log CI per essere letto dal team.

04 · Leggi

Per automazioni più complesse, Anthropic offre l'Agent SDK — librerie Python e TypeScript per costruire agent in produzione con supporto agli strumenti di Claude.

L'Agent SDK ti dà il pieno controllo programmatico: quali strumenti sono disponibili, come gestire i risultati, la gestione della sessione (riprendere le conversazioni) e persino le connessioni ai server MCP. È il livello che supporta le integrazioni Claude Code più complesse.

La CLI (claude -p) è ideale per automazioni semplici. L'Agent SDK è ciò di cui hai bisogno quando vuoi il pieno controllo programmatico — gestione personalizzata degli errori, risultati in streaming, concatenazione di più chiamate Claude o costruzione di un prodotto sopra le capacità di Claude.

Punti chiave

Agent SDK: librerie Python e TypeScript per agent in produzione
Pieno controllo programmatico su strumenti, sessioni e risultati
CLI (claude -p): automazioni semplici e script
Agent SDK: applicazioni complesse e sistemi in produzione
Gestione della sessione: cattura e riprendi le conversazioni in modo programmatico

05 · Esempio di codice

Ecco un semplice esempio di Agent SDK in TypeScript che trova e corregge bug in modo programmatico.

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);
  }
}

L'Agent SDK ti offre un'interfaccia in streaming — mentre Claude lavora, itieri sui messaggi. L'array allowedTools controlla cosa può fare Claude. Quando Claude finisce, il messaggio result contiene il riassunto di ciò che ha fatto. Questo è il modo per costruire un agent automatico in grado di leggere, modificare ed eseguire comandi.

06 · Quiz

Quale flag fa girare Claude Code in modo non interattivo, senza terminale interattivo?

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

07 · Completa

Per eseguire Claude in una pipeline CI/CD senza interazione dell'utente, usa claude _____ "il tuo prompt".

08 · Abbina

Abbina ogni metodo di automazione al suo utilizzo ottimale.

(Questa sezione è interattiva — attiva JavaScript per usarla.)

Altre lezioni di questo capitolo

⚠ L'esperienza interattiva completa richiede JavaScript. Attivalo e ricarica la pagina.

※ Questo è un progetto educativo indipendente — non è un prodotto ufficiale di Anthropic. Claude™ è un marchio di Anthropic, PBC.