Vai al contenuto principale
L’Agent SDK ti fornisce gli stessi strumenti, il ciclo dell’agente e la gestione del contesto che alimentano Claude Code. È disponibile come CLI per script e CI/CD, oppure come pacchetti Python e TypeScript per il controllo programmatico completo.
La CLI era precedentemente chiamata “headless mode”. Il flag -p e tutte le opzioni CLI funzionano allo stesso modo.
Per eseguire Claude Code a livello programmatico dalla CLI, passa -p con il tuo prompt e qualsiasi opzione CLI: 
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
Questa pagina copre l’utilizzo dell’Agent SDK tramite la CLI (claude -p). Per i pacchetti SDK Python e TypeScript con output strutturati, callback di approvazione degli strumenti e oggetti messaggio nativi, consulta la documentazione completa dell’Agent SDK.

​
Utilizzo di base

Aggiungi il flag -p (o --print) a qualsiasi comando claude per eseguirlo in modo non interattivo. Tutte le opzioni CLI funzionano con -p, incluse: Questo esempio chiede a Claude una domanda sulla tua base di codice e stampa la risposta: 
claude -p "What does the auth module do?"

​
Esempi

Questi esempi evidenziano i modelli CLI comuni.

​
Ottenere output strutturato

Utilizza --output-format per controllare come vengono restituite le risposte:
  • text (predefinito): output di testo semplice
  • json: JSON strutturato con risultato, ID sessione e metadati
  • stream-json: JSON delimitato da newline per lo streaming in tempo reale
Questo esempio restituisce un riepilogo del progetto come JSON con metadati della sessione, con il risultato del testo nel campo result: 
claude -p "Summarize this project" --output-format json
Per ottenere output conforme a uno schema specifico, utilizza --output-format json con --json-schema e una definizione JSON Schema. La risposta include metadati sulla richiesta (ID sessione, utilizzo, ecc.) con l’output strutturato nel campo structured_output. Questo esempio estrae i nomi delle funzioni e li restituisce come array di stringhe: 
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"]}'
Utilizza uno strumento come jq per analizzare la risposta ed estrarre campi specifici:
# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

# Extract structured output
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

​
Streaming delle risposte

Utilizza --output-format stream-json con --verbose e --include-partial-messages per ricevere i token mentre vengono generati. Ogni riga è un oggetto JSON che rappresenta un evento: 
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
L’esempio seguente utilizza jq per filtrare i delta di testo e visualizzare solo il testo in streaming. Il flag -r restituisce stringhe non elaborate (senza virgolette) e -j si unisce senza newline in modo che i token fluiscano 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'
Per lo streaming programmatico con callback e oggetti messaggio, consulta Stream responses in real-time nella documentazione dell’Agent SDK.

​
Approvare automaticamente gli strumenti

Utilizza --allowedTools per consentire a Claude di utilizzare determinati strumenti senza chiedere. Questo esempio esegue una suite di test e corregge i guasti, consentendo a Claude di eseguire comandi Bash e leggere/modificare file senza chiedere il permesso: 
claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

​
Creare un commit

Questo esempio esamina le modifiche in staging e crea un commit con un messaggio appropriato: 
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 *)"
Il flag --allowedTools utilizza la sintassi delle regole di autorizzazione. Lo spazio finale * abilita la corrispondenza dei prefissi, quindi Bash(git diff *) consente qualsiasi comando che inizia con git diff. Lo spazio prima di * è importante: senza di esso, Bash(git diff*) corrisponderebbe anche a git diff-index.
Le skills richiamate dall’utente come /commit e i comandi incorporati sono disponibili solo in modalità interattiva. In modalità -p, descrivi invece l’attività che desideri completare.

​
Personalizzare il prompt di sistema

Utilizza --append-system-prompt per aggiungere istruzioni mantenendo il comportamento predefinito di Claude Code. Questo esempio invia un diff PR a Claude e gli istruisce di esaminarlo per vulnerabilità di sicurezza: 
gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json
Consulta i flag del prompt di sistema per ulteriori opzioni incluso --system-prompt per sostituire completamente il prompt predefinito.

​
Continuare le conversazioni

Utilizza --continue per continuare la conversazione più recente, oppure --resume con un ID sessione per continuare una conversazione specifica. Questo esempio esegue una revisione, quindi invia prompt di follow-up: 
# 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 stai eseguendo più conversazioni, acquisisci l’ID sessione per riprendere una specifica: 
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

​
Passaggi successivi