openai-responses

OpenAI Responses API

ステータス：本番環境対応済み 最終更新日：2026-01-21 API 公開日：2025年3月 依存関係：[email protected]（Node.js）または fetch API（Cloudflare Workers）

---

Responses API とは？

エージェント型アプリケーション向けに OpenAI が提供する統合インターフェースです。2025年3月に公開されました。ターンをまたいで推論状態を保持する、ステートフルな会話を実現します。

主な革新点： Chat Completions とは異なり（ターン間で推論が破棄されます）、Responses はモデルの推論ノートを保持するため、TAUBench での性能が5%向上し、複数ターンにわたるやり取りの質も高まります。

Chat Completions との比較：

機能	Chat Completions	Responses API
状態	履歴を手動で管理	自動（会話 ID）
推論	ターン間で破棄	ターン間で保持（TAUBench で +5%）
ツール	クライアント側で往復	サーバー側でホスト
出力	単一メッセージ	多相型（8 種類）
キャッシュ	基準	利用効率が 40～80% 向上
MCP	手動	組み込み

---

クイックスタート

npm install [email protected]

import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'What are the 5 Ds of dodgeball?',
});

console.log(response.output_text);

Chat Completions との主な違い：

• エンドポイント：/v1/responses（/v1/chat/completions ではありません）
• パラメーター：input（messages ではありません）
• ロール：developer（system ではありません）
• 出力：response.output_text（choices[0].message.content ではありません）

---

Responses と Chat Completions の使い分け

Responses を使う場合：

• エージェント型アプリケーション（推論 + アクション）
• 複数ターンにわたる会話（推論の保持により TAUBench で +5%）
• 組み込みツール（Code Interpreter、File Search、Web Search、MCP）
• バックグラウンド処理（標準 60 秒、延長タイムアウト 10 分）

Chat Completions を使う場合：

• 単発のシンプルな生成
• 完全にステートレスなやり取り
• レガシーな連携

---

ステートフルな会話

会話 ID を使用した自動状態管理：

// Create conversation
const conv = await openai.conversations.create({
  metadata: { user_id: 'user_123' },
});

// First turn
const response1 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id,
  input: 'What are the 5 Ds of dodgeball?',
});

// Second turn - model remembers context + reasoning
const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id,
  input: 'Tell me more about the first one',
});

メリット： 履歴を手動で管理する必要がなく、推論が保持され、キャッシュ利用効率が 40～80% 向上します。

会話の制限： 90 日で有効期限が切れます

---

組み込みツール（サーバー側）

サーバー側でホストされるツールにより、バックエンドとの往復が不要になります。

ツール	用途	備考
code_interpreter	Python コードを実行	サンドボックス化、タイムアウト 30 秒（より長い時間が必要な場合は background: true を使用）
file_search	ベクトルストアを使わない RAG	ファイルあたり最大 512MB、PDF／Word／Markdown／HTML／コードに対応
web_search	リアルタイムのウェブ情報	ソースを自動引用
image_generation	DALL-E との連携	デフォルトは DALL-E 3
mcp	外部ツールに接続	OAuth に対応、トークンは保存されません

使用方法：

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Calculate mean of: 10, 20, 30, 40, 50',
  tools: [{ type: 'code_interpreter' }],
});

Web Search の TypeScript に関する注意

TypeScript の制限： web_search ツールの external_web_access オプションは SDK の型定義にありません（v6.16.0 時点）。

回避策：

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Search for recent news',
  tools: [{
    type: 'web_search',
    external_web_access: true,
  } as any],  // ✅ Type assertion to suppress error
});

参照元： GitHub Issue #1716

---

MCP サーバーとの連携

外部ツール（Stripe、データベース、カスタム API）に接続する**Model Context Protocol（MCP）**サーバーを標準でサポートしています。

ユーザーの承認要件

デフォルトでは、リモート MCP サーバーとデータを共有する前に、ユーザーによる明示的な承認が必要です（セキュリティ機能）。

承認の処理：

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Get my Stripe balance',
  tools: [{
    type: 'mcp',
    server_label: 'stripe',
    server_url: 'https://mcp.stripe.com',
    authorization: process.env.STRIPE_TOKEN,
  }],
});

if (response.status === 'requires_approval') {
  // Show user: "This action requires sharing data with Stripe. Approve?"
  // After user approves, retry with approval token
}

別の方法： OpenAI ダッシュボードで MCP サーバーを事前承認します（ユーザーは設定から信頼するサーバーを登録できます）。

参照元： 公式 MCP ガイド

MCP の基本的な使い方

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Roll 2d6 dice',
  tools: [{
    type: 'mcp',
    server_label: 'dice',
    server_url: 'https://example.com/mcp',
    authorization: process.env.TOKEN, // ⚠️ NOT stored, required each request
  }],
});

MCP の出力タイプ：

• mcp_list_tools - サーバー上で検出されたツール
• mcp_call - ツールの呼び出しと結果
• message - 最終応答

---

推論の保持

主な革新点： モデルの内部推論状態がターンをまたいで保持されます（推論が破棄される Chat Completions とは異なります）。

イメージ：

• Chat Completions：応答する前に、モデルがメモ用紙を破り捨てます
• Responses API：次のターンでもメモ用紙を開いたままにします

性能： 推論を保持するだけで、TAUBench で GPT-5 の性能が +5% 向上します。

推論の要約（無料）：

response.output.forEach(item => {
  if (item.type === 'reasoning') console.log(item.summary[0].text);
  if (item.type === 'message') console.log(item.content[0].text);
});

重要：推論トレースのプライバシー

得られるもの：推論の要約（内部トレース全体ではありません） OpenAI が保持するもの：完全な思考連鎖による推論（セキュリティとプライバシー保護のための独自情報）

GPT-5-Thinking モデルの場合：

• OpenAI は推論をバックエンドで内部的に保持します
• この保持された推論により、複数ターンでのパフォーマンスが向上します（TAUBench で +5%）
• ただし、開発者が受け取るのは要約のみで、実際の思考連鎖は受け取れません
• 完全な推論トレースは公開されません（OpenAI の知的財産保護）

出典：Sean Goedecke による分析

---

バックグラウンドモード

長時間実行されるタスクには、background: true を使用します。

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Analyze 500-page document',
  background: true,
  tools: [{ type: 'file_search', file_ids: [fileId] }],
});

// Poll for completion (check every 5s)
const result = await openai.responses.retrieve(response.id);
if (result.status === 'completed') console.log(result.output_text);

タイムアウト制限：

• 標準：60 秒
• バックグラウンド：10 分

パフォーマンスに関する考慮事項

初回トークン応答時間（TTFT）のレイテンシ： 現在、バックグラウンドモードの TTFT は同期応答よりも長くなっています。OpenAI はこの差を縮めるために取り組んでいます。

推奨事項：

• ユーザー向けのリアルタイム応答には、同期モードを使用します（レイテンシが低い）
• 長時間実行される非同期タスクには、バックグラウンドモードを使用します（レイテンシが許容されます）

出典：OpenAI バックグラウンドモードのドキュメント

---

データの保持とプライバシー

デフォルトの保持期間：store: true（デフォルト）の場合は 30 日間 ゼロデータ保持（ZDR）：ZDR を利用する組織では、store: false が自動的に適用されます バックグラウンドモード：ZDR には対応していません（ポーリングのため、約 10 分間データを保存します）

タイムライン：

• 2025 年 9 月 26 日：OpenAI に対する裁判所命令によるデータ保持が終了
• 現在：store: true の場合、デフォルトで 30 日間保持

ストレージの制御：

// Disable storage (no retention)
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Hello!',
  store: false,  // ✅ No retention
});

// ZDR organizations: store always treated as false
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Hello!',
  store: true,  // ⚠️ Ignored by OpenAI for ZDR orgs, treated as false
});

ZDR への準拠：

• バックグラウンドモードは使用しないでください（一時的なストレージが必要です）
• 明確にするため、store: false を明示的に設定してください
• 注：同期モードでは 60 秒のタイムアウトが適用されます

出典：OpenAI のデータ管理

---

多相出力

単一のメッセージではなく、8 種類の出力タイプを返します。

タイプ	例
message	最終回答、説明
reasoning	段階的な思考プロセス（無料！）
code_interpreter_call	Python コードと結果
mcp_call	ツール名、引数、出力
mcp_list_tools	MCP サーバーからのツール定義
file_search_call	一致したチャンク、引用
web_search_call	URL、スニペット
image_generation_call	画像 URL

処理：

response.output.forEach(item => {
  if (item.type === 'reasoning') console.log(item.summary[0].text);
  if (item.type === 'web_search_call') console.log(item.results);
  if (item.type === 'message') console.log(item.content[0].text);
});

// Or use helper for text-only
console.log(response.output_text);

---

Chat Completions からの移行

互換性を破る変更：

機能	Chat Completions	Responses API
エンドポイント	/v1/chat/completions	/v1/responses
パラメーター	messages	input
ロール	system	developer
出力	choices[0].message.content	output_text
状態	手動の配列	自動（会話 ID）
ストリーミング	data: {"choices":[...]}	8 種類の項目を含む SSE

例：

// Before
const response = await openai.chat.completions.create({
  model: 'gpt-5',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Hello!' },
  ],
});
console.log(response.choices[0].message.content);

// After
const response = await openai.responses.create({
  model: 'gpt-5',
  input: [
    { role: 'developer', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Hello!' },
  ],
});
console.log(response.output_text);

---

Assistants API からの移行

重要：Assistants API の終了スケジュール

• 2025 年 8 月 26 日：Assistants API が正式に非推奨になります
• 2025～2026 年：OpenAI が移行用ユーティリティを提供します
• 2026 年 8 月 26 日：Assistants API が終了します（動作を停止します）

破壊的変更を避けるため、2026 年 8 月 26 日までに移行してください。

出典：Assistants API の終了に関する発表

主な互換性を破る変更：

Assistants API	Responses API
Assistants（API 経由で作成）	プロンプト（ダッシュボードで作成）
スレッド	会話（メッセージだけでなく、項目を保存）
Run（サーバーサイドのライフサイクル）	Response（ステートレスな呼び出し）
Run-Steps	項目（多相出力）

移行例：

// Before (Assistants API - deprecated)
const assistant = await openai.beta.assistants.create({
  model: 'gpt-4',
  instructions: 'You are helpful.',
});

const thread = await openai.beta.threads.create();

const run = await openai.beta.threads.runs.create(thread.id, {
  assistant_id: assistant.id,
});

// After (Responses API - current)
const conversation = await openai.conversations.create({
  metadata: { purpose: 'customer_support' },
});

const response = await openai.responses.create({
  model: 'gpt-5',
  conversation: conversation.id,
  input: [
    { role: 'developer', content: 'You are helpful.' },
    { role: 'user', content: 'Hello!' },
  ],
});

移行ガイド：Assistants からの公式移行ドキュメント

---

既知の問題の防止

このスキルにより、文書化されている 11 件のエラーを防止できます。

1. セッション状態が保持されない

• 原因：会話 ID を使用していない、またはターンごとに異なる ID を使用している
• 解決策：会話を一度作成し（const conv = await openai.conversations.create()）、すべてのターンで conv.id を再利用します

2. MCP サーバーへの接続に失敗する（mcp_connection_error）

• 原因：URL が無効、認証トークンがない／期限切れ、サーバーが停止している
• 解決策：URL が正しいことを確認し、fetch() で手動テストを行い、トークンの有効期限を確認します

3. Code Interpreter がタイムアウトする（code_interpreter_timeout）

• 原因：コードの実行に 30 秒を超える時間がかかる
• 解決策：タイムアウトを延長する場合は background: true を使用します（最長 10 分）

4. 画像生成のレート制限（rate_limit_error）

• 原因：DALL-E リクエストが多すぎる
• 解決策：指数バックオフによるリトライを実装します（1 秒、2 秒、3 秒の遅延）

5. ファイル検索の関連性に関する問題

• 原因：曖昧なクエリでは、無関係な結果が返される
• 解決策：具体的なクエリを使用し（「価格を検索」ではなく「2024 年第 4 四半期の価格」）、chunk.score > 0.7 でフィルタリングします

6. コスト追跡の混乱

• 原因：Responses では入力＋出力＋ツール＋保存された会話が課金対象です（Chat Completions では入力＋出力のみ）
• 解決策：不要な場合は store: false を設定し、response.usage.tool_tokens を監視します

7. 会話が見つからない（invalid_request_error）

• 原因：ID の入力ミス、会話が削除された、または期限切れ（90 日の制限）
• 解決策：使用前に openai.conversations.list() で存在を確認します

8. ツール出力の解析に失敗する

• 原因：誤った出力構造にアクセスしている
• 解決策：response.output_text ヘルパーを使用するか、response.output.forEach(item => ...) で反復処理し、item.type を確認します

9. Zod v4 と構造化出力の非互換性

• エラー：Invalid schema for response_format 'name': schema must be a JSON Schema of 'type: "object"', got 'type: "string"'.
• 参照元：GitHub Issue #1597
• 発生理由：SDK に同梱されている zod-to-json-schema ライブラリが Zod v4 をサポートしていません（ZodFirstPartyTypeKind エクスポートがありません）
• 予防策：Zod v3（"zod": "^3.23.8"）にバージョンを固定するか、z.toJSONSchema({ target: "draft-7" }) を使用したカスタム zodTextFormat を使用します

// Workaround: Pin to Zod v3 (recommended)
{
  "dependencies": {
    "openai": "^6.16.0",
    "zod": "^3.23.8"  // DO NOT upgrade to v4 yet
  }
}

10. バックグラウンドモードのウェブ検索でソースが欠落する

• エラー：web_search_call の出力項目にクエリは含まれますが、ソース／結果がありません
• 参照元：GitHub Issue #1676
• 発生理由：background: true と web_search ツールを使用すると、OpenAI はレスポンスにソースを返しません
• 予防策：ウェブ検索のソースが必要な場合は、同期モード（background: false）を使用します

// ✅ Sources available in sync mode
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Latest AI news?',
  background: false,  // Required for sources
  tools: [{ type: 'web_search' }],
});

11. ストリーミングモードで output_text ヘルパーが欠落する

• エラー：ストリーミングモードでは finalResponse().output_text が undefined になります
• 参照元：GitHub Issue #1662
• 発生理由：stream.finalResponse() には output_text の便利なフィールドが含まれません（非ストリーミングのレスポンスでのみ利用可能です）
• 予防策：output_text.done イベントを待ち受けるか、output 項目から手動で抽出します

// Workaround: Listen for event
const stream = openai.responses.stream({ model: 'gpt-5', input: 'Hello!' });
let outputText = '';
for await (const event of stream) {
  if (event.type === 'output_text.done') {
    outputText = event.output_text;  // ✅ Available in event
  }
}

---

重要なパターン

✅ 常に行うこと：

• 複数ターンでは会話 ID を使用します（キャッシュ効率が 40～80% 向上）
• 多相レスポンスの 8 種類すべての出力タイプを処理します
• 30 秒を超えるタスクには background: true を使用します
• MCP の authorization トークンを指定します（保存されず、リクエストごとに必要です）
• コスト管理のため response.usage.total_tokens を監視します

❌ 決して行わないこと：

• API キーをクライアント側のコードで公開する
• 出力が単一メッセージだと仮定する（response.output_text ヘルパーを使用します）
• ユーザー間で会話 ID を再利用する（セキュリティリスクがあります）
• エラーの種類を無視する（rate_limit_error や mcp_connection_error を個別に処理します）
• バックグラウンドタスクを 1 秒未満の間隔でポーリングする（5 秒間隔を使用します）

---

参考資料

公式ドキュメント：

• Responses API ガイド：https://platform.openai.com/docs/guides/responses
• API リファレンス：https://platform.openai.com/docs/api-reference/responses
• MCP 連携：https://platform.openai.com/docs/guides/tools-connectors-mcp
• ブログ記事：https://developers.openai.com/blog/responses-api/
• スターターアプリ：https://github.com/openai/openai-responses-starter-app

スキルのリソース： templates/、references/responses-vs-chat-completions.md、references/mcp-integration-guide.md、references/built-in-tools-guide.md、references/migration-guide.md、references/top-errors.md

---

最終確認日：2026-01-21 | スキルのバージョン：2.1.0 | 変更点：TIER 1 の問題を3件追加（Zod v4、バックグラウンドのウェブ検索、ストリーミング出力の output_text）、TIER 2 の調査結果を2件追加（MCP の承認、推論のプライバシー）、データ保持と ZDR のセクション、Assistants API の提供終了スケジュール、バックグラウンドモードの TTFT に関する注記、ウェブ検索の TypeScript に関する制限を追加しました。SDK のバージョンを 6.16.0 に更新しました。