Saltar al contenido principal
La interfaz V2 es una vista previa inestable. Las API pueden cambiar según los comentarios antes de volverse estables. Algunas características como la bifurcación de sesiones solo están disponibles en el SDK V1.
El SDK del Agente TypeScript V2 de Claude elimina la necesidad de generadores asincronos y coordinación de rendimiento. Esto hace que las conversaciones de múltiples turnos sean más simples; en lugar de gestionar el estado del generador entre turnos, cada turno es un ciclo send()/stream() separado. La superficie de la API se reduce a tres conceptos:
  • createSession() / resumeSession(): Iniciar o continuar una conversación
  • session.send(): Enviar un mensaje
  • session.stream(): Obtener la respuesta

​
Instalación

La interfaz V2 se incluye en el paquete SDK existente: 
npm install @anthropic-ai/claude-agent-sdk
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

No todas las características de V1 están disponibles en V2 aún. Lo siguiente requiere usar el SDK V1:
  • Bifurcación de sesiones (opción forkSession)
  • Algunos patrones avanzados de entrada de transmisión

​
Comentarios

Comparta sus comentarios sobre la interfaz V2 antes de que se vuelva estable. Informe de problemas y sugerencias a través de GitHub Issues.

​
Véase también