As sessões persistem a conversa, não o sistema de arquivos. Para capturar e reverter alterações de arquivo que o agente fez, use file checkpointing.
resume e fork manualmente, e o que você precisa saber sobre retomar sessões entre hosts.
Escolha uma abordagem
Quanto gerenciamento de sessão você precisa depende da forma do seu aplicativo. O gerenciamento de sessão entra em jogo quando você envia múltiplos prompts que devem compartilhar contexto. Dentro de uma única chamadaquery(), o agente já faz quantas voltas precisar, e prompts de permissão e AskUserQuestion são tratados em loop (eles não encerram a chamada).
| O que você está construindo | O que usar |
|---|---|
| Tarefa única: prompt único, sem acompanhamento | Nada extra. Uma chamada query() resolve. |
| Chat multi-turno em um processo | ClaudeSDKClient (Python) ou continue: true (TypeScript). O SDK rastreia a sessão para você sem nenhum tratamento de ID. |
| Retomar de onde parou após reinicialização do processo | continue_conversation=True (Python) / continue: true (TypeScript). Retoma a sessão mais recente no diretório, sem necessidade de ID. |
| Retomar uma sessão passada específica (não a mais recente) | Capture o ID da sessão e passe para resume. |
| Tentar uma abordagem alternativa sem perder a original | Faça fork da sessão. |
| Tarefa sem estado, não quer nada escrito em disco (apenas TypeScript) | Defina persistSession: false. A sessão existe apenas na memória durante a chamada. Python sempre persiste em disco. |
Continue, resume e fork
Continue, resume e fork são campos de opção que você define emquery() (ClaudeAgentOptions em Python, Options em TypeScript).
Continue e resume ambos retomam uma sessão existente e adicionam a ela. A diferença é como eles encontram essa sessão:
- Continue encontra a sessão mais recente no diretório atual. Você não rastreia nada. Funciona bem quando seu aplicativo executa uma conversa por vez.
- Resume recebe um ID de sessão específico. Você rastreia o ID. Necessário quando você tem múltiplas sessões (por exemplo, uma por usuário em um aplicativo multi-usuário) ou quer retornar a uma que não é a mais recente.
Gerenciamento automático de sessão
Ambos os SDKs oferecem uma interface que rastreia o estado da sessão para você entre chamadas, para que você não passe IDs manualmente. Use-os para conversas multi-turno dentro de um único processo.Python: ClaudeSDKClient
ClaudeSDKClient trata IDs de sessão internamente. Cada chamada para client.query() continua automaticamente a mesma sessão. Chame client.receive_response() para iterar sobre as mensagens da consulta atual. Use o cliente como um gerenciador de contexto assíncrono para que a configuração e encerramento da conexão sejam tratados para você, ou chame connect() e disconnect() manualmente.
Este exemplo executa duas consultas contra o mesmo client. A primeira pede ao agente para analisar um módulo; a segunda pede para refatorar esse módulo. Como ambas as chamadas passam pela mesma instância do cliente, a segunda consulta tem contexto completo da primeira sem nenhum resume ou ID de sessão explícito:
Python
ClaudeSDKClient versus a função query() independente.
TypeScript: continue: true
O SDK TypeScript não tem um objeto cliente que mantém sessão como o ClaudeSDKClient do Python. Em vez disso, passe continue: true em cada chamada query() subsequente e o SDK retoma a sessão mais recente no diretório atual. Nenhum rastreamento de ID necessário.
Este exemplo faz duas chamadas query() separadas. A primeira cria uma sessão nova; a segunda define continue: true, que diz ao SDK para encontrar e retomar a sessão mais recente em disco. O agente tem contexto completo da primeira chamada:
TypeScript
A API de sessão V2 experimental, que fornecia
createSession() com um padrão send / stream, foi removida no TypeScript Agent SDK 0.3.142. Use a função query() e as opções de sessão descritas nesta página.Use opções de sessão com query()
Capture o ID da sessão
Resume e fork requerem um ID de sessão. Leia-o do camposession_id na mensagem de resultado (ResultMessage em Python, SDKResultMessage em TypeScript), que está presente em cada resultado independentemente de sucesso ou erro. Em TypeScript, o ID também está disponível mais cedo como um campo direto na SystemMessage de inicialização; em Python, está aninhado dentro de SystemMessage.data.
Retomar por ID
Passe um ID de sessão pararesume para retornar a essa sessão específica. O agente retoma com contexto completo de onde a sessão parou. Razões comuns para retomar:
- Acompanhamento de uma tarefa concluída. O agente já analisou algo; agora você quer que ele aja com base nessa análise sem reler arquivos.
- Recuperação de um limite. A primeira execução terminou com
error_max_turnsouerror_max_budget_usd(veja Handle the result); retome com um limite mais alto. - Reiniciar seu processo. Você capturou o ID antes do desligamento e quer restaurar a conversa.
SessionStore.
Fork para explorar alternativas
Forking cria uma nova sessão que começa com uma cópia do histórico da original, mas diverge a partir desse ponto. O fork recebe seu próprio ID de sessão; o ID e histórico da original permanecem inalterados. Você acaba com duas sessões independentes que pode retomar separadamente.Forking ramifica o histórico de conversas, não o sistema de arquivos. Se um agente com fork editar arquivos, essas alterações são reais e visíveis para qualquer sessão trabalhando no mesmo diretório. Para ramificar e reverter alterações de arquivo, use file checkpointing.
session_id e quer explorar OAuth2 sem perder o thread focado em JWT. O primeiro bloco faz fork da sessão e captura o ID do fork (forked_id); o segundo bloco retoma o session_id original para continuar pelo caminho JWT. Você agora tem dois IDs de sessão apontando para dois históricos separados:
Retomar entre hosts
Os arquivos de sessão são locais para a máquina que os criou. Para retomar uma sessão em um host diferente (workers de CI, contêineres efêmeros, sem servidor), você tem duas opções:- Mover o arquivo de sessão. Persista
~/.claude/projects/<encoded-cwd>/<session-id>.jsonlda primeira execução e restaure-o para o mesmo caminho no novo host antes de chamarresume. Ocwddeve corresponder. - Não confie em retomada de sessão. Capture os resultados que você precisa (saída de análise, decisões, diffs de arquivo) como estado do aplicativo e passe-os para o prompt de uma sessão nova. Isso geralmente é mais robusto do que enviar arquivos de transcrição.
listSessions() e getSessionMessages() em TypeScript, list_sessions() e get_session_messages() em Python. Use-os para construir seletores de sessão personalizados, lógica de limpeza ou visualizadores de transcrição.
Ambos os SDKs também expõem funções para procurar e mutar sessões individuais: get_session_info(), rename_session() e tag_session() em Python, e getSessionInfo(), renameSession() e tagSession() em TypeScript. Use-os para organizar sessões por tag ou dar-lhes títulos legíveis por humanos.
Recursos relacionados
- How the agent loop works: Entenda voltas, mensagens e acumulação de contexto dentro de uma sessão
- File checkpointing: Rastreie e reverta alterações de arquivo entre sessões
- Python
ClaudeAgentOptions: Referência completa de opções de sessão para Python - TypeScript
Options: Referência completa de opções de sessão para TypeScript