Skip to main content

Panoramica

Claude Agent SDK supporta due modalità di input distinte per interagire con gli agenti:
  • Modalità Streaming Input: una sessione persistente e interattiva
  • Single Message Input: query una tantum che utilizzano lo stato della sessione e la ripresa
La modalità streaming input è il modo preferito per utilizzare Claude Agent SDK. Fornisce accesso completo alle capacità dell’agente e consente esperienze ricche e interattive. Consente all’agente di operare come un processo di lunga durata che accetta input dell’utente, gestisce interruzioni, visualizza richieste di autorizzazione e gestisce la gestione della sessione.

Vantaggi

In modalità streaming input, lavorate in una sessione persistente con queste capacità:
  • Caricamenti di immagini: allegate immagini direttamente ai messaggi per l’analisi visiva e la comprensione
  • Messaggi in coda: inviate più messaggi che vengono elaborati sequenzialmente, con la possibilità di interrompere
  • Integrazione tool: accesso completo a tutti i tool e ai server MCP personalizzati durante la sessione
  • Feedback in tempo reale: vedete le risposte mentre vengono generate, non solo i risultati finali
  • Persistenza del contesto: mantenete il contesto della conversazione su più turni naturalmente

Esempio di Implementazione

Questi esempi leggono un’immagine denominata diagram.png dalla directory di lavoro. Createne una lì per prima, oppure cambiate il nome del file per puntare alla vostra immagine.
Quando eseguite l’esempio, la versione TypeScript stampa ogni risposta al completamento. Il ciclo receive_response() della versione Python termina al primo messaggio di risultato, quindi stampa l’analisi di sicurezza; per leggere entrambe le risposte, utilizzate una coppia query() e receive_response() per messaggio come mostrato nell’esempio di continuazione di una conversazione del riferimento Python. Se il source di un blocco immagine manca o non è un oggetto, l’SDK non segnala alcun errore. Claude Code invia a Claude una nota testuale al posto dell’immagine, come [Image could not be processed: image block has no source object], e la sessione continua.
In TypeScript SDK, se il vostro generatore di messaggi genera un’eccezione, ad esempio quando un file che legge è mancante, il flusso termina con un errore che recita Claude Code process aborted by user invece dell’errore originale, quindi controllate il codice all’interno del vostro generatore per primo quando vedete quel messaggio. L’errore potrebbe anche essere preceduto da una lunga riga minificata del codice sorgente SDK raggruppato, quindi leggete fino alla fine dell’output per il testo dell’errore.In Python SDK, un’eccezione del generatore viene registrata a livello di debug e la sessione si blocca senza sollevare, quindi se una sessione di streaming si blocca senza output, abilitate la registrazione di debug e controllate il vostro generatore.

Single Message Input

Single message input è più semplice ma più limitato.

Quando Utilizzare Single Message Input

Utilizzate single message input quando:
  • Avete bisogno di una risposta una tantum
  • Non avete bisogno di allegati di immagini o metodi di controllo mid-session
  • Dovete operare in un ambiente senza stato, come una funzione lambda

Limitazioni

La modalità single message input non supporta:
  • Allegati di immagini diretti nei messaggi
  • Accodamento dinamico dei messaggi
  • Interruzione in tempo reale
  • Conversazioni multi-turno naturali
Se una query termina con un risultato di errore, come error_max_turns, una singola chiamata query() genera un errore che include il testo dell’errore dopo aver restituito il messaggio di risultato finale, quindi avvolgete il ciclo in un blocco try se il vostro codice deve continuare. Consultate Gestire il risultato per i sottotipi di risultato.

Esempio di Implementazione

Quando eseguite l’esempio, ogni query stampa il testo del risultato finale: prima la spiegazione dell’autenticazione, poi la spiegazione dell’autorizzazione.