​
Gerenciamento de Sessões

O Claude Agent SDK fornece capacidades de gerenciamento de sessões para lidar com o estado da conversa e retomada. As sessões permitem que você continue conversas através de múltiplas interações mantendo o contexto completo.

​
Como as Sessões Funcionam

Quando você inicia uma nova consulta, o SDK automaticamente cria uma sessão e retorna um ID de sessão na mensagem inicial do sistema. Você pode capturar este ID para retomar a sessão mais tarde.

​
Obtendo o ID da Sessão

import { query } from "@anthropic-ai/claude-agent-sdk"

let sessionId: string | undefined

const response = query({
  prompt: "Me ajude a construir uma aplicação web",
  options: {
    model: "claude-sonnet-4-5"
  }
})

for await (const message of response) {
  // A primeira mensagem é uma mensagem de inicialização do sistema com o ID da sessão
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Sessão iniciada com ID: ${sessionId}`)
    // Você pode salvar este ID para retomada posterior
  }

  // Processar outras mensagens...
  console.log(message)
}

// Mais tarde, você pode usar o sessionId salvo para retomar
if (sessionId) {
  const resumedResponse = query({
    prompt: "Continue de onde paramos",
    options: {
      resume: sessionId
    }
  })
}

​
Retomando Sessões

O SDK suporta retomar sessões de estados de conversa anteriores, habilitando fluxos de trabalho de desenvolvimento contínuo. Use a opção resume com um ID de sessão para continuar uma conversa anterior. 
import { query } from "@anthropic-ai/claude-agent-sdk"

// Retomar uma sessão anterior usando seu ID
const response = query({
  prompt: "Continue implementando o sistema de autenticação de onde paramos",
  options: {
    resume: "session-xyz", // ID da sessão da conversa anterior
    model: "claude-sonnet-4-5",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// A conversa continua com contexto completo da sessão anterior
for await (const message of response) {
  console.log(message)
}
O SDK automaticamente lida com o carregamento do histórico da conversa e contexto quando você retoma uma sessão, permitindo que Claude continue exatamente de onde parou.

​
Bifurcando Sessões

Ao retomar uma sessão, você pode escolher continuar a sessão original ou bifurcá-la em uma nova ramificação. Por padrão, retomar continua a sessão original. Use a opção forkSession (TypeScript) ou fork_session (Python) para criar um novo ID de sessão que inicia do estado retomado.

​
Quando Bifurcar uma Sessão

Bifurcar é útil quando você quer:
  • Explorar diferentes abordagens do mesmo ponto de partida
  • Criar múltiplas ramificações de conversa sem modificar a original
  • Testar mudanças sem afetar o histórico da sessão original
  • Manter caminhos de conversa separados para diferentes experimentos

​
Bifurcar vs Continuar

ComportamentoforkSession: false (padrão)forkSession: true
ID da SessãoMesmo da originalNovo ID de sessão gerado
HistóricoAnexa à sessão originalCria nova ramificação do ponto de retomada
Sessão OriginalModificadaPreservada inalterada
Caso de UsoContinuar conversa linearRamificar para explorar alternativas

​
Exemplo: Bifurcando uma Sessão

import { query } from "@anthropic-ai/claude-agent-sdk"

// Primeiro, capturar o ID da sessão
let sessionId: string | undefined

const response = query({
  prompt: "Me ajude a projetar uma 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(`Sessão original: ${sessionId}`)
  }
}

// Bifurcar a sessão para tentar uma abordagem diferente
const forkedResponse = query({
  prompt: "Agora vamos reprojetar isso como uma API GraphQL em vez disso",
  options: {
    resume: sessionId,
    forkSession: true,  // Cria um novo ID de sessão
    model: "claude-sonnet-4-5"
  }
})

for await (const message of forkedResponse) {
  if (message.type === 'system' && message.subtype === 'init') {
    console.log(`Sessão bifurcada: ${message.session_id}`)
    // Este será um ID de sessão diferente
  }
}

// A sessão original permanece inalterada e ainda pode ser retomada
const originalContinued = query({
  prompt: "Adicione autenticação à API REST",
  options: {
    resume: sessionId,
    forkSession: false,  // Continuar sessão original (padrão)
    model: "claude-sonnet-4-5"
  }
})