Gerenciamento de Sessões
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
}
})
}from claude_agent_sdk import query, ClaudeAgentOptions
session_id = None
async for message in query(
prompt="Me ajude a construir uma aplicação web",
options=ClaudeAgentOptions(
model="claude-sonnet-4-5"
)
):
# A primeira mensagem é uma mensagem de inicialização do sistema com o ID da sessão
if hasattr(message, 'subtype') and message.subtype == 'init':
session_id = message.data.get('session_id')
print(f"Sessão iniciada com ID: {session_id}")
# Você pode salvar este ID para retomada posterior
# Processar outras mensagens...
print(message)
# Mais tarde, você pode usar o session_id salvo para retomar
if session_id:
async for message in query(
prompt="Continue de onde paramos",
options=ClaudeAgentOptions(
resume=session_id
)
):
print(message)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
| Comportamento | forkSession: false (padrão) | forkSession: true |
|---|---|---|
| ID da Sessão | Mesmo da original | Novo ID de sessão gerado |
| Histórico | Anexa à sessão original | Cria nova ramificação do ponto de retomada |
| Sessão Original | Modificada | Preservada inalterada |
| Caso de Uso | Continuar conversa linear | Ramificar 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"
}
})