Gestión de Sesiones
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
}
})
}from claude_agent_sdk import query, ClaudeAgentOptions
session_id = None
async for message in query(
prompt="Ayúdame a construir una aplicación web",
options=ClaudeAgentOptions(
model="claude-sonnet-4-5"
)
):
# El primer mensaje es un mensaje de inicialización del sistema con el ID de sesión
if hasattr(message, 'subtype') and message.subtype == 'init':
session_id = message.data.get('session_id')
print(f"Sesión iniciada con ID: {session_id}")
# Puedes guardar este ID para reanudación posterior
# Procesar otros mensajes...
print(message)
# Más tarde, puedes usar el session_id guardado para reanudar
if session_id:
async for message in query(
prompt="Continúa donde lo dejamos",
options=ClaudeAgentOptions(
resume=session_id
)
):
print(message)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
| Comportamiento | forkSession: false (por defecto) | forkSession: true |
|---|---|---|
| ID de Sesión | Igual que el original | Nuevo ID de sesión generado |
| Historial | Se añade a la sesión original | Crea nueva rama desde el punto de reanudación |
| Sesión Original | Modificada | Preservada sin cambios |
| Caso de Uso | Continuar conversación lineal | Bifurcar 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"
}
})