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.

​
Modalità Streaming Input (Consigliata)

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

​
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

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