openai-assistants

OpenAI Assistants API v2

ステータス：本番環境で利用可能（2026 年上半期に非推奨化） | パッケージ：[email protected] 最終更新日：2025-11-21 | v2 の提供終了：2026 年上半期

---

⚠️ 重要：非推奨化のお知らせ

OpenAI は、Assistants API を Responses API に移行するため、非推奨化することを発表しました。

スケジュール：

• ✅ 2024 年 12 月 18 日：Assistants API v1 が非推奨化
• ⏳ 2026 年上半期：Assistants API v2 の提供終了を予定
• ✅ 現在：Responses API が利用可能（新規プロジェクトに推奨）

このスキルを引き続き使用すべきですか？

• ✅ はい、次の場合：既存の Assistants API コードがある（移行期間は 12～18 か月）
• ✅ はい、次の場合：レガシーアプリケーションの保守が必要
• ✅ はい、次の場合：Assistants API から Responses API への移行を計画している
• ❌ いいえ、次の場合：新しいプロジェクトを開始する（代わりに openai-responses スキルを使用してください）

移行方法： 移行ガイドの全文は references/migration-to-responses.md を参照してください。

---

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

1. インストール

bun add [email protected]  # preferred
# or: npm install [email protected]

2. 環境のセットアップ

export OPENAI_API_KEY="sk-..."

3. 基本的なアシスタント

import OpenAI from 'openai'

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

// 1. Create an assistant
const assistant = await openai.beta.assistants.create({
  name: "Math Tutor",
  instructions: "You are a helpful math tutor. Answer math questions clearly.",
  model: "gpt-4-1106-preview",
})

// 2. Create a thread (conversation)
const thread = await openai.beta.threads.create()

// 3. Add a message
await openai.beta.threads.messages.create(thread.id, {
  role: "user",
  content: "What is 12 * 34?",
})

// 4. Create and poll run
const run = await openai.beta.threads.runs.createAndPoll(thread.id, {
  assistant_id: assistant.id,
})

// 5. Get messages
if (run.status === 'completed') {
  const messages = await openai.beta.threads.messages.list(thread.id)
  console.log(messages.data[0].content[0].text.value)
}

重要：

• Assistants は永続化されます（サーバー側に保存）
• Threads は永続化されます（会話履歴）
• Runs は Thread 上でアシスタントを実行します
• Runs は非同期のため、必ずポーリングまたはストリーミングしてください
• 簡単に実行するには createAndPoll を、リアルタイム性が必要な場合はストリーミングを使用してください

---

コアコンセプト

4 つの主要オブジェクト：

1. Assistant = 指示とツールを備えた AI エージェント
2. Thread = 会話（メッセージを保持）
3. Message = Thread 内の 1 つのメッセージ（ユーザーまたはアシスタント）
4. Run = Thread 上でのアシスタントの実行

ライフサイクル：

Assistant (create once) + Thread (per conversation) + Message (add user input) → Run (execute) → Messages (get response)

アーキテクチャ、オブジェクト、ワークフロー、料金の詳細については、references/assistants-api-v2.md を読み込んでください。

---

重要なルール

必ず行うこと

✅ Runs をポーリングまたはストリーミングする - Runs は非同期です。即座に完了すると想定しないでください ✅ Run のステータスを確認する - requires_action、failed、cancelled、expired に対応する ✅ 関数呼び出しに対応する - requires_action の場合はツールの出力を送信する ✅ Thread ID を保存する - 複数ターンの会話では Thread を再利用する ✅ タイムアウトを設定する - 大きなファイルのベクトルストアのインデックス作成には数分かかる場合がある ✅ ファイルのアップロードを検証する - 対応形式とサイズ制限を確認する ✅ 構造化された指示を使う - 明確で具体的なアシスタントへの指示を設定する ✅ レート制限に対応する - 指数バックオフを実装する ✅ 未使用のリソースをクリーンアップする - 古い Assistants／Threads を削除してコストを抑える ✅ 最新の API バージョンを使う - Assistants API v2（v1 は 2024 年 12 月に非推奨化）

絶対に行わないこと

❌ Run のポーリングを省略しない - Runs は即座に完了しません ❌ Run ID を再利用しない - インタラクションごとに新しい Run を作成する ❌ ファイルのインデックス作成が即時に完了すると想定しない - ベクトルストアの処理には時間がかかります ❌ requires_action ステータスを無視しない - 関数呼び出しには応答が必要です ❌ Assistant ID をハードコードしない - 環境変数を使用する ❌ リクエストごとに新しい Assistant を作成しない - Assistants を再利用する ❌ ファイル制限を超えない - ベクトルストアあたり 10,000 ファイル、1 ファイルあたり 10GB ❌ 本番環境で Code Interpreter を使用しない - 代わりにサンドボックス化された実行を使用する ❌ エラーハンドリングを省略しない - API 呼び出しは失敗する場合があります ❌ Assistants API で新しいプロジェクトを開始しない - 代わりに Responses API を使用する

---

よくあるエラーを防ぐための上位 5 項目

このスキルは15 件の記録されたエラーを防ぎます。上位 5 項目を紹介します。

エラー #1：「Thread にアクティブな Run がすでにあります」

エラー：Can't create run: thread_xyz already has an active run 予防策：新しい Run を作成する前に、アクティブな Runs がないか確認します：

// Get runs and check status
const runs = await openai.beta.threads.runs.list(thread.id)
const activeRun = runs.data.find(r => ['in_progress', 'queued'].includes(r.status))

if (activeRun) {
  // Cancel or wait
  await openai.beta.threads.runs.cancel(thread.id, activeRun.id)
}

// Now create new run
const run = await openai.beta.threads.runs.create(thread.id, {...})

参照先：references/top-errors.md #1

エラー #2：ベクトルストアのインデックス作成タイムアウト

エラー：アップロード直後のファイル検索で結果が空になる 予防策：インデックス作成が完了するまで待ちます：

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

// Add to vector store
await openai.beta.vectorStores.files.create(vectorStore.id, {
  file_id: file.id,
})

// Wait for indexing (poll file_counts)
let vs = await openai.beta.vectorStores.retrieve(vectorStore.id)
while (vs.file_counts.in_progress > 0) {
  await new Promise(resolve => setTimeout(resolve, 1000))
  vs = await openai.beta.vectorStores.retrieve(vectorStore.id)
}

参照先：references/top-errors.md #2

エラー #3：Run ステータスのポーリングが無限ループする

エラー：ポーリングが終了せず、永久にハングする 予防策：タイムアウトと終端ステータスの確認を追加します：

const maxAttempts = 60 // 60 seconds
let attempts = 0

while (attempts < maxAttempts) {
  const run = await openai.beta.threads.runs.retrieve(thread.id, run.id)

  if (['completed', 'failed', 'cancelled', 'expired', 'requires_action'].includes(run.status)) {
    break
  }

  await new Promise(resolve => setTimeout(resolve, 1000))
  attempts++
}

if (attempts >= maxAttempts) {
  throw new Error('Run polling timeout')
}

参照先：references/top-errors.md #3

エラー #4：関数呼び出しが送信されない

エラー：実行が requires_action ステータスのまま止まる 防止策：必要に応じてツールの出力を送信します：

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

if (run.status === 'requires_action') {
  const toolCalls = run.required_action.submit_tool_outputs.tool_calls

  const toolOutputs = toolCalls.map(call => ({
    tool_call_id: call.id,
    output: JSON.stringify(executeTool(call.function.name, call.function.arguments)),
  }))

  await openai.beta.threads.runs.submitToolOutputsAndPoll(thread.id, run.id, {
    tool_outputs: toolOutputs,
  })
}

参照先：references/top-errors.md #4

エラー #5：ファイルのアップロード形式がサポートされていない

エラー：Invalid file format for Code Interpreter 防止策：アップロード前にファイル形式を検証します：

const supportedFormats = {
  code_interpreter: ['.c', '.cpp', '.csv', '.docx', '.html', '.java', '.json', '.md', '.pdf', '.php', '.pptx', '.py', '.rb', '.tex', '.txt', '.css', '.js', '.sh', '.ts'],
  file_search: ['.c', '.cpp', '.docx', '.html', '.java', '.json', '.md', '.pdf', '.php', '.pptx', '.py', '.rb', '.tex', '.txt', '.css', '.js', '.sh', '.ts'],
}

const fileExtension = path.extname(filePath)

if (!supportedFormats.code_interpreter.includes(fileExtension)) {
  throw new Error(`Unsupported file format: ${fileExtension}`)
}

// Now safe to upload
const file = await openai.files.create({
  file: fs.createReadStream(filePath),
  purpose: 'assistants',
})

参照先：references/top-errors.md #5

エラーの全カタログ（全 15 件）：references/top-errors.md を参照してください

---

一般的なユースケース

ユースケース 1：シンプルな Q&A チャットボット

テンプレート：templates/basic-assistant.ts | 所要時間：10 分

const assistant = await openai.beta.assistants.create({
  name: "Support Bot",
  instructions: "Answer customer questions professionally.",
  model: "gpt-4-1106-preview",
})
// Per conversation: create thread → add message → run → get response

ユースケース 2：RAG によるドキュメント Q&A

テンプレート：templates/file-search-assistant.ts | 所要時間：30 分 参照先：完全な実装については、references/file-search-rag-guide.md と references/vector-stores.md を読み込みます。

ユースケース 3：コード実行アシスタント

テンプレート：templates/code-interpreter-assistant.ts | 所要時間：20 分 参照先：セットアップ、代替手段、トラブルシューティングについては、references/code-interpreter-guide.md を読み込みます。

ユースケース 4：関数呼び出しアシスタント

テンプレート：templates/function-calling-assistant.ts | 所要時間：25 分

ユースケース 5：ストリーミングチャットボット

テンプレート：templates/streaming-assistant.ts | 所要時間：15 分

---

詳細なリファレンスを読み込むタイミング

次の場合は references/assistants-api-v2.md を読み込みます：

• ユーザーが完全な API リファレンスを必要としている
• ユーザーが特定のエンドポイントやパラメーターについて質問している
• ユーザーがレート制限やクォータの情報を必要としている
• ユーザーがアーキテクチャの詳細を知りたい

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

• ユーザーがコード実行を実装している
• ユーザーが Code Interpreter でサポートされているファイル形式について質問している
• ユーザーが Code Interpreter の代替手段（E2B、Modal）を必要としている
• ユーザーが Code Interpreter のエラーに遭遇している

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

• ユーザーが RAG アプリケーションを構築している
• ユーザーがベクトルストアのセットアップについて質問している
• ユーザーがファイル検索の最適化戦略を必要としている
• ユーザーが基本的なセットアップを超えてドキュメント検索をスケールしている

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

• ユーザーが Assistants API v1 に言及している
• ユーザーが v1 から v2 にアップグレードしている
• ユーザーが破壊的変更（retrieval → file_search）について質問している
• ユーザーが v1 の非推奨化エラーに遭遇している

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

• ユーザーが将来的に Responses API への移行を計画している
• ユーザーが Responses API との比較について質問している
• ユーザーが非推奨化のスケジュールに言及している
• ユーザーが新しいプロジェクトを構築している（Responses API を推奨）

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

• ユーザーが複数ターンの会話を構築している
• ユーザーがスレッドの永続化パターンについて質問している
• ユーザーが会話管理の戦略を必要としている
• ユーザーがスレッドの使用やクリーンアップを最適化している

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

• ユーザーがエラーに遭遇している（全 15 件を記載）
• ユーザーがトラブルシューティングについて質問している
• ユーザーが既知の問題を防ぎたい
• ユーザーが本番環境の問題をデバッグしている

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

• ユーザーが基本的なセットアップを超えてファイル検索をスケールしている
• ユーザーがファイル数の上限（10,000 件）について質問している
• ユーザーがインデックス作成の最適化を必要としている
• ユーザーがベクトルストアのコスト（$0.10/GB/日）を管理している

---

利用可能なテンプレート

本番環境ですぐに使えるコード例は templates/ にあります：

• basic-assistant.ts - 最小限のアシスタントのセットアップ（利用開始）
• code-interpreter-assistant.ts - コード実行（Python コードランナー）
• file-search-assistant.ts - ドキュメント Q&A（RAG アプリケーション）
• function-calling-assistant.ts - 外部ツール（API 統合）
• streaming-assistant.ts - リアルタイム応答（ストリーミング出力）
• thread-management.ts - 複数ターンの会話（チャットボット）
• vector-store-setup.ts - ベクトルストアの設定（ファイル検索のセットアップ）
• package.json - 依存関係（プロジェクトのセットアップ）

---

依存関係

必須：

• [email protected] - OpenAI Node.js SDK

任意：

• fs - ファイルシステム操作（組み込み）
• path - パスユーティリティ（組み込み）

---

公式ドキュメント

• Assistants API: https://platform.openai.com/docs/assistants/overview
• API リファレンス: https://platform.openai.com/docs/api-reference/assistants
• Responses API: https://platform.openai.com/docs/guides/responses（新規プロジェクトに推奨）
• 移行ガイド: https://platform.openai.com/docs/guides/migration
• コミュニティフォーラム: https://community.openai.com/

---

パッケージのバージョン（2025-10-25 確認済み）

{
  "dependencies": {
    "openai": "^6.7.0"
  }
}

バージョンに関する注意：

• OpenAI SDK 6.7.0 が最新の安定版です
• Assistants API v2 をサポートしています
• Assistants API v1 は 2024 年 12 月 18 日に非推奨になりました
• Assistants API v2 は 2026 年上半期に提供終了予定です

---

本番環境での使用例

このスキルは本番環境での使用に基づいています：

• トークン削減：手動実装と比べて約 60％
• 防止したエラー：文書化された 15 件の問題
• セットアップ時間：基本的なチャットボットなら 30 分未満
• 検証状況：✅ ファイル検索が動作、✅ ストリーミングが機能、✅ 関数呼び出しをテスト済み

---

セットアップ完了チェックリスト

• [email protected] をインストールした
• OPENAI_API_KEY 環境変数を設定した
• アシスタントを少なくとも 1 つ作成した
• スレッドの作成とメッセージの追加をテストした
• 実行のポーリングまたはストリーミングを実装した
• requires_action ステータスに対応した（関数呼び出しを使用する場合）
• ファイルのアップロードをテストした（Code Interpreter または File Search を使用する場合）
• すべての API 呼び出しにエラー処理を実装した
• 会話を保持するため、スレッド ID を保存した
• Responses API への移行を計画した（新規プロジェクト向け）
• レート制限のモニタリングを設定した
• 未使用のリソースをクリーンアップする処理を実装した

---

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

1. 公式ドキュメントを確認してください：https://platform.openai.com/docs/assistants/overview
2. 文書化された 15 件すべてのエラーについては、references/top-errors.md を確認してください
3. 本番環境ですぐに使えるコード例は templates/ を参照してください
4. 今後に備えた移行については、references/migration-to-responses.md を確認してください
5. コミュニティに参加してください：https://community.openai.com/

---

⚠️ 注意：この API は非推奨です。新規プロジェクトでは、代わりに Responses API を使用してください。移行ガイドについては、references/migration-to-responses.md を参照してください。