Interfaz TypeScript SDK V2 (vista previa)

La interfaz V2 es una vista previa inestable. Las APIs 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 Claude V2 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 en todos los 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

Inicio rápido

Solicitud única

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 e imprime 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-6'
})
console.log(result.result)

Ver la misma operación en V1

import { query } from '@anthropic-ai/claude-agent-sdk'

const q = query({
  prompt: 'What is 2 + 2?',
  options: { model: 'claude-opus-4-6' }
})

for await (const msg of q) {
  if (msg.type === 'result') {
    console.log(msg.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-6'
})

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

Ver la misma operación en V1

En V1, tanto la entrada como la salida fluyen a través de un único generador asincrónico. Para una solicitud básica, esto se ve similar, pero agregar lógica de múltiples turnos requiere reestructuración para usar un generador de entrada.

import { query } from '@anthropic-ai/claude-agent-sdk'

const q = query({
  prompt: 'Hello!',
  options: { model: 'claude-opus-4-6' }
})

for await (const msg of q) {
  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-6'
})

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

Ver la misma operación en V1

import { query } from '@anthropic-ai/claude-agent-sdk'

// Must create an async iterable to feed messages
async function* createInputStream() {
  yield {
    type: 'user',
    session_id: '',
    message: { role: 'user', content: [{ type: 'text', text: 'What is 5 + 3?' }] },
    parent_tool_use_id: null
  }
  // Must coordinate when to yield next message
  yield {
    type: 'user',
    session_id: '',
    message: { role: 'user', content: [{ type: 'text', text: 'Multiply by 2' }] },
    parent_tool_use_id: null
  }
}

const q = query({
  prompt: createInputStream(),
  options: { model: 'claude-opus-4-6' }
})

for await (const msg of q) {
  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 en 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-6'
})

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-6'
})

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

Ver la misma operación en V1

import { query } from '@anthropic-ai/claude-agent-sdk'

// Create initial session
const initialQuery = query({
  prompt: 'Remember this number: 42',
  options: { model: 'claude-opus-4-6' }
})

// Get session ID from any message
let sessionId: string | undefined
for await (const msg of initialQuery) {
  sessionId = msg.session_id
  if (msg.type === 'assistant') {
    const text = msg.message.content
      .filter(block => block.type === 'text')
      .map(block => block.text)
      .join('')
    console.log('Initial response:', text)
  }
}

console.log('Session ID:', sessionId)

// Later: resume the session
const resumedQuery = query({
  prompt: 'What number did I ask you to remember?',
  options: {
    model: 'claude-opus-4-6',
    resume: sessionId
  }
})

for await (const msg of resumedQuery) {
  if (msg.type === 'assistant') {
    const text = msg.message.content
      .filter(block => block.type === 'text')
      .map(block => block.text)
      .join('')
    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-6'
})
// 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-6'
})
// ... 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
}): Session

`unstable_v2_resumeSession()`

Reanuda una sesión existente por ID.

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

`unstable_v2_prompt()`

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

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

Interfaz de sesión

interface Session {
  send(message: string): Promise<void>;
  stream(): AsyncGenerator<SDKMessage>;
  close(): void;
}

Disponibilidad de características

No todas las características de V1 están disponibles en V2 aún. Las siguientes requieren 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. Reporte problemas y sugerencias a través de GitHub Issues.

Ver 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 funcional