Input in Streaming
Panoramica
Il Claude Agent SDK supporta due modalità di input distinte per interagire con gli agenti:
- Modalità Input in Streaming (Predefinita e Consigliata) - Una sessione persistente e interattiva
- Input Messaggio Singolo - Query one-shot che utilizzano lo stato della sessione e la ripresa
Questa guida spiega le differenze, i vantaggi e i casi d'uso per ciascuna modalità per aiutarti a scegliere l'approccio giusto per la tua applicazione.
Modalità Input in Streaming (Consigliata)
La modalità input in streaming è il modo preferito per utilizzare il Claude Agent SDK. Fornisce accesso completo alle capacità dell'agente e abilita esperienze ricche e interattive.
Consente all'agente di operare come un processo di lunga durata che riceve input dell'utente, gestisce interruzioni, presenta richieste di permesso e gestisce la gestione delle sessioni.
Come Funziona
%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D", "primaryColor": "#F0F0EB", "primaryTextColor": "#191919", "primaryBorderColor": "#D9D8D5", "secondaryColor": "#F5E6D8", "tertiaryColor": "#CC785C", "noteBkgColor": "#FAF0E6", "noteBorderColor": "#91918D"}, "sequence": {"actorMargin": 50, "width": 150, "height": 65, "boxMargin": 10, "boxTextMargin": 5, "noteMargin": 10, "messageMargin": 35}}}%%
sequenceDiagram
participant App as Your Application
participant Agent as Claude Agent
participant Tools as Tools/Hooks
participant FS as Environment/<br/>File System
App->>Agent: Initialize with AsyncGenerator
activate Agent
App->>Agent: Yield Message 1
Agent->>Tools: Execute tools
Tools->>FS: Read files
FS-->>Tools: File contents
Tools->>FS: Write/Edit files
FS-->>Tools: Success/Error
Agent-->>App: Stream partial response
Agent-->>App: Stream more content...
Agent->>App: Complete Message 1
App->>Agent: Yield Message 2 + Image
Agent->>Tools: Process image & execute
Tools->>FS: Access filesystem
FS-->>Tools: Operation results
Agent-->>App: Stream response 2
App->>Agent: Queue Message 3
App->>Agent: Interrupt/Cancel
Agent->>App: Handle interruption
Note over App,Agent: Session stays alive
Note over Tools,FS: Persistent file system<br/>state maintained
deactivate AgentVantaggi
Caricamento Immagini
Allega immagini direttamente ai messaggi per analisi visiva e comprensione
Messaggi in Coda
Invia più messaggi che si elaborano sequenzialmente, con possibilità di interrompere
Integrazione Strumenti
Accesso completo a tutti gli strumenti e server MCP personalizzati durante la sessione
Supporto Hook
Utilizza hook del ciclo di vita per personalizzare il comportamento in vari punti
Feedback in Tempo Reale
Vedi le risposte mentre vengono generate, non solo i risultati finali
Persistenza del Contesto
Mantieni il contesto della conversazione attraverso più turni naturalmente
Esempio di Implementazione
import { query } from "@anthropic-ai/claude-agent-sdk";
import { readFileSync } from "fs";
async function* generateMessages() {
// Primo messaggio
yield {
type: "user" as const,
message: {
role: "user" as const,
content: "Analizza questo codebase per problemi di sicurezza"
}
};
// Aspetta condizioni o input dell'utente
await new Promise(resolve => setTimeout(resolve, 2000));
// Seguito con immagine
yield {
type: "user" as const,
message: {
role: "user" as const,
content: [
{
type: "text",
text: "Rivedi questo diagramma dell'architettura"
},
{
type: "image",
source: {
type: "base64",
media_type: "image/png",
data: readFileSync("diagram.png", "base64")
}
}
]
}
};
}
// Elabora risposte in streaming
for await (const message of query({
prompt: generateMessages(),
options: {
maxTurns: 10,
allowedTools: ["Read", "Grep"]
}
})) {
if (message.type === "result") {
console.log(message.result);
}
}Input Messaggio Singolo
L'input messaggio singolo è più semplice ma più limitato.
Quando Utilizzare l'Input Messaggio Singolo
Utilizza l'input messaggio singolo quando:
- Hai bisogno di una risposta one-shot
- Non hai bisogno di allegati immagine, hook, ecc.
- Devi operare in un ambiente stateless, come una funzione lambda
Limitazioni
La modalità input messaggio singolo non supporta:
- Allegati immagine diretti nei messaggi
- Accodamento dinamico dei messaggi
- Interruzione in tempo reale
- Integrazione hook
- Conversazioni multi-turno naturali
Esempio di Implementazione
import { query } from "@anthropic-ai/claude-agent-sdk";
// Query one-shot semplice
for await (const message of query({
prompt: "Spiega il flusso di autenticazione",
options: {
maxTurns: 1,
allowedTools: ["Read", "Grep"]
}
})) {
if (message.type === "result") {
console.log(message.result);
}
}
// Continua conversazione con gestione sessione
for await (const message of query({
prompt: "Ora spiega il processo di autorizzazione",
options: {
continue: true,
maxTurns: 1
}
})) {
if (message.type === "result") {
console.log(message.result);
}
}