メインコンテンツへスキップ
query() はデフォルトで毎回の呼び出し時に新しいセッションを開始します。options のいくつかのフィールドを通じて、セッション ID の指定、履歴セッションの復元、既存セッションからのフォークが可能です。

​
コンセプト

1つのセッションは CLI 側で永続化された1つの対話履歴（コンテキスト、ツール呼び出し記録、圧縮境界などを含む）に対応し、UUID で識別されます。システムメッセージ init に今回の session_id が含まれ、これが後続の resume / fork のアンカーポイントとなります。 以下の例にある auth: accessTokenFromEnv() は、プロジェクトで使用している他の認証方法に置き換えることもできます。詳細は 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',
  },
});

​
最後のセッションの復元

セッション ID が不明な場合、continue: true で最後に変更されたセッションに接続します： 
const q = query({
  prompt: 'Continue',
  options: {
    auth: accessTokenFromEnv(),
    continue: true,
  },
});
resume と continue は同時に渡さないでください。

​
セッションのフォーク

既存のセッションから新しいセッションを派生させ、元のコンテキストを保持しつつ新しいセッション 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',
}

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

フィールド型動作
sessionIdstring単独使用：この ID で新規作成。forkSession と併用：フォーク後の新セッションの ID
resumestring復元するセッション ID
continuebooleantrue で最後のセッションを復元
forkSessionbooleanresume と併用し、接続ではなくフォーク

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

init メッセージを監視します： 
for await (const msg of q) {
  if (msg.type === 'system' && msg.subtype === 'init') {
    console.log('session_id:', msg.session_id);
  }
}

​
セッションタイトルの生成

ホストアプリケーションが既存セッションの短い表示タイトルを必要とする場合、q.generateSessionTitle() を呼び出します： 
const title = await q.generateSessionTitle(
  'User asked the agent to review authentication middleware and fix failing tests.',
);
CLI は control response で生成結果を返します。現在の headless control 経路ではこのタイトルは永続化されません。永続化された ai-title transcript entry は、引き続き session list 系 API から取得できます。

​
subagent transcript の読み取り

Subagent は親セッション配下に専用 transcript を書き込みます。親セッション完了後、まず listSubagents() で subagent ID を取得し、次に getSubagentMessages() で対象 subagent のメッセージ列を読み取ります： 
import { getSubagentMessages, listSubagents } from '@qoder-ai/qoder-agent-sdk';

const agentIds = await listSubagents(sessionId, { dir: '/path/to/project' });

for (const agentId of agentIds) {
  const messages = await getSubagentMessages(sessionId, agentId, {
    dir: '/path/to/project',
  });

  console.log(agentId, messages.length);
}
getSubagentMessages() は subagent transcript の parent チェーンをたどり、user / assistant メッセージを時系列で返します。