Modalità headless e l'Agent SDK
Claude Code non è solo interattivo. Puoi eseguirlo in modalità headless (non interattiva, scriptabile) e puoi costruire i tuoi agenti sullo stesso harness sottostante con l'Agent SDK.
- Come eseguire un singolo prompt in modo non interattivo e catturarne l'output
- Perché un'esecuzione non presidiata richiede una postura dei permessi deliberata, non quella interattiva predefinita
- Quando hai superato la chiamata singola e dovresti passare all'Agent SDK
- Le tre modalità a confronto, per scegliere in modo deliberato e non per abitudine
Modalità headless
Esegui un singolo prompt in modo non interattivo e cattura l'output — perfetto per script, hook pre-commit e CI:
Rivedi il diff in staging da uno script
claude -p "Review the staged diff and list any bugs as a Markdown checklist"
Convoglia l'input in ingresso, ottieni un risultato in uscita. Combinalo con i permessi impostati su una postura sicura e non interattiva, così non resta mai bloccato in attesa di approvazione — e bloccalo a fondo così un'esecuzione automatizzata non può toccare i segreti (vedi Rendere robuste le esecuzioni autonome).
- Un prompt, una risposta, uscita. Tutto ciò che serve a un'esecuzione headless è un flag, perché non c'è un'interfaccia che ti chieda qualcosa.
- Una sessione interattiva chiede a te; un job di CI non ha nessuno a cui chiedere. Imposta regole di autorizzazione esplicite per gli strumenti di cui il compito ha davvero bisogno, e fai in modo che un prompt senza risposta termini l'esecuzione invece di bloccarla.
- Limita i turni e la spesa, così un ciclo che va storto costa minuti e centesimi invece di ore e dollari.
- Uno script che analizza prosa è uno script che si rompe. Richiedi JSON — o uno schema — così il risultato è leggibile dalla macchina fin dall'origine.
- Segreti, rete e accesso in scrittura sono le tre cose di cui un'esecuzione non presidiata dovrebbe avere il minimo. Vedi Rendere robuste le esecuzioni autonome.
I flag esatti per ogni passaggio — e le insidie che contengono — sono in La CLI claude: i flag che cambiano i risultati. Un uso classico di tutto questo insieme: un job di CI che fa rivedere a Claude ogni pull request — vedi il tutorial sulla revisione delle PR.
L'Agent SDK
Il Claude Agent SDK (Python e TypeScript) ti permette di costruire agenti di produzione sullo stesso ciclo che alimenta Claude Code — uso degli strumenti, accesso a file/shell, permessi, gestione del contesto — ma integrato nella tua applicazione.
Ricorri a esso quando hai superato la singola chiamata API o un ciclo fatto a mano e vuoi un runtime per agenti completo di tutto. Per lo spettro delle opzioni — singola chiamata → workflow → agente personalizzato → gestito — vedi Costruire agenti sull'API.
Headless/SDK contro interattivo
| Modalità | Per |
|---|---|
| Claude Code interattivo | Sviluppo quotidiano con un essere umano nel ciclo |
Headless (claude -p) | Script, pre-commit, esecuzioni una tantum in CI |
| Agent SDK | Agenti di produzione integrati nel tuo software |
Verifica te stesso
Check yourself
0/2- Headless è lo stesso harness senza l'essere umano — quindi tutto ciò che l'umano avrebbe deciso diventa configurazione.
- Restringi i permessi, limita turni e spesa, e chiedi un output strutturato. Tutti e quattro sono flag, non convenzioni.
- Passa all'Agent SDK quando vuoi il ciclo dentro la tua applicazione invece di una chiamata CLI da uno script.
- Un'esecuzione non presidiata è una postura di sicurezza oltre che una funzionalità: rendi robusto ciò che può raggiungere prima di pianificarla.
Avanti
- La CLI claude: i flag che cambiano i risultati — il contratto a cinque flag per un'esecuzione non presidiata
- Una GitHub Action che rivede ogni PR (tutorial)
- Costruire agenti sull'API
- Rendere robuste le esecuzioni autonome