API sessione TypeScript SDK V2 (rimosso)

L’API sessione V2 non è più supportata. TypeScript Agent SDK 0.3.142 rimuove unstable_v2_createSession, unstable_v2_resumeSession, unstable_v2_prompt e i tipi SDKSession e SDKSessionOptions.Per eseguire la migrazione, utilizzare l’API query() e le opzioni sessione che accetta. Passare un AsyncIterable<SDKUserMessage> per conversazioni multi-turno, oppure options.resume per continuare una sessione salvata. Questa pagina viene mantenuta come riferimento se si mantiene il codice su Agent SDK 0.2.x o versioni precedenti.

V2 era un’API sessione sperimentale che eliminava la necessità di generatori asincroni e coordinamento yield. Invece di gestire lo stato del generatore tra i turni, ogni turno era un ciclo send()/stream() separato. La superficie API si riduceva a creare una sessione, inviare un messaggio e trasmettere la risposta:

createSession() / resumeSession(): Avviare o continuare una conversazione
session.send(): Inviare un messaggio
session.stream(): Ottenere la risposta

Installazione

Agent SDK 0.2.x è l’ultima versione che include l’interfaccia V2. La versione del pacchetto è passata da 0.2.x direttamente a 0.3.142, quindi la versione di rimozione sopra e il pin di installazione sottostante descrivono lo stesso limite. Per installare l’ultima versione compatibile con V2, fissare la versione principale e secondaria:

npm install @anthropic-ai/claude-agent-sdk@0.2

L’SDK raggruppa un binario Claude Code nativo per la vostra piattaforma come dipendenza opzionale, quindi la maggior parte delle installazioni non necessita di un’installazione separata di Claude Code. Consultare la nota di installazione della guida rapida per le installazioni che ne hanno bisogno.

Avvio rapido

Prompt singolo

Per semplici query a turno singolo dove non è necessario mantenere una sessione, utilizzare unstable_v2_prompt(). Questo esempio invia una domanda matematica e registra la risposta:

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

const result = await unstable_v2_prompt("What is 2 + 2?", {
  model: "claude-opus-4-7"
});
if (result.subtype === "success") {
  console.log(result.result);
}

Sessione di base

Per interazioni oltre un singolo prompt, creare una sessione. V2 separa l’invio e lo streaming in passaggi distinti:

send() invia il vostro messaggio
stream() trasmette la risposta

Questa separazione esplicita rende più facile aggiungere logica tra i turni (come elaborare le risposte prima di inviare i follow-up). L’esempio seguente crea una sessione, invia “Hello!” a Claude e stampa la risposta di testo. Utilizza await using (TypeScript 5.2+) per chiudere automaticamente la sessione quando il blocco esce. Potete anche chiamare session.close() manualmente.

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

await using session = unstable_v2_createSession({
  model: "claude-opus-4-7"
});

await session.send("Hello!");
for await (const msg of session.stream()) {
  // Filter for assistant messages to get human-readable output
  if (msg.type === "assistant") {
    const text = msg.message.content
      .filter((block) => block.type === "text")
      .map((block) => block.text)
      .join("");
    console.log(text);
  }
}

Conversazione multi-turno

Le sessioni mantengono il contesto attraverso più scambi. Per continuare una conversazione, chiamare send() di nuovo sulla stessa sessione. Claude ricorda i turni precedenti. Questo esempio pone una domanda matematica, quindi pone un follow-up che fa riferimento alla risposta precedente:

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

await using session = unstable_v2_createSession({
  model: "claude-opus-4-7"
});

// Turn 1
await session.send("What is 5 + 3?");
for await (const msg of session.stream()) {
  // Filter for assistant messages to get human-readable output
  if (msg.type === "assistant") {
    const text = msg.message.content
      .filter((block) => block.type === "text")
      .map((block) => block.text)
      .join("");
    console.log(text);
  }
}

// Turn 2
await session.send("Multiply that by 2");
for await (const msg of session.stream()) {
  if (msg.type === "assistant") {
    const text = msg.message.content
      .filter((block) => block.type === "text")
      .map((block) => block.text)
      .join("");
    console.log(text);
  }
}

Ripresa della sessione

Se avete un ID di sessione da un’interazione precedente, potete riprenderla in seguito. Questo è utile per flussi di lavoro di lunga durata o quando è necessario persistere le conversazioni tra i riavvii dell’applicazione. Questo esempio crea una sessione, memorizza il suo ID, la chiude, quindi riprende la conversazione:

import {
  unstable_v2_createSession,
  unstable_v2_resumeSession,
  type SDKMessage
} from "@anthropic-ai/claude-agent-sdk";

// Helper to extract text from assistant messages
function getAssistantText(msg: SDKMessage): string | null {
  if (msg.type !== "assistant") return null;
  return msg.message.content
    .filter((block) => block.type === "text")
    .map((block) => block.text)
    .join("");
}

// Create initial session and have a conversation
const session = unstable_v2_createSession({
  model: "claude-opus-4-7"
});

await session.send("Remember this number: 42");

// Get the session ID from any received message
let sessionId: string | undefined;
for await (const msg of session.stream()) {
  sessionId = msg.session_id;
  const text = getAssistantText(msg);
  if (text) console.log("Initial response:", text);
}

console.log("Session ID:", sessionId);
session.close();

// Later: resume the session using the stored ID
await using resumedSession = unstable_v2_resumeSession(sessionId!, {
  model: "claude-opus-4-7"
});

await resumedSession.send("What number did I ask you to remember?");
for await (const msg of resumedSession.stream()) {
  const text = getAssistantText(msg);
  if (text) console.log("Resumed response:", text);
}

Pulizia

Le sessioni possono essere chiuse manualmente o automaticamente utilizzando await using, una funzionalità di TypeScript 5.2+ per la pulizia automatica delle risorse. Se state utilizzando una versione precedente di TypeScript o riscontrate problemi di compatibilità, utilizzate invece la pulizia manuale. Gli esempi seguenti mostrano solo il modello di pulizia e non inviano alcun messaggio, quindi l’esecuzione non produce alcun output. Pulizia automatica (TypeScript 5.2+):

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

await using session = unstable_v2_createSession({
  model: "claude-opus-4-7"
});
// Session closes automatically when the block exits

Pulizia manuale:

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

const session = unstable_v2_createSession({
  model: "claude-opus-4-7"
});
// ... use the session ...
session.close();

Riferimento API

`unstable_v2_createSession()`

Crea una nuova sessione per conversazioni multi-turno.

function unstable_v2_createSession(options: {
  model: string;
  // Additional options supported
}): SDKSession;

`unstable_v2_resumeSession()`

Riprende una sessione esistente per ID.

function unstable_v2_resumeSession(
  sessionId: string,
  options: {
    model: string;
    // Additional options supported
  }
): SDKSession;

`unstable_v2_prompt()`

Funzione di convenienza one-shot per query a turno singolo.

function unstable_v2_prompt(
  prompt: string,
  options: {
    model: string;
    // Additional options supported
  }
): Promise<SDKResultMessage>;

Interfaccia SDKSession

interface SDKSession {
  readonly sessionId: string;
  send(message: string | SDKUserMessage): Promise<void>;
  stream(): AsyncGenerator<SDKMessage, void>;
  close(): void;
}

Disponibilità delle funzionalità

L’API sessione V2 non supporta tutte le funzionalità V1. Le seguenti richiedono l’SDK V1:

Forking della sessione (opzione forkSession)
Alcuni pattern di input streaming avanzati

Vedere anche

Riferimento SDK TypeScript (V1) - Documentazione completa dell’SDK V1
Panoramica SDK - Concetti generali dell’SDK
Esempi V2 su GitHub - Esempi di codice funzionanti

Agent SDK

Crea agenti

Concetti fondamentali

Input e output

Estendi con strumenti

Personalizza il comportamento

Controllo e osservabilità

Distribuzione

Riferimenti SDK

API sessione TypeScript SDK V2 (rimosso)

Installazione

Avvio rapido

Prompt singolo

Sessione di base

Conversazione multi-turno

Ripresa della sessione

Pulizia

Riferimento API

`unstable_v2_createSession()`

`unstable_v2_resumeSession()`

`unstable_v2_prompt()`

Interfaccia SDKSession

Disponibilità delle funzionalità

Vedere anche

​Installazione

​Avvio rapido

​Prompt singolo

​Sessione di base

​Conversazione multi-turno

​Ripresa della sessione

​Pulizia

​Riferimento API

​unstable_v2_createSession()

​unstable_v2_resumeSession()

​unstable_v2_prompt()

​Interfaccia SDKSession

​Disponibilità delle funzionalità

​Vedere anche

Installazione

Avvio rapido

Prompt singolo

Sessione di base

Conversazione multi-turno

Ripresa della sessione

Pulizia

Riferimento API

`unstable_v2_createSession()`

`unstable_v2_resumeSession()`

`unstable_v2_prompt()`

Interfaccia SDKSession

Disponibilità delle funzionalità

Vedere anche