API de sesión de TypeScript SDK V2 (eliminada)

La API de sesión V2 ya no es compatible. TypeScript Agent SDK 0.3.142 elimina unstable_v2_createSession, unstable_v2_resumeSession, unstable_v2_prompt y los tipos SDKSession y SDKSessionOptions.Para migrar, use la API query() y las opciones de sesión que acepta. Pase un AsyncIterable<SDKUserMessage> para conversaciones de múltiples turnos, u options.resume para continuar una sesión guardada. Esta página se mantiene como referencia si mantiene código en Agent SDK 0.2.x o anterior.

V2 fue una API de sesión experimental que eliminó la necesidad de generadores asincronos y coordinación de rendimiento. En lugar de gestionar el estado del generador entre turnos, cada turno era un ciclo send()/stream() separado. La superficie de la API se redujo a tres conceptos:

createSession() / resumeSession(): Iniciar o continuar una conversación
session.send(): Enviar un mensaje
session.stream(): Obtener la respuesta

Instalación

Agent SDK 0.2.x es la última versión que incluye la interfaz V2. La versión del paquete saltó de 0.2.x directamente a 0.3.142, por lo que la versión de eliminación anterior y el pin de instalación a continuación describen el mismo límite. Para instalar la última versión compatible con V2, fije la versión principal y secundaria:

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

El SDK incluye un binario nativo de Claude Code para su plataforma como una dependencia opcional, por lo que no necesita instalar Claude Code por separado.

Inicio rápido

Solicitud de un solo turno

Para consultas simples de un solo turno donde no necesita mantener una sesión, use unstable_v2_prompt(). Este ejemplo envía una pregunta matemática y registra la respuesta:

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

Sesión básica

Para interacciones más allá de una solicitud única, cree una sesión. V2 separa el envío y la transmisión en pasos distintos:

send() envía su mensaje
stream() transmite la respuesta

Esta separación explícita facilita agregar lógica entre turnos (como procesar respuestas antes de enviar seguimientos). El ejemplo a continuación crea una sesión, envía “¡Hola!” a Claude e imprime la respuesta de texto. Utiliza await using (TypeScript 5.2+) para cerrar automáticamente la sesión cuando el bloque sale. También puede llamar a 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);
  }
}

Conversación de múltiples turnos

Las sesiones persisten el contexto en múltiples intercambios. Para continuar una conversación, llame a send() nuevamente en la misma sesión. Claude recuerda los turnos anteriores. Este ejemplo hace una pregunta matemática y luego hace un seguimiento que hace referencia a la respuesta anterior:

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

Reanudación de sesión

Si tiene un ID de sesión de una interacción anterior, puede reanudarlo más tarde. Esto es útil para flujos de trabajo de larga duración o cuando necesita persistir conversaciones entre reinicios de aplicaciones. Este ejemplo crea una sesión, almacena su ID, la cierra y luego reanuda la conversación:

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

Limpieza

Las sesiones se pueden cerrar manualmente o automáticamente usando await using, una característica de TypeScript 5.2+ para la limpieza automática de recursos. Si está utilizando una versión anterior de TypeScript o encuentra problemas de compatibilidad, use la limpieza manual en su lugar. Limpieza automática (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

Limpieza manual:

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

Referencia de API

`unstable_v2_createSession()`

Crea una nueva sesión para conversaciones de múltiples turnos.

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

`unstable_v2_resumeSession()`

Reanuda una sesión existente por ID.

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

`unstable_v2_prompt()`

Función de conveniencia de un solo turno para consultas de un solo turno.

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

Interfaz SDKSession

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

Disponibilidad de características

La API de sesión V2 no admite todas las características de V1. Lo siguiente requiere el SDK V1:

Bifurcación de sesiones (opción forkSession)
Algunos patrones avanzados de entrada de transmisión

Véase también

Referencia del SDK TypeScript (V1) - Documentación completa del SDK V1
Descripción general del SDK - Conceptos generales del SDK
Ejemplos de V2 en GitHub - Ejemplos de código funcionales

SDK de Agent

Conceptos fundamentales

Entrada y salida

Extender con herramientas

Personalizar comportamiento

Control y observabilidad

Implementación

Referencias de SDK

API de sesión de TypeScript SDK V2 (eliminada)

Instalación

Inicio rápido

Solicitud de un solo turno

Sesión básica

Conversación de múltiples turnos

Reanudación de sesión

Limpieza

Referencia de API

`unstable_v2_createSession()`

`unstable_v2_resumeSession()`

`unstable_v2_prompt()`

Interfaz SDKSession

Disponibilidad de características

Véase también

​Instalación

​Inicio rápido

​Solicitud de un solo turno

​Sesión básica

​Conversación de múltiples turnos

​Reanudación de sesión

​Limpieza

​Referencia de API

​unstable_v2_createSession()

​unstable_v2_resumeSession()

​unstable_v2_prompt()

​Interfaz SDKSession

​Disponibilidad de características

​Véase también

Instalación

Inicio rápido

Solicitud de un solo turno

Sesión básica

Conversación de múltiples turnos

Reanudación de sesión

Limpieza

Referencia de API

`unstable_v2_createSession()`

`unstable_v2_resumeSession()`

`unstable_v2_prompt()`

Interfaz SDKSession

Disponibilidad de características

Véase también