Vai al contenuto principale

​
Panoramica

Claude Agent SDK supporta due modalità di input distinte per interagire con gli agenti:
  • Modalità Streaming Input (Predefinita e Consigliata) - Una sessione persistente e interattiva
  • Single Message Input - Query una tantum 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 aiutarvi a scegliere l’approccio giusto per la vostra applicazione. 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.

​
Come Funziona

​
Vantaggi

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

import { query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
import { readFile } from "fs/promises";

async function* generateMessages(): AsyncGenerator<SDKUserMessage> {
  // First message
  yield {
    type: "user",
    message: {
      role: "user",
      content: "Analyze this codebase for security issues"
    },
    parent_tool_use_id: null
  };

  // Wait for conditions or user input
  await new Promise((resolve) => setTimeout(resolve, 2000));

  // Follow-up with image
  yield {
    type: "user",
    message: {
      role: "user",
      content: [
        {
          type: "text",
          text: "Review this architecture diagram"
        },
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: await readFile("diagram.png", "base64")
          }
        }
      ]
    },
    parent_tool_use_id: null
  };
}

// Process streaming responses
for await (const message of query({
  prompt: generateMessages(),
  options: {
    maxTurns: 10,
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}
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

import { query } from "@anthropic-ai/claude-agent-sdk";

// Simple one-shot query
for await (const message of query({
  prompt: "Explain the authentication flow",
  options: {
    maxTurns: 1,
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

// Continue conversation with session management
for await (const message of query({
  prompt: "Now explain the authorization process",
  options: {
    continue: true,
    maxTurns: 1
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}