​
Gestión de Sesiones

El Claude Agent SDK proporciona capacidades de gestión de sesiones para manejar el estado de conversación y la reanudación. Las sesiones te permiten continuar conversaciones a través de múltiples interacciones mientras mantienes el contexto completo.

​
Cómo Funcionan las Sesiones

Cuando inicias una nueva consulta, el SDK crea automáticamente una sesión y devuelve un ID de sesión en el mensaje inicial del sistema. Puedes capturar este ID para reanudar la sesión más tarde.

​
Obteniendo el ID de Sesión

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

let sessionId: string | undefined

const response = query({
  prompt: "Ayúdame a construir una aplicación web",
  options: {
    model: "claude-sonnet-4-5"
  }
})

for await (const message of response) {
  // El primer mensaje es un mensaje de inicialización del sistema con el ID de sesión
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Sesión iniciada con ID: ${sessionId}`)
    // Puedes guardar este ID para reanudación posterior
  }

  // Procesar otros mensajes...
  console.log(message)
}

// Más tarde, puedes usar el sessionId guardado para reanudar
if (sessionId) {
  const resumedResponse = query({
    prompt: "Continúa donde lo dejamos",
    options: {
      resume: sessionId
    }
  })
}

​
Reanudando Sesiones

El SDK soporta reanudar sesiones desde estados de conversación previos, habilitando flujos de trabajo de desarrollo continuo. Usa la opción resume con un ID de sesión para continuar una conversación previa. 
import { query } from "@anthropic-ai/claude-agent-sdk"

// Reanudar una sesión previa usando su ID
const response = query({
  prompt: "Continúa implementando el sistema de autenticación desde donde lo dejamos",
  options: {
    resume: "session-xyz", // ID de sesión de conversación previa
    model: "claude-sonnet-4-5",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// La conversación continúa con contexto completo de la sesión previa
for await (const message of response) {
  console.log(message)
}
El SDK maneja automáticamente la carga del historial de conversación y contexto cuando reanudas una sesión, permitiendo a Claude continuar exactamente donde lo dejó.

​
Bifurcando Sesiones

Al reanudar una sesión, puedes elegir continuar la sesión original o bifurcarla en una nueva rama. Por defecto, reanudar continúa la sesión original. Usa la opción forkSession (TypeScript) o la opción fork_session (Python) para crear un nuevo ID de sesión que comience desde el estado reanudado.

​
Cuándo Bifurcar una Sesión

Bifurcar es útil cuando quieres:
  • Explorar diferentes enfoques desde el mismo punto de partida
  • Crear múltiples ramas de conversación sin modificar la original
  • Probar cambios sin afectar el historial de la sesión original
  • Mantener rutas de conversación separadas para diferentes experimentos

​
Bifurcar vs Continuar

ComportamientoforkSession: false (por defecto)forkSession: true
ID de SesiónIgual que el originalNuevo ID de sesión generado
HistorialSe añade a la sesión originalCrea nueva rama desde el punto de reanudación
Sesión OriginalModificadaPreservada sin cambios
Caso de UsoContinuar conversación linealBifurcar para explorar alternativas

​
Ejemplo: Bifurcando una Sesión

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

// Primero, capturar el ID de sesión
let sessionId: string | undefined

const response = query({
  prompt: "Ayúdame a diseñar una API REST",
  options: { model: "claude-sonnet-4-5" }
})

for await (const message of response) {
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Sesión original: ${sessionId}`)
  }
}

// Bifurcar la sesión para probar un enfoque diferente
const forkedResponse = query({
  prompt: "Ahora rediseñemos esto como una API GraphQL en su lugar",
  options: {
    resume: sessionId,
    forkSession: true,  // Crea un nuevo ID de sesión
    model: "claude-sonnet-4-5"
  }
})

for await (const message of forkedResponse) {
  if (message.type === 'system' && message.subtype === 'init') {
    console.log(`Sesión bifurcada: ${message.session_id}`)
    // Este será un ID de sesión diferente
  }
}

// La sesión original permanece sin cambios y aún puede ser reanudada
const originalContinued = query({
  prompt: "Añade autenticación a la API REST",
  options: {
    resume: sessionId,
    forkSession: false,  // Continuar sesión original (por defecto)
    model: "claude-sonnet-4-5"
  }
})