Pular para o conteúdo principal
Uma sessão é o histórico de conversas que o SDK acumula enquanto seu agente trabalha. Ela contém seu prompt, cada chamada de ferramenta que o agente fez, cada resultado de ferramenta e cada resposta. O SDK a escreve em disco automaticamente para que você possa retornar a ela mais tarde. Retornar a uma sessão significa que o agente tem contexto completo de antes: arquivos que já leu, análises que já realizou, decisões que já tomou. Você pode fazer uma pergunta de acompanhamento, se recuperar de uma interrupção ou ramificar para tentar uma abordagem diferente.
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.
Este guia cobre como escolher a abordagem certa para seu aplicativo, as interfaces do SDK que rastreiam sessões automaticamente, como capturar IDs de sessão e usar 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 chamada query(), 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á construindoO que usar
Tarefa única: prompt único, sem acompanhamentoNada extra. Uma chamada query() resolve.
Chat multi-turno em um processoClaudeSDKClient (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 processocontinue_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 originalFaç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 em query() (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.
Fork é diferente: cria uma nova sessão que começa com uma cópia do histórico da original. A original permanece inalterada. Use fork para tentar uma direção diferente enquanto mantém a opção de voltar.

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
import asyncio
from claude_agent_sdk import (
    ClaudeSDKClient,
    ClaudeAgentOptions,
    AssistantMessage,
    ResultMessage,
    TextBlock,
)


def print_response(message):
    """Print only the human-readable parts of a message."""
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if isinstance(block, TextBlock):
                print(block.text)
    elif isinstance(message, ResultMessage):
        cost = (
            f"${message.total_cost_usd:.4f}"
            if message.total_cost_usd is not None
            else "N/A"
        )
        print(f"[done: {message.subtype}, cost: {cost}]")


async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Glob", "Grep"],
    )

    async with ClaudeSDKClient(options=options) as client:
        # First query: client captures the session ID internally
        await client.query("Analyze the auth module")
        async for message in client.receive_response():
            print_response(message)

        # Second query: automatically continues the same session
        await client.query("Now refactor it to use JWT")
        async for message in client.receive_response():
            print_response(message)


asyncio.run(main())
Veja a referência do SDK Python para detalhes sobre quando usar 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
import { query } from "@anthropic-ai/claude-agent-sdk";

// First query: creates a new session
for await (const message of query({
  prompt: "Analyze the auth module",
  options: { allowedTools: ["Read", "Glob", "Grep"] }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

// Second query: continue: true resumes the most recent session
for await (const message of query({
  prompt: "Now refactor it to use JWT",
  options: {
    continue: true,
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}
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 campo session_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.
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    session_id = None

    async for message in query(
        prompt="Analyze the auth module and suggest improvements",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep"],
        ),
    ):
        if isinstance(message, ResultMessage):
            session_id = message.session_id
            if message.subtype == "success":
                print(message.result)

    print(f"Session ID: {session_id}")
    return session_id


session_id = asyncio.run(main())

Retomar por ID

Passe um ID de sessão para resume 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_turns ou error_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.
Este exemplo retoma a sessão de Capture o ID da sessão com um prompt de acompanhamento. Como você está retomando, o agente já tem a análise anterior em contexto:
# Earlier session analyzed the code; now build on that analysis
async for message in query(
    prompt="Now implement the refactoring you suggested",
    options=ClaudeAgentOptions(
        resume=session_id,
        allowed_tools=["Read", "Edit", "Write", "Glob", "Grep"],
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)
Se uma chamada resume retornar uma sessão nova em vez do histórico esperado, a causa mais comum é um cwd incompatível. As sessões são armazenadas em ~/.claude/projects/<encoded-cwd>/*.jsonl, onde <encoded-cwd> é o diretório de trabalho absoluto com cada caractere não alfanumérico substituído por - (então /Users/me/proj se torna -Users-me-proj). Se sua chamada resume for executada de um diretório diferente, o SDK procura no lugar errado. O arquivo de sessão também precisa existir na máquina atual.
Para retomar sessões entre máquinas ou em ambientes sem servidor, espelhe transcrições para armazenamento compartilhado com um adaptador 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.
Este exemplo se baseia em Capture o ID da sessão: você já analisou um módulo de autenticação em 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:
# Fork: branch from session_id into a new session
forked_id = None
async for message in query(
    prompt="Instead of JWT, implement OAuth2 for the auth module",
    options=ClaudeAgentOptions(
        resume=session_id,
        fork_session=True,
    ),
):
    if isinstance(message, ResultMessage):
        forked_id = message.session_id  # The fork's ID, distinct from session_id
        if message.subtype == "success":
            print(message.result)

print(f"Forked session: {forked_id}")

# Original session is untouched; resuming it continues the JWT thread
async for message in query(
    prompt="Continue with the JWT approach",
    options=ClaudeAgentOptions(resume=session_id),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)

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>.jsonl da primeira execução e restaure-o para o mesmo caminho no novo host antes de chamar resume. O cwd deve 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.
Ambos os SDKs expõem funções para enumerar sessões em disco e ler suas mensagens: 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