Openai Assistants

openai-assistants

Complete guide for OpenAI's Assistants API v2: stateful conversational AI with built-in tools, vector stores, and thread management.

⚠️ DEPRECATION NOTICE: OpenAI plans to sunset Assistants API in H1 2026. Use openai-responses for new projects.

---

Auto-Trigger Keywords

This skill automatically activates when you mention:

Primary Keywords

• openai assistants
• assistants api
• openai threads
• openai runs
• code interpreter assistant
• file search openai
• vector store openai
• openai rag

Use Case Keywords

• assistant streaming
• thread persistence
• stateful chatbot openai
• data analysis assistant
• document qa openai
• python code execution openai
• semantic search openai
• conversational ai with memory

Tool Keywords

• code_interpreter tool
• file_search tool
• function calling assistant
• vector stores api
• assistant file uploads

Error-Based Keywords

• thread already has active run
• run status polling
• vector store error
• assistant run failed
• thread not found
• run requires action
• code interpreter failed
• file search not working
• vector store indexing delay

---

What This Skill Provides

Core Capabilities

• ✅ Assistants - Configured AI entities with instructions and tools
• ✅ Threads - Persistent conversation containers (up to 100k messages)
• ✅ Runs - Asynchronous execution with polling and streaming
• ✅ Messages - User/assistant messages with file attachments
• ✅ Code Interpreter - Python code execution, data analysis, visualizations
• ✅ File Search - RAG with vector stores (up to 10,000 files)
• ✅ Function Calling - Custom tools integration
• ✅ Vector Stores - Semantic search infrastructure
• ✅ Streaming - Real-time Server-Sent Events (SSE)

Implementation Approaches

• ✅ Node.js SDK (openai@6.7.0)
• ✅ Fetch API (Cloudflare Workers compatible)

---

When to Use This Skill

✅ Use openai-assistants when:

• Building stateful chatbots with conversation history
• Implementing RAG with vector stores
• Executing Python code for data analysis
• Using file search for document Q&A
• Managing multi-turn conversations
• Maintaining existing Assistants API applications
• Planning migration to Responses API

❌ Use openai-responses instead when:

• Starting new projects (modern, actively developed)
• Need better reasoning preservation across turns
• Want built-in MCP server integration
• Building agentic workflows
• Prefer polymorphic outputs (messages + reasoning + tool calls)

❌ Use openai-api instead when:

• Need stateless text generation
• Implementing simple one-off completions
• Using streaming without conversation persistence

---

Quick Example

import OpenAI from 'openai';

const openai = new OpenAI();

// 1. Create assistant
const assistant = await openai.beta.assistants.create({
  name: "Math Tutor",
  instructions: "You are a math tutor. Use code to solve problems.",
  tools: [{ type: "code_interpreter" }],
  model: "gpt-4o",
});

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

// 3. Add message
await openai.beta.threads.messages.create(thread.id, {
  role: "user",
  content: "What is 3x + 11 = 14?",
});

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

// 5. Poll for completion
let runStatus = await openai.beta.threads.runs.retrieve(thread.id, run.id);
while (runStatus.status !== 'completed') {
  await new Promise(resolve => setTimeout(resolve, 1000));
  runStatus = await openai.beta.threads.runs.retrieve(thread.id, run.id);
}

// 6. Get response
const messages = await openai.beta.threads.messages.list(thread.id);
console.log(messages.data[0].content[0].text.value);

---

Known Issues Prevented

Issue	Solution in Skill
1. Thread already has active run	Active run detection pattern
2. Run polling timeout	Timeout handling with cancellation
3. Vector store indexing delay	Async wait pattern
4. File search relevance issues	Chunking strategy guide
5. Code Interpreter file output lost	File retrieval timing
6. Thread message limit exceeded	Cleanup patterns
7. Function calling timeout	Timeout configuration
8. Streaming run interruption	Event handling patterns
9. Vector store quota limits	Cost monitoring
10. File upload format incompatibility	Format validation
11. Assistant instructions too long	Token limit checking
12. Thread deletion during active run	Lifecycle management

---

File Structure

openai-assistants/
├── SKILL.md                          # Complete API guide (2100+ lines)
├── README.md                         # This file
├── templates/
│   ├── basic-assistant.ts            # Simple assistant example
│   ├── code-interpreter-assistant.ts # Data analysis with Python
│   ├── file-search-assistant.ts      # RAG with vector stores
│   ├── function-calling-assistant.ts # Custom tools
│   ├── streaming-assistant.ts        # Real-time streaming
│   ├── thread-management.ts          # Lifecycle patterns
│   ├── vector-store-setup.ts         # Vector store creation
│   └── package.json                  # Dependencies
├── references/
│   ├── assistants-api-v2.md          # API overview
│   ├── code-interpreter-guide.md     # Python execution deep dive
│   ├── file-search-rag-guide.md      # Vector stores and RAG
│   ├── thread-lifecycle.md           # Thread management patterns
│   ├── vector-stores.md              # Storage pricing and limits
│   ├── migration-from-v1.md          # v1 → v2 migration
│   └── top-errors.md                 # 12 common errors + solutions
└── scripts/
    └── check-versions.sh             # Package version verification

---

Dependencies

bun add openai@6.7.0  # preferred
# or: npm install openai@6.7.0

Environment Variables:

export OPENAI_API_KEY="sk-..."

---

Related Skills

• openai-responses - Modern Responses API (recommended for new projects)
• openai-api - Chat Completions API (stateless)
• openai-realtime - Realtime audio streaming
• openai-batch - Batch processing for cost optimization

---

Production Status

✅ Production Ready (with deprecation timeline)

Tested With:

• openai@6.7.0
• Node.js 18+
• Cloudflare Workers
• Next.js 14+

Deprecation Timeline:

• Dec 2024: v1 deprecated
• H1 2026: v2 sunset planned
• Migration path: Responses API

---

Important Notes

Deprecation Warning

OpenAI announced plans to deprecate Assistants API in favor of Responses API:

• Timeline: H1 2026 sunset
• Replacement: Responses API
• Migration: 12-18 month window
• New Projects: Use openai-responses skill instead

This skill remains valuable for:

• Maintaining existing Assistants API applications
• Understanding migration requirements
• Learning stateful AI patterns

When to Migrate

Migrate to Responses API if:

• Starting new projects
• Need latest features (MCP, better reasoning)
• Want active development/support
• Building agentic workflows

Keep using Assistants if:

• Have existing production apps
• Not ready to refactor (12+ month window)
• Need time for migration planning

---

Support & Documentation

Official Docs: https://platform.openai.com/docs/assistants API Reference: https://platform.openai.com/docs/api-reference/assistants Migration Guide: See references/migration-to-responses.md (in this skill)

---

Last Updated: 2025-10-25 Status: Production Ready (Deprecated H1 2026) License: MIT