セッション管理

Claude Agent SDKは、会話状態とその再開を処理するためのセッション管理機能を提供します。セッションを使用すると、完全なコンテキストを維持しながら、複数のインタラクション全体で会話を続行できます。

セッションの仕組み

新しいクエリを開始すると、SDKは自動的にセッションを作成し、初期システムメッセージでセッションIDを返します。このIDをキャプチャして、後でセッションを再開できます。

セッションIDの取得

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

let sessionId: string | undefined

const response = query({
  prompt: "Help me build a web application",
  options: {
    model: "claude-sonnet-4-5"
  }
})

for await (const message of response) {
  // The first message is a system init message with the session ID
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Session started with ID: ${sessionId}`)
    // You can save this ID for later resumption
  }

  // Process other messages...
  console.log(message)
}

// Later, you can use the saved sessionId to resume
if (sessionId) {
  const resumedResponse = query({
    prompt: "Continue where we left off",
    options: {
      resume: sessionId
    }
  })
}

セッションの再開

SDKは以前の会話状態からセッションを再開することをサポートしており、継続的な開発ワークフローを実現します。resumeオプションとセッションIDを使用して、以前の会話を続行します。

SDKは、セッションを再開するときに会話履歴とコンテキストの読み込みを自動的に処理し、Claudeが正確に中断したところから続行できるようにします。

セッション全体でファイルの変更を追跡し、元に戻すには、ファイルチェックポイントを参照してください。

セッションのフォーク

セッションを再開するときに、元のセッションを続行するか、新しいブランチにフォークするかを選択できます。デフォルトでは、再開すると元のセッションが続行されます。forkSessionオプション（TypeScript）またはfork_sessionオプション（Python）を使用して、再開状態から開始する新しいセッションIDを作成します。

セッションをフォークする場合

フォークは以下の場合に便利です：

同じ開始点から異なるアプローチを探索したい
元のセッションを変更せずに複数の会話ブランチを作成したい
元のセッション履歴に影響を与えずに変更をテストしたい
異なる実験用に個別の会話パスを維持したい

フォークと継続の比較

動作	`forkSession: false`（デフォルト）	`forkSession: true`
セッションID	元のセッションと同じ	新しいセッションIDが生成される
履歴	元のセッションに追加される	再開ポイントから新しいブランチを作成
元のセッション	変更される	変更されずに保持される
ユースケース	線形会話を続行	代替案を探索するためにブランチ化

例：セッションのフォーク

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

// Resume a previous session using its ID
const response = query({
  prompt: "Continue implementing the authentication system from where we left off",
  options: {
    resume: "session-xyz", // Session ID from previous conversation
    model: "claude-sonnet-4-5",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// The conversation continues with full context from the previous session
for await (const message of response) {
  console.log(message)
}

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

// First, capture the session ID
let sessionId: string | undefined

const response = query({
  prompt: "Help me design a REST API",
  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(`Original session: ${sessionId}`)
  }
}

// Fork the session to try a different approach
const forkedResponse = query({
  prompt: "Now let's redesign this as a GraphQL API instead",
  options: {
    resume: sessionId,
    forkSession: true,  // Creates a new session ID
    model: "claude-sonnet-4-5"
  }
})

for await (const message of forkedResponse) {
  if (message.type === 'system' && message.subtype === 'init') {
    console.log(`Forked session: ${message.session_id}`)
    // This will be a different session ID
  }
}

// The original session remains unchanged and can still be resumed
const originalContinued = query({
  prompt: "Add authentication to the REST API",
  options: {
    resume: sessionId,
    forkSession: false,  // Continue original session (default)
    model: "claude-sonnet-4-5"
  }
})