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 tre concetti:

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 non è necessario installare Claude Code separatamente.

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. 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

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