openai-responses

OpenAI Responses API

ステータス：本番環境で利用可能 | API リリース：2025 年 3 月 | SDK：[email protected] 以降

---

クイックスタート（5 分）

Node.js

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);

Cloudflare Workers

const response = await fetch('https://api.openai.com/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${env.OPENAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-5',
    input: 'Hello, world!',
  }),
});

const data = await response.json();
console.log(data.output_text);

ステートフルな会話と組み込みツールを含むセットアップの詳細については、references/setup-guide.md を読み込んでください。

---

Responses API とは？

Responses API（/v1/responses）は、2025 年 3 月にリリースされた、エージェント型アプリケーション向けの OpenAI の統合インターフェースです。主な革新点：ターンをまたいで推論状態を保持します（状態を破棄する Chat Completions とは異なります）。これにより、TAUBench のマルチターン性能が約 5% 向上します。

Chat Completions ではなく Responses を使う理由：状態管理の自動化、推論の保持、サーバーサイドツール、キャッシュ利用率の 40～80% 向上、組み込み MCP サポートを利用できます。

詳細な比較と選択ガイドについては、references/responses-vs-chat-completions.md を読み込んでください。

---

特に重要な 3 つのルール

必ず行うこと ✅

1. conversation_id を保存する - ターン間で状態を保持するために必要です（最重要）
2. API キーには環境変数を使う（ハードコードは絶対にしないでください）
3. 多相出力を処理する - output.type（message、reasoning、function_call）を確認してください

絶対に行わないこと ❌

1. conversation_id を無視しない - 状態が失われます
2. 出力タイプが 1 つだけだと思い込まない - 必ず output.type を確認してください
3. 同じ会話で Chat Completions と Responses を混在させない

ルールとベストプラクティスの詳細については、references/setup-guide.md を読み込んでください。

---

主な 5 つのユースケース

ユースケース 1：ステートフルな会話

// First turn
const response1 = await openai.responses.create({
  model: 'gpt-5',
  input: 'My favorite color is blue.',
});

const conversationId = response1.conversation_id;

// Second turn - model remembers
const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation_id: conversationId,
  input: 'What is my favorite color?',
});
// Output: "Your favorite color is blue."

読み込むファイル：references/stateful-conversations.md + templates/stateful-conversation.ts

---

ユースケース 2：ウェブ検索エージェント

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Search the web for latest AI news.',
  tools: {
    web_search: { enabled: true },
  },
});

読み込むファイル：references/built-in-tools-guide.md + templates/web-search.ts

---

ユースケース 3：コードインタープリター

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Calculate the sum of squares from 1 to 100.',
  tools: {
    code_interpreter: { enabled: true },
  },
});

読み込むファイル：references/built-in-tools-guide.md + templates/code-interpreter.ts

---

ユースケース 4：ファイル検索（RAG）

// Upload file
const file = await openai.files.create({
  file: fs.createReadStream('document.pdf'),
  purpose: 'user_data',
});

// Search file
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Summarize key points from the uploaded document.',
  tools: {
    file_search: {
      enabled: true,
      file_ids: [file.id],
    },
  },
});

読み込むファイル：references/built-in-tools-guide.md + templates/file-search.ts

---

ユースケース 5：MCP サーバーの統合

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Get weather for San Francisco.',
  tools: {
    mcp_servers: [
      {
        url: 'https://weather-mcp.example.com',
        tool_choice: 'auto',
      },
    ],
  },
});

読み込むファイル：references/mcp-integration-guide.md + templates/mcp-integration.ts

---

組み込みツール

すべてのツールはサーバーサイドで実行されます：コードインタープリター（Python の実行）、ファイル検索（RAG）、ウェブ検索（リアルタイム）、画像生成（DALL-E）。

明示的に有効にしてください：

tools: {
  code_interpreter: { enabled: true },
  file_search: { enabled: true, file_ids: ['file-123'] },
  web_search: { enabled: true },
  image_generation: { enabled: true },
}

例と設定オプションを含む詳細なガイドについては、references/built-in-tools-guide.md を読み込んでください。

---

ステートフルな会話

会話 ID による自動状態管理により、メッセージを手動で追跡する必要がなくなり、推論が保持され、キャッシュ利用率が 40～80% 向上します。

// Create conversation
const response1 = await openai.responses.create({
  model: 'gpt-5',
  input: 'Remember: my name is Alice.',
});

// Continue conversation
const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation_id: response1.conversation_id,
  input: 'What is my name?',
});

永続化パターン（Node.js/Redis/KV）とライフサイクル管理については、references/stateful-conversations.md を読み込んでください。

---

Chat Completions からの移行

簡単な変更点：messages → input、system ロール → developer、choices[0].message.content → output_text、/v1/chat/completions → /v1/responses。

変更前（Chat Completions）：

const messages = [{ role: 'user', content: 'Hello' }];
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: messages,
});
messages.push(response.choices[0].message); // Manual history

変更後（Responses API）：

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Hello',
});

const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation_id: response.conversation_id, // Automatic state
  input: 'Follow-up question',
});

ツール移行パターンを含む移行チェックリストの全体については、references/migration-guide.md を読み込んでください。

---

多相出力

Responses は複数の出力タイプ（message、reasoning、function_call、image）を返すことがあります。各タイプを処理するか、便利なプロパティ output_text を使用してください。

for (const output of response.output) {
  if (output.type === 'message') {
    console.log('Message:', output.content);
  } else if (output.type === 'reasoning') {
    console.log('Reasoning:', output.summary);
  } else if (output.type === 'function_call') {
    console.log('Function:', output.name, output.arguments);
  }
}

// Or use convenience property
console.log(response.output_text);

推論出力の詳細とデバッグパターンについては、references/reasoning-preservation.md を読み込んでください。

---

バックグラウンドモード

長時間実行されるタスク（60 秒超）には、background: true を使って非同期で実行し、完了するまでポーリングしてください。

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Analyze this 50-page document.',
  background: true,
});

// Poll for completion
const completed = await openai.responses.retrieve(response.id);

指数バックオフを使ったポーリングパターンの詳細については、templates/background-mode.ts を読み込んでください。

---

主なエラー 3 つと解決策

エラー 1：セッション状態が保持されない

症状：モデルが以前のターンを記憶していません。

原因：会話 ID を使用していないか、毎回新しい会話を作成しています。

解決策：

// ✅ GOOD: Reuse conversation ID
const conv = await openai.conversations.create();
const response1 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id, // Same ID
  input: 'Question 1',
});
const response2 = await openai.responses.create({
  model: 'gpt-5',
  conversation: conv.id, // Same ID - remembers previous
  input: 'Question 2',
});

---

エラー 2：MCP サーバーへの接続に失敗しました

原因：サーバー URL が無効、または認証トークンがないか期限切れです。

解決方法：

const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Test MCP',
  tools: [
    {
      type: 'mcp',
      server_url: 'https://mcp.stripe.com', // ✅ Full HTTPS URL
      authorization: process.env.STRIPE_OAUTH_TOKEN, // ✅ Valid token
    },
  ],
});

予防策：シークレットには環境変数を使用し、トークンの更新ロジックを実装し、指数バックオフによる再試行を追加してください。

---

エラー 3：コードインタープリターがタイムアウトしました

原因：コードの実行時間が 30 秒（標準モードの上限）を超えています。

解決方法：

// ✅ GOOD: Use background mode for long tasks
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'Process this massive dataset',
  background: true, // ✅ Up to 10 minutes
  tools: [{ type: 'code_interpreter' }],
});

// Poll for results
let result = await openai.responses.retrieve(response.id);
while (result.status === 'in_progress') {
  await new Promise(r => setTimeout(r, 5000));
  result = await openai.responses.retrieve(response.id);
}

詳細な解決策と予防策を含む 8 つのエラーすべてについては、references/top-errors.md を読み込んでください。

---

参照資料を読み込むタイミング

次の場合は references/setup-guide.md を読み込みます：

• Responses API を初めて使用し、Node.js または Cloudflare Workers のセットアップ全体が必要な場合
• 環境ごとのベストプラクティスを含む、本番環境へのデプロイチェックリストが必要な場合
• セットアップの問題をトラブルシューティングする場合、またはストリーミング／バックグラウンドのパターンを実装する場合

次の場合は references/responses-vs-chat-completions.md を読み込みます：

• Responses API と Chat Completions API のどちらを使用するか決める場合
• パフォーマンスベンチマーク（TAUBench の結果、キャッシュ利用率）について理解する場合
• 移行の作業量を評価する場合、またはコスト構造を比較する場合

次の場合は references/migration-guide.md を読み込みます：

• Chat Completions API から移行する際、手順ごとのチェックリストが必要な場合
• コードの比較例（移行前／移行後のパターン）が必要な場合
• カスタム関数から組み込みツール／MCP にツールを移行する場合

次の場合は references/built-in-tools-guide.md を読み込みます：

• Code Interpreter、File Search、Web Search、Image Generation を使用する場合
• ツールの設定オプション、複数のツールの組み合わせ、またはトラブルシューティングが必要な場合

次の場合は references/mcp-integration-guide.md を読み込みます：

• 外部 MCP サーバーを統合する場合、またはカスタム MCP ツールを構築する場合
• MCP の設定例や認証パターンが必要な場合

次の場合は references/stateful-conversations.md を読み込みます：

• KV／Redis／データベースを使用して会話の永続化を実装する場合
• 会話のライフサイクル管理やメタデータ追跡のパターンが必要な場合

次の場合は references/reasoning-preservation.md を読み込みます：

• デバッグや透明性確保のためにモデルの推論にアクセスする場合
• 監査可能な AI システムを構築する場合、または推論出力の例が必要な場合

次の場合は references/top-errors.md を読み込みます：

• API エラーが発生した場合（よくある 8 つのエラーと解決策を掲載）
• エラーコードのリファレンス、予防策、またはエラー処理のパターンが必要な場合

---

本番環境チェックリスト

デプロイする前に、以下を確認してください。

• API キーが安全に保存されている（環境変数またはシークレット）
• エラー処理が実装されている（401、429、400、500）
• レート制限に対応している（指数バックオフ）
• 会話 ID が永続化されている（データベース／KV）
• 長い応答に対してストリーミングが有効になっている
• ツールが明示的に有効化されている
• 多相出力が処理されている

プラットフォーム固有の考慮事項を含む本番環境チェックリスト全体については、references/setup-guide.md を読み込んでください。

---

関連スキル

• openai-api - 従来の Chat Completions API
• openai-agents - OpenAI Agents SDK（Responses のラッパー）
• claude-api - 比較用の Claude API
• ai-sdk-core - Vercel AI SDK（Responses をサポート）

---

公式ドキュメント

• Responses API: https://platform.openai.com/docs/api-reference/responses
• 移行ガイド: https://platform.openai.com/docs/guides/responses-migration
• 組み込みツール: https://platform.openai.com/docs/guides/responses-tools
• MCP 統合: https://platform.openai.com/docs/guides/mcp

---

質問や問題がありますか？

1. エラーの解決策については references/top-errors.md を確認してください
2. セットアップ全体については references/setup-guide.md を確認してください
3. Chat Completions からの移行については references/migration-guide.md を参照してください
4. 動作する例については templates/ からテンプレートを読み込んでください