Skip to main content
Una sesión es el historial de conversación que el SDK acumula mientras su agente trabaja. Contiene su prompt, cada llamada a herramienta que hizo el agente, cada resultado de herramienta y cada respuesta. El SDK la escribe en disco automáticamente para que pueda volver a ella más tarde. Volver a una sesión significa que el agente tiene contexto completo de antes: archivos que ya leyó, análisis que ya realizó, decisiones que ya tomó. Puede hacer una pregunta de seguimiento, recuperarse de una interrupción o ramificarse para probar un enfoque diferente.
Las sesiones persisten la conversación, no el sistema de archivos. Para capturar y revertir cambios de archivos que hizo el agente, use file checkpointing.
Esta guía cubre cómo elegir el enfoque correcto para su aplicación, las interfaces del SDK que rastrean sesiones automáticamente, cómo capturar IDs de sesión y usar resume y fork manualmente, y qué debe saber sobre reanudar sesiones entre hosts.

Elegir un enfoque

Cuánto manejo de sesiones necesita depende de la forma de su aplicación. La gestión de sesiones entra en juego cuando envía múltiples prompts que deben compartir contexto. Dentro de una única llamada query(), el agente ya toma tantos turnos como necesita, y los prompts de permiso y AskUserQuestion se manejan en bucle (no terminan la llamada).

Continue, resume y fork

Continue, resume y fork son campos de opción que establece en query() (ClaudeAgentOptions en Python, Options en TypeScript). Continue y resume ambos retoman una sesión existente y la amplían. La diferencia es cómo encuentran esa sesión:
  • Continue encuentra la sesión más reciente en el directorio actual. No rastrea nada. Funciona bien cuando su aplicación ejecuta una conversación a la vez.
  • Resume toma un ID de sesión específico. Rastrea el ID. Requerido cuando tiene múltiples sesiones (por ejemplo, una por usuario en una aplicación multiusuario) o desea volver a una que no sea la más reciente.
Fork es diferente: crea una nueva sesión que comienza con una copia del historial del original. El original permanece sin cambios. Use fork para probar una dirección diferente mientras mantiene la opción de volver atrás.

Gestión automática de sesiones

Ambos SDKs ofrecen una interfaz que rastrea el estado de la sesión para usted entre llamadas, por lo que no pasa IDs alrededor manualmente. Use estos para conversaciones multi-turno dentro de un único proceso.

Python: ClaudeSDKClient

ClaudeSDKClient maneja IDs de sesión internamente. Cada llamada a client.query() continúa automáticamente la misma sesión. Llame a client.receive_response() para iterar sobre los mensajes de la consulta actual. Use el cliente como un gestor de contexto asincrónico para que la configuración de conexión y el cierre se manejen automáticamente, o llame a connect() y disconnect() manualmente. Este ejemplo ejecuta dos consultas contra el mismo client. La primera le pide al agente que analice un módulo; la segunda le pide que refactorice ese módulo. Debido a que ambas llamadas van a través de la misma instancia de cliente, la segunda consulta tiene contexto completo de la primera sin ningún resume explícito o ID de sesión:
Python
Cada consulta imprime la respuesta de texto del agente seguida de una línea de estado del mensaje de resultado, como [done: success, cost: $0.0042]. Vea la referencia del SDK de Python para detalles sobre cuándo usar ClaudeSDKClient versus la función query() independiente.

TypeScript: continue: true

El SDK de TypeScript no tiene un objeto cliente que mantenga sesión como el ClaudeSDKClient de Python. En su lugar, pase continue: true en cada llamada query() posterior y el SDK retoma la sesión más reciente en el directorio actual. No se requiere seguimiento de ID. Este ejemplo hace dos llamadas query() separadas. La primera crea una sesión nueva; la segunda establece continue: true, que le dice al SDK que encuentre y reanude la sesión más reciente en disco. El agente tiene contexto completo de la primera llamada:
TypeScript
La API de sesión V2 experimental, que proporcionaba createSession() con un patrón send / stream, fue eliminada en TypeScript Agent SDK 0.3.142. Use la función query() y las opciones de sesión descritas en esta página en su lugar.

Usar opciones de sesión con query()

Capturar el ID de sesión

Resume y fork requieren un ID de sesión. Léalo del campo session_id en el mensaje de resultado (ResultMessage en Python, SDKResultMessage en TypeScript), que está presente en cada resultado independientemente del éxito o error. En TypeScript, el ID también está disponible antes como un campo directo en el SystemMessage de inicio; en Python está anidado dentro de SystemMessage.data.
Cuando la consulta se completa, el script imprime la respuesta del agente seguida de una línea como Session ID: 5b3f2c1a-8d4e-4f6b-9a7c-2e1d0f9b8a6c. En las siguientes secciones, pasa este ID a resume.

Reanudar por ID

Pase un ID de sesión a resume para volver a esa sesión específica. El agente retoma con contexto completo de donde la sesión se quedó. Las razones comunes para reanudar son:
  • Seguimiento en una tarea completada. El agente ya analizó algo; ahora quiere que actúe sobre ese análisis sin releer archivos.
  • Recuperarse de un límite. La primera ejecución terminó con error_max_turns o error_max_budget_usd (vea Manejar el resultado); reanude con un límite más alto. En una llamada query() de un solo disparo, el SDK genera una excepción después de ceder ese resultado de error, así que capture el error antes de reanudar.
  • Reiniciar su proceso. Capturó el ID antes del apagado y desea restaurar la conversación.
Este ejemplo reanuda la sesión de Capturar el ID de sesión con un prompt de seguimiento. Debido a que está reanudando, el agente ya tiene el análisis anterior en contexto:
Debería ver una respuesta que se basa en el análisis anterior en lugar de comenzar de nuevo. Eso confirma que el agente reanudó la sesión con su contexto anterior intacto.
Claude Code almacena sesiones bajo ~/.claude/projects/<encoded-cwd>/*.jsonl. Si establece la variable de entorno CLAUDE_CONFIG_DIR, busque bajo $CLAUDE_CONFIG_DIR/projects/ en su lugar.Para encontrar el directorio de su sesión, reemplace cada carácter no alfanumérico en el directorio de trabajo absoluto con -: /Users/me/proj se convierte en -Users-me-proj. Para un directorio de trabajo cuyo nombre convertido excede 200 caracteres, Claude Code trunca el nombre y añade un hash, así que coincida con los primeros 200 caracteres del nombre convertido cuando enumere projects/.Si establece CLAUDE_CODE_PROJECT_DIR_NAME junto a CLAUDE_CONFIG_DIR, busque bajo ese nombre en projects/ en su lugar. Requiere TypeScript Agent SDK v0.3.234 o posterior, o Python Agent SDK v0.2.140 o posterior.Puede reanudar desde cualquier directorio de trabajo:
  • Búsqueda entre directorios: Claude Code busca más allá del directorio del proyecto actual para encontrar el ID; consulta Reanudar una sesión para el orden de búsqueda exacto y cómo se manejan las copias duplicadas.
  • Solo la misma máquina: el archivo de sesión aún necesita existir en la máquina actual.
Antes de v2.1.223, la búsqueda estaba limitada al directorio del proyecto actual y sus git worktrees; las versiones del SDK que incluyen una CLI más antigua aún se comportan de esta manera.
Para reanudar sesiones entre máquinas o en entornos sin servidor, refleje transcripciones en almacenamiento compartido con un adaptador SessionStore.

Bifurcar para explorar alternativas

Bifurcar crea una nueva sesión que comienza con una copia del historial del original pero diverge desde ese punto. La bifurcación obtiene su propio ID de sesión; el ID y el historial del original permanecen sin cambios. Termina con dos sesiones independientes que puede reanudar por separado.
Bifurcar ramifica el historial de conversación, no el sistema de archivos. Si un agente bifurcado edita archivos, esos cambios son reales y visibles para cualquier sesión que trabaje en el mismo directorio. Para ramificar y revertir cambios de archivos, use file checkpointing.
Este ejemplo se basa en Capturar el ID de sesión: ya ha analizado un módulo de autenticación en session_id y desea explorar OAuth2 sin perder el hilo enfocado en JWT. El primer bloque bifurca la sesión y captura el ID de la bifurcación (forked_id); el segundo bloque reanuda el session_id original para continuar por el camino JWT. Ahora tiene dos IDs de sesión apuntando a dos historiales separados:
Debería ver que forkedId difiere del ID de sesión original. Reanudar la sesión original aún continúa el hilo JWT, lo que confirma que la bifurcación no modificó el historial original.

Reanudar entre hosts

Los archivos de sesión son locales a la máquina que los creó. Para reanudar una sesión en un host diferente (trabajadores de CI, contenedores efímeros, sin servidor), elija el enfoque que se ajuste:
  • Pasar un almacén de sesión. Adjunte un adaptador sessionStore / session_store para que el SDK refleje las transcripciones en su propio backend y otro host pueda reanudarlas. La clave de búsqueda del almacén se deriva del directorio de trabajo, así que reanude desde un cwd que coincida con la ejecución original.
  • Mover el archivo de sesión. Persista ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl de la primera ejecución y restáurelo dentro de cualquier directorio bajo ~/.claude/projects/ en el nuevo host antes de llamar a resume. Claude Code busca más allá del directorio del proyecto actual para encontrar el ID; consulta Reanudar una sesión para conocer el orden de búsqueda exacto y cómo se manejan las copias duplicadas. Antes de v2.1.223, la búsqueda se limitaba al directorio del proyecto actual y sus git worktrees; las versiones del SDK que incluyen una CLI más antigua aún se comportan de esta manera.
  • No confíe en la reanudación de sesión. Capture los resultados que necesita (salida de análisis, decisiones, diffs de archivos) como estado de aplicación y páselos al prompt de una sesión nueva. Esto a menudo es más robusto que enviar archivos de transcripción.
Ambos SDKs exponen funciones para enumerar sesiones en disco y leer sus mensajes: listSessions() y getSessionMessages() en TypeScript, list_sessions() y get_session_messages() en Python. Úselos para construir selectores de sesión personalizados, lógica de limpieza o visores de transcripción. Ambos SDKs también exponen funciones para buscar y mutar sesiones individuales: get_session_info(), rename_session() y tag_session() en Python, y getSessionInfo(), renameSession() y tagSession() en TypeScript. Úselos para organizar sesiones por etiqueta o darles títulos legibles por humanos.