Skip to main content
会話とセッション

セッション制御

SDK はデフォルトで、呼び出し（TypeScript の query()）または接続（Python の QoderSDKClient）のたびに新しいセッションを開始します。options のいくつかのフィールドで、セッション ID の指定、過去セッションの再開、既存セッションからのフォークができます。

コンセプト

1つのセッションは CLI 側で永続化された1つの対話履歴（コンテキスト、ツール呼び出し記録、圧縮境界などを含む）に対応し、UUID で識別されます。システムメッセージ init に今回の session_id が含まれ、これが後続の resume / fork のアンカーポイントとなります。 以下の例の認証方式は、プロジェクトで使っている他の認証方式に置き換えられます。SDK 認証 を参照してください。

新規セッションの作成

デフォルト

セッション関連フィールドを渡さない場合、毎回新規作成されます： 
import { accessTokenFromEnv, query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Hello',
  options: { auth: accessTokenFromEnv() },
});

セッション ID の指定

呼び出し側がセッションの UUID を決定します（ホストが独自にセッションインデックスを管理する場合に適します）： 
import { randomUUID } from 'node:crypto';

const sessionId = randomUUID();
const q = query({
  prompt: 'Hello',
  options: {
    auth: accessTokenFromEnv(),
    sessionId,
  },
});

セッションの復元

ID による復元

const q = query({
  prompt: 'Continue the previous conversation',
  options: {
    auth: accessTokenFromEnv(),
    resume: 'previous-session-id',
  },
});

最後のセッションの復元

session ID が分からない場合は、continue: true（TypeScript）/ continue_conversation=True（Python）で最後に変更されたセッションを引き継ぎます： 
const q = query({
  prompt: 'Continue',
  options: {
    auth: accessTokenFromEnv(),
    continue: true,
  },
});
resume と continue（Python では continue_conversation）を同時に渡さないでください。

セッションのフォーク

既存のセッションから新しいセッションを派生させ、元のコンテキストを保持しつつ新しいセッション ID を取得します。元のセッションは影響を受けません： 
const q = query({
  prompt: 'Based on the prior context, explore a different direction',
  options: {
    auth: accessTokenFromEnv(),
    resume: 'source-session-id',
    forkSession: true,
  },
});
フォーク後の新しいセッションに ID を指定する場合： 
options: {
  auth: accessTokenFromEnv(),
  resume: 'source-session-id',
  forkSession: true,
  sessionId: 'my-new-session-id',
}

フィールドクイックリファレンス

フィールド（TypeScript / Python）型動作
sessionId / session_idstring / str単独使用：この ID で新規作成。フォーク用フィールドと併用：フォーク後の新セッションの ID
resume / resumestring / str再開するセッション ID
continue / continue_conversationboolean / booltrue で直近のセッションを再開
forkSession / fork_sessionboolean / boolresume と組み合わせて、継続ではなくフォーク

現在のセッション ID の取得

init システムメッセージを監視します。Python では ResultMessage にも session_id が含まれ、どちらも記録に使えます： 
for await (const msg of q) {
  if (msg.type === 'system' && msg.subtype === 'init') {
    console.log('session_id:', msg.session_id);
  }
}

ユーザーデータディレクトリ

ユーザーデータディレクトリには、セッション履歴、リソース、ログなどの CLI ユーザーレベルデータが保存されます。options.env で QODER_CONFIG_DIR を設定すると、このディレクトリを指定できます。 
import { accessTokenFromEnv, query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Analyze this repository',
  options: {
    auth: accessTokenFromEnv(),
    env: {
      ...process.env,
      QODER_CONFIG_DIR: '/var/lib/my-agent/qoder',
    },
  },
});
クイックスタート
基本概念
会話とセッション
ツールと拡張機能
制御と安全性
リファレンス