セッション
セッションは、Agents SDK に 永続的なメモリ層 を提供します。Session インターフェースを実装した任意のオブジェクトを Runner.run に渡すだけで、残りの処理は SDK が行います。セッションがある場合、ランナーは次の処理を自動的に行います。
- 以前に保存された会話項目を取得し、次のターンの入力の先頭に追加します。
- 各実行の完了後に、新しいユーザー入力とアシスタントの出力を永続化します。
- 新しいユーザーテキストでランナーを呼び出す場合も、中断された
RunStateから再開する場合も、以降のターンでセッションを利用できる状態に保ちます。
これにより、toInputList() を手動で呼び出したり、ターン間で履歴をつなぎ合わせたりする必要がなくなります。TypeScript SDK には、Conversations API 向けの OpenAIConversationsSession と、ローカル開発向けの MemorySession という 2 つの実装が付属しています。どちらも Session インターフェースを共有しているため、独自のストレージバックエンドに差し替えられます。Conversations API 以外の実装の参考として、examples/memory/ にあるセッションバックエンドのコード例(Prisma、ファイルベースなど)をご覧ください。OpenAI Responses モデルを使用する場合は、任意のセッションを OpenAIResponsesCompactionSession でラップすると、responses.compact を通じて保存済みの会話履歴を自動的に縮小できます。
ヒント:このページの
OpenAIConversationsSessionのコード例を実行するには、SDK が Conversations API を呼び出せるように、環境変数OPENAI_API_KEYを設定してください(またはセッションの構築時にapiKeyを指定してください)。
クライアント側のメモリ管理を SDK に任せたい場合は、セッションを使用してください。conversationId または previousResponseId を使って、OpenAI のサーバー管理の状態をすでに利用している場合、通常は同じ会話履歴に対してセッションを併用する必要はありません。
クイックスタート
Section titled “クイックスタート”OpenAIConversationsSession を使用して Conversations API とメモリを同期するか、ほかの任意の Session 実装に差し替えてください。
import { Agent, OpenAIConversationsSession, run } from '@openai/agents';
const agent = new Agent({ name: 'TourGuide', instructions: 'Answer with compact travel facts.',});
// Any object that implements the Session interface works here. This example uses// the built-in OpenAIConversationsSession, but you can swap in a custom Session.const session = new OpenAIConversationsSession();
const firstTurn = await run(agent, 'What city is the Golden Gate Bridge in?', { session,});console.log(firstTurn.finalOutput); // "San Francisco"
const secondTurn = await run(agent, 'What state is it in?', { session });console.log(secondTurn.finalOutput); // "California"同じセッションインスタンスを再利用すると、エージェントは各ターンの前に会話履歴全体を受け取り、新しい項目も自動的に永続化されます。別の Session 実装に切り替えても、ほかのコードを変更する必要はありません。
ローカルのデモやテスト、プロセス内のチャット状態の管理には、OpenAI と通信せずに同じインターフェースを提供する MemorySession を使用できます。
import { Agent, MemorySession, run } from '@openai/agents';
const agent = new Agent({ name: 'TourGuide', instructions: 'Answer with compact travel facts.',});
const session = new MemorySession();const result = await run(agent, 'What city is the Golden Gate Bridge in?', { session,});
console.log(result.finalOutput);OpenAIConversationsSession のコンストラクターオプション:
| オプション | 型 | 備考 |
|---|---|---|
conversationId | string | 会話を遅延作成する代わりに、既存の会話を再利用します。 |
client | OpenAI | 設定済みの OpenAI クライアントを渡します。 |
apiKey | string | 内部の OpenAI クライアントを作成する際に使用する API キーです。 |
baseURL | string | OpenAI 互換エンドポイントのベース URL です。 |
organization | string | リクエストに使用する OpenAI 組織 ID です。 |
project | string | リクエストに使用する OpenAI プロジェクト ID です。 |
MemorySession のコンストラクターオプション:
| オプション | 型 | 備考 |
|---|---|---|
sessionId | string | ログやテスト用の固定識別子です。デフォルトでは自動生成されます。 |
initialItems | AgentInputItem[] | 既存の履歴をセッションの初期データとして設定します。 |
logger | Logger | デバッグ出力に使用するロガーを上書きします。 |
MemorySession はすべてをローカルプロセスのメモリに保存するため、プロセスが終了するとリセットされます。
セッションを構築する前に会話 ID を作成する必要がある場合は、startOpenAIConversationsSession(client?) を使用し、返された ID を conversationId として渡してください。
セッションの基本動作
Section titled “セッションの基本動作”ランナーによるセッションの使用方法
Section titled “ランナーによるセッションの使用方法”- 各実行の前に セッション履歴を取得し、新しいターンの入力とマージして、結合したリストをエージェントに渡します。
- 非ストリーミング実行の後に
session.addItems()を 1 回呼び出して、最新のターンの元のユーザー入力とモデル出力の両方を永続化します。 - ストリーミング実行では 最初にユーザー入力を書き込み、ターンが完了するとストリーミングされた出力を追加します。
RunResult.stateから再開する場合(承認やその他の中断への対応)は、同じsessionを渡し続けてください。入力を再準備することなく、再開されたターンがメモリに追加されます。
出力ガードレールが、最終出力となる関数ツールの実行結果を拒否した場合、ランナーは拒否された元の実行結果を新しいセッション履歴に追加しません。認識できた関数呼び出しと実行結果のペアに対しては、リプレイしても安全なプレースホルダーを永続化します。また、現在のレスポンスの末尾部分の帰属が曖昧な場合、帰属先を証明できない出力を保存するのではなく、その部分を省略します。この保護によって、外部ツールの副作用が取り消されたり、アプリケーションがセッションパイプラインの外部に保存したデータが消去されたりすることはありません。
履歴の確認と編集
Section titled “履歴の確認と編集”セッションはシンプルな CRUD ヘルパーを公開しているため、「元に戻す」「チャットをクリア」、監査などの機能を構築できます。
import { OpenAIConversationsSession } from '@openai/agents';import type { AgentInputItem } from '@openai/agents-core';
// Replace OpenAIConversationsSession with any other Session implementation that// supports get/add/pop/clear if you store history elsewhere.const session = new OpenAIConversationsSession({ conversationId: 'conv_123', // Resume an existing conversation if you have one.});
const history = await session.getItems();console.log(`Loaded ${history.length} prior items.`);
const followUp: AgentInputItem[] = [ { type: 'message', role: 'user', content: [{ type: 'input_text', text: 'Let’s continue later.' }], },];await session.addItems(followUp);
const undone = await session.popItem();
if (undone?.type === 'message') { console.log(undone.role); // "user"}
await session.clearSession();session.getItems() は保存済みの AgentInputItem[] を返します。最後の項目を削除するには popItem() を呼び出してください。エージェントを再実行する前にユーザーが内容を修正する場合に便利です。
カスタムストレージとマージ動作
Section titled “カスタムストレージとマージ動作”独自ストレージの使用
Section titled “独自ストレージの使用”Session インターフェースを実装すると、Redis、DynamoDB、SQLite、その他のデータストアをメモリの保存先として使用できます。必要なのは 5 つの非同期メソッドだけです。
import { Agent, run } from '@openai/agents';import { randomUUID } from '@openai/agents-core/_shims';import { getLogger } from '@openai/agents-core';import type { AgentInputItem, Session } from '@openai/agents-core';
/** * Minimal example of a Session implementation; swap this class for any storage-backed version. */export class CustomMemorySession implements Session { private readonly sessionId: string; private readonly logger: ReturnType<typeof getLogger>;
private items: AgentInputItem[];
constructor( options: { sessionId?: string; initialItems?: AgentInputItem[]; logger?: ReturnType<typeof getLogger>; } = {}, ) { this.sessionId = options.sessionId ?? randomUUID(); this.items = options.initialItems ? options.initialItems.map(cloneAgentItem) : []; this.logger = options.logger ?? getLogger('openai-agents:memory-session'); }
async getSessionId(): Promise<string> { return this.sessionId; }
async getItems(limit?: number): Promise<AgentInputItem[]> { if (limit === undefined) { const cloned = this.items.map(cloneAgentItem); this.logger.debug( `Getting items from memory session (${this.sessionId}): ${JSON.stringify(cloned)}`, ); return cloned; } if (limit <= 0) { return []; } const start = Math.max(this.items.length - limit, 0); const items = this.items.slice(start).map(cloneAgentItem); this.logger.debug( `Getting items from memory session (${this.sessionId}): ${JSON.stringify(items)}`, ); return items; }
async addItems(items: AgentInputItem[]): Promise<void> { if (items.length === 0) { return; } const cloned = items.map(cloneAgentItem); this.logger.debug( `Adding items to memory session (${this.sessionId}): ${JSON.stringify(cloned)}`, ); this.items = [...this.items, ...cloned]; }
async popItem(): Promise<AgentInputItem | undefined> { if (this.items.length === 0) { return undefined; } const item = this.items[this.items.length - 1]; const cloned = cloneAgentItem(item); this.logger.debug( `Popping item from memory session (${this.sessionId}): ${JSON.stringify(cloned)}`, ); this.items = this.items.slice(0, -1); return cloned; }
async clearSession(): Promise<void> { this.logger.debug(`Clearing memory session (${this.sessionId})`); this.items = []; }}
function cloneAgentItem<T extends AgentInputItem>(item: T): T { return structuredClone(item);}
const agent = new Agent({ name: 'MemoryDemo', instructions: 'Remember the running total.',});
// Using the above custom memory session implementation hereconst session = new CustomMemorySession({ sessionId: 'session-123-4567',});
const first = await run(agent, 'Add 3 to the total.', { session });console.log(first.finalOutput);
const second = await run(agent, 'Add 4 more.', { session });console.log(second.finalOutput);カスタムセッションでは、保持ポリシーの適用、暗号化の追加、永続化前の各会話ターンへのメタデータの付与が可能です。
カスタム永続化のアトミック性と冪等性の確保
Section titled “カスタム永続化のアトミック性と冪等性の確保”履歴の更新と操作識別子の記録をアトミックに行えるバックエンドでは、オプションの SessionHistoryTransactionAwareSession インターフェースを実装してください。その applyHistoryTransaction(...) メソッドは、固定の operationId と、次の 2 つの形式のいずれかのトランザクションを受け取ります。
append_itemsは、履歴項目のグループを追加します。replace_suffixは、現在保存されている履歴の末尾部分が想定どおりの内容と一致している場合に限り、その部分を置き換えます。
操作識別子と履歴の変更は、同じバックエンドトランザクションで永続化してください。同じ操作識別子で同じトランザクションを繰り返した場合、変更を二重に適用せずに成功する必要があります。異なる内容で識別子を再利用した場合や、想定していた履歴の末尾部分が変更された後に replace_suffix を適用した場合は、履歴を変更せずに失敗する必要があります。これにより、ランナーは再試行や再開可能な出力ガードレールフローにまたがって、永続化された出力の整合性を安全に保てます。
MemorySession は、リファレンスとしてこの契約を実装しています。既存の Session 実装はこのインターフェースがなくても引き続き有効ですが、トランザクション対応の永続化処理は利用しません。
実行コンテキストによるカスタムセッションのスコープ設定
Section titled “実行コンテキストによるカスタムセッションのスコープ設定”カスタムセッションがストレージのルーティングやメタデータのためにアクティブな RunContext を必要とする場合は、RunContextAwareSession<TContext> を実装し、acceptsRunContext を true に設定してください。ランナーは、ストリーミング中の永続化や再開された実行を含め、実行中のすべての履歴操作に同じコンテキストインスタンスを渡します。Session のみを実装するセッションは既存のメソッドシグネチャを維持し、追加の引数なしで呼び出されます。
import { Agent, run, type AgentInputItem, type RunContext, type RunContextAwareSession,} from '@openai/agents';
type TenantContext = { tenantId: string;};
class TenantSession implements RunContextAwareSession<TenantContext> { readonly acceptsRunContext = true; private readonly itemsByTenant = new Map<string, AgentInputItem[]>();
async getSessionId(): Promise<string> { return 'shared-tenant-session'; }
async getItems( limit?: number, runContext?: RunContext<TenantContext>, ): Promise<AgentInputItem[]> { const items = this.getTenantItems(runContext); return limit === undefined ? [...items] : items.slice(-limit); }
async addItems( items: AgentInputItem[], runContext?: RunContext<TenantContext>, ): Promise<void> { this.getTenantItems(runContext).push(...items); }
async popItem( runContext?: RunContext<TenantContext>, ): Promise<AgentInputItem | undefined> { return this.getTenantItems(runContext).pop(); }
async clearSession(runContext?: RunContext<TenantContext>): Promise<void> { this.itemsByTenant.set(this.getTenantId(runContext), []); }
private getTenantItems( runContext: RunContext<TenantContext> | undefined, ): AgentInputItem[] { const tenantId = this.getTenantId(runContext); const items = this.itemsByTenant.get(tenantId) ?? []; this.itemsByTenant.set(tenantId, items); return items; }
private getTenantId( runContext: RunContext<TenantContext> | undefined, ): string { if (!runContext) { throw new Error('TenantSession requires a run context.'); } return runContext.context.tenantId; }}
const agent = new Agent<TenantContext>({ name: 'Assistant', instructions: 'Reply concisely.',});const session = new TenantSession();
await run(agent, 'Remember that my favorite color is green.', { context: { tenantId: 'tenant-a' }, session,});
await run(agent, 'What is my favorite color?', { context: { tenantId: 'tenant-a' }, session,});OpenAIResponsesCompactionSession は、基になるセッションに実行コンテキストを転送しません。これらの機能を組み合わせる場合は、コンテキストのスコープごとに 1 つの圧縮セッションインスタンスを使用してください。
履歴と新しい項目のマージ方法の制御
Section titled “履歴と新しい項目のマージ方法の制御”AgentInputItem の配列を実行の入力として渡す場合は、保存済みの履歴と決定論的にマージするための sessionInputCallback を指定してください。ランナーは既存の履歴を読み込み、 モデルの呼び出し前に コールバックを呼び出し、返された配列をそのターンの完全な入力としてモデルに渡します。このフックは、古い項目の削除、ツールの実行結果の重複排除、モデルに見せたいコンテキストだけを強調する場合に最適です。
import { Agent, OpenAIConversationsSession, run } from '@openai/agents';import type { AgentInputItem } from '@openai/agents-core';
const agent = new Agent({ name: 'Planner', instructions: 'Track outstanding tasks before responding.',});
// Any Session implementation can be passed here; customize storage as needed.const session = new OpenAIConversationsSession();
const todoUpdate: AgentInputItem[] = [ { type: 'message', role: 'user', content: [ { type: 'input_text', text: 'Add booking a hotel to my todo list.' }, ], },];
await run(agent, todoUpdate, { session, // function that combines session history with new input items before the model call sessionInputCallback: (history, newItems) => { const recentHistory = history.slice(-8); return [...recentHistory, ...newItems]; },});文字列入力の場合はランナーが履歴を自動的にマージするため、コールバックは省略できます。コールバックは、ターンの入力がすでに項目の配列になっている場合にのみ実行されます。
conversationId または previousResponseId も使用している場合は、現在のターンの新しい項目を少なくとも 1 つ、コールバックの戻り値に含めてください。これらのサーバー管理の API は、現在のターンの差分に依存します。コールバックが新しい項目をすべて削除した場合、SDK は空の差分を送信する代わりに、元の新しい入力を復元して警告をログに記録します。
再開可能な実行
Section titled “再開可能な実行”承認と再開可能な実行の処理
Section titled “承認と再開可能な実行の処理”Human in the loop (人間の介入) のフローでは、承認を待つために実行を一時停止することがよくあります。
import { Agent, MemorySession, Runner } from '@openai/agents';
const agent = new Agent({ name: 'Trip Planner', instructions: 'Plan trips and ask for approval before booking anything.',});
const runner = new Runner();const session = new MemorySession();
const result = await runner.run(agent, 'Search the itinerary', { session,});
if (result.interruptions?.length) { // ... collect user feedback, then resume the agent in a later turn. for (const interruption of result.interruptions) { result.state.approve(interruption); }
const continuation = await runner.run(agent, result.state, { session }); console.log(continuation.finalOutput);}以前の RunState から再開すると、新しいターンが同じメモリレコードに追加され、単一の会話履歴が維持されます。人間の介入(HITL)におけるほとんどの承認チェックポイントでは、RunState を介して中断と再開が行われ、その間もセッションが完全な会話履歴を保持します。
承認された関数ツールの実行結果が最終出力になり得る場合、出力ガードレールはより厳格な境界を設けます。現在の RunState スキーマは、生成項目が現在のレスポンスに帰属することを SDK が証明できる場合に、その正確な帰属情報を記録します。これにより、サポートされている出力を伴う承認チェックポイントでは、セッション履歴を保持したまま再開できます。SDK は、モデル、ツール、セッションに対してさらに副作用を発生させる前に、その帰属情報を検証します。古いスナップショットや、帰属情報が欠落している、不正である、または曖昧であるチェックポイントでは、引き続き安全側に倒して処理を拒否します。SDK がこの状態を報告した場合は、安全な入力から新しい実行を開始してください。元の項目をリプレイして回避しようとしないでください。
応用:履歴の圧縮
Section titled “応用:履歴の圧縮”OpenAI Responses の履歴の自動圧縮
Section titled “OpenAI Responses の履歴の自動圧縮”OpenAIResponsesCompactionSession は任意の Session をラップし、OpenAI Responses API を使用して、保存済みの長い履歴を、それと同等の内容を持つ、より短い会話項目のリストに置き換えます。各ターンの永続化後、ランナーは最新の responseId を runCompaction に渡します。判断用フックが true を返すと、runCompaction が responses.compact を呼び出します。compactionMode に応じて、リクエストは最新の Responses API チェーン、またはセッションの現在の項目から構築されます。デフォルトのトリガーは、ユーザー以外の項目が 10 件以上蓄積すると圧縮を行います。トークン数やカスタムのヒューリスティクスに基づいて判断するには、shouldTriggerCompaction を上書きしてください。圧縮処理が返った後、デコレーターは基になるセッションをクリアし、削減された項目リストで書き直します。そのため、異なるサーバー管理の履歴フローを使用する OpenAIConversationsSession との併用は避けてください。
import { Agent, MemorySession, OpenAIResponsesCompactionSession, run,} from '@openai/agents';
const agent = new Agent({ name: 'Support', instructions: 'Answer briefly and keep track of prior context.', model: 'gpt-5.4',});
// Wrap any Session to trigger responses.compact once history grows beyond your threshold.const session = new OpenAIResponsesCompactionSession({ // You can pass any Session implementation except OpenAIConversationsSession underlyingSession: new MemorySession(), // (optional) The model used for calling responses.compact API model: 'gpt-5.4', // (optional) your custom logic here shouldTriggerCompaction: ({ compactionCandidateItems }) => { return compactionCandidateItems.length >= 12; },});
await run(agent, 'Summarize order #8472 in one sentence.', { session });await run(agent, 'Remind me of the shipping address.', { session });
// Compaction runs automatically after each persisted turn. You can also force it manually.await session.runCompaction({ force: true });OpenAIResponsesCompactionSession のコンストラクターオプション:
| オプション | 型 | 備考 |
|---|---|---|
client | OpenAI | responses.compact に使用する OpenAI クライアントです。 |
underlyingSession | Session | 圧縮された項目でクリア・書き直しを行う、基になるセッションストアです。デフォルトはデモ用のインメモリセッションです。OpenAIConversationsSession は指定できません。 |
model | OpenAI.ResponsesModel | 圧縮リクエストに使用するモデルです。デフォルトは SDK の現在のデフォルトの OpenAI モデルです。 |
compactionMode | 'auto' | 'previous_response_id' | 'input' | 圧縮にサーバーのレスポンスチェーンを使用するか、ローカルの入力項目を使用するかを制御します。 |
shouldTriggerCompaction | (context) => boolean | Promise<boolean> | responseId、compactionMode、候補項目、現在のセッション項目に基づくカスタムトリガーフックです。 |
compactionMode: 'previous_response_id' は、Responses API のレスポンス ID でターンをすでにつなげている場合に便利です。compactionMode: 'input' は、代わりに現在のセッション項目から圧縮リクエストを再構築します。これは、レスポンスチェーンが利用できない場合や、基になるセッションの内容を信頼できる情報源としたい場合に役立ちます。
runCompaction(args) のオプション:
| オプション | 型 | 備考 |
|---|---|---|
responseId | string | previous_response_id モードで使用する、最新の Responses API レスポンス ID です。 |
compactionMode | 'auto' | 'previous_response_id' | 'input' | 設定済みのモードを呼び出しごとに上書きするための省略可能なオプションです。 |
store | boolean | 直前の実行でサーバーの状態を保存したかどうかを示します。 |
force | boolean | shouldTriggerCompaction を無視して、直ちに圧縮します。 |
OpenAIResponsesCompactionSession は、同じラッパーインスタンスを通じて発行された変更操作を直列化します。runCompaction()、addItems()、popItem()、clearSession() の呼び出しは呼び出し順に実行され、操作が拒否された後もキューの処理は続きます。そのため、後続のラッパー経由の変更操作が、置換やロールバックに割り込むことはありません。置換またはロールバックが成功すると、ラッパーのキャッシュ済み履歴は基になるセッションと整合した状態に保たれます。置換と復元の両方が失敗した場合は、処理を続ける前に基になるセッションを復旧してください。この順序保証は、別のラッパーインスタンスや underlyingSession の直接変更とは連携しません。それらのアクセス経路の調整は、アプリケーションで行ってください。
自動圧縮では、読み取った履歴スナップショットの所有権を、その実行が引き続き持っているかどうかも検証します。自動圧縮が始まる前に別の操作がラッパーの履歴を変更した場合、SDK は新しい履歴を保持し、その圧縮処理をスキップします。更新された履歴は、後続の実行や明示的な runCompaction() の呼び出しで圧縮できます。
低レイテンシーのストリーミングのための手動圧縮
Section titled “低レイテンシーのストリーミングのための手動圧縮”圧縮は基になるセッションをクリアして書き直すため、SDK は圧縮が終わるまでストリーミング実行の完了を待ちます。圧縮処理が重い場合、最後の出力トークンの後も result.completed が数秒間保留状態になることがあります。ストリーミングのレイテンシーを低く抑えたり、ターンの切り替えを速めたりするには、自動圧縮を無効にして、ターン間(またはアイドル時間中)に自分で runCompaction を呼び出してください。
import { Agent, MemorySession, OpenAIResponsesCompactionSession, run,} from '@openai/agents';
const agent = new Agent({ name: 'Support', instructions: 'Answer briefly and keep track of prior context.', model: 'gpt-5.4',});
// Disable auto-compaction to avoid delaying stream completion.const session = new OpenAIResponsesCompactionSession({ underlyingSession: new MemorySession(), shouldTriggerCompaction: () => false,});
const result = await run(agent, 'Share the latest ticket update.', { session, stream: true,});
// Wait for the streaming run to finish before compacting.await result.completed;
// Choose force based on your own thresholds or heuristics, between turns or during idle time.await session.runCompaction({ force: true });アーカイブやハンドオフの前に履歴を縮小するため、いつでも runCompaction({ force: true }) を呼び出せます。圧縮の判断を追跡するには、DEBUG=openai-agents:openai:compaction でデバッグログを有効にしてください。