​
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

​
Vantaggi

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