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.
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 llamadaquery(), el agente ya toma tantos turnos como necesita, y los prompts de permiso y AskUserQuestion se manejan en bucle (no terminan la llamada).
| Lo que está construyendo | Qué usar |
|---|---|
| Tarea de una sola vez: prompt único, sin seguimiento | Nada extra. Una llamada query() lo maneja. |
| Chat multi-turno en un proceso | ClaudeSDKClient (Python) o continue: true (TypeScript). El SDK rastrea la sesión para usted sin manejo de ID. |
| Continuar donde lo dejó después de un reinicio de proceso | continue_conversation=True (Python) / continue: true (TypeScript). Reanuda la sesión más reciente en el directorio, sin ID necesario. |
| Reanudar una sesión pasada específica (no la más reciente) | Capture el ID de sesión y páselo a resume. |
| Probar un enfoque alternativo sin perder el original | Bifurque la sesión. |
| Tarea sin estado, no quiere nada escrito en disco (solo TypeScript) | Establezca persistSession: false. La sesión existe solo en memoria durante la duración de la llamada. Python siempre persiste en disco. |
Continue, resume y fork
Continue, resume y fork son campos de opción que establece enquery() (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.
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
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 camposession_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.
Reanudar por ID
Pase un ID de sesión aresume 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_turnsoerror_max_budget_usd(vea Manejar el resultado); reanude con un límite más alto. - Reiniciar su proceso. Capturó el ID antes del apagado y desea restaurar la conversación.
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.
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:
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), tiene dos opciones:- Mover el archivo de sesión. Persista
~/.claude/projects/<encoded-cwd>/<session-id>.jsonlde la primera ejecución y restáurelo a la misma ruta en el nuevo host antes de llamar aresume. Elcwddebe coincidir. - 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.
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.
Recursos relacionados
- Cómo funciona el bucle del agente: Comprenda turnos, mensajes y acumulación de contexto dentro de una sesión
- File checkpointing: Captura de pantalla y reversión de cambios de archivos que el agente realizó dentro de una sesión
- Python
ClaudeAgentOptions: Referencia completa de opciones de sesión para Python - TypeScript
Options: Referencia completa de opciones de sesión para TypeScript