openai-assistants

Original source / Raw SKILL.md

---
name: openai-assistants
description: OpenAI Assistants API v2 for stateful chatbots with Code Interpreter, File Search, RAG. Use for threads, vector stores, or encountering active run errors, indexing delays. ⚠️ Sunset August 26, 2026.

  Keywords: openai assistants, assistants api, openai threads, openai runs, code interpreter assistant,
  file search openai, vector store openai, openai rag, assistant streaming, thread persistence,
  stateful chatbot, thread already has active run, run status polling, vector store error
license: MIT
metadata:
  version: "2.0.0"
  openai_version: "6.9.1"
  last_verified: "2025-11-21"
  api_version: "v2"
  v1_deprecated: "2024-12-18"
  v2_sunset: "H1 2026"
  production_tested: true
  token_savings: "~60%"
  errors_prevented: 15
  templates_included: 8
  references_included: 8
---

# OpenAI Assistants API v2

**Status**: Production Ready (Deprecated H1 2026) | **Package**: [email protected]
**Last Updated**: 2025-11-21 | **v2 Sunset**: H1 2026

---

## ⚠️ Important: Deprecation Notice

**OpenAI announced that the Assistants API will be deprecated in favor of the Responses API.**

**Timeline:**
- ✅ **Dec 18, 2024**: Assistants API v1 deprecated
- ⏳ **H1 2026**: Planned sunset of Assistants API v2
- ✅ **Now**: Responses API available (recommended for new projects)

**Should you still use this skill?**
- ✅ **Yes, if**: You have existing Assistants API code (12-18 month migration window)
- ✅ **Yes, if**: You need to maintain legacy applications
- ✅ **Yes, if**: Planning migration from Assistants → Responses
- ❌ **No, if**: Starting a new project (use openai-responses skill instead)

**Migration Path:** See `references/migration-to-responses.md` for complete migration guide.

---

## Quick Start (5 Minutes)

### 1. Installation

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

### 2. Environment Setup

```bash
export OPENAI_API_KEY="sk-..."
```

### 3. Basic Assistant

```typescript
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)
}
```

**CRITICAL:**
- Assistants are persistent (stored server-side)
- Threads are persistent (conversation history)
- Runs execute the assistant on a thread
- Always poll or stream runs (they're async)
- Use `createAndPoll` for simplicity or streaming for real-time

---

## Core Concepts

**4 Key Objects:**

1. **Assistant** = AI agent with instructions + tools
2. **Thread** = Conversation (persists messages)
3. **Message** = Single message in thread (user or assistant)
4. **Run** = Execution of assistant on thread

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

**Load `references/assistants-api-v2.md`** for complete architecture, objects, workflows, and pricing details.

---

## Critical Rules

### Always Do

✅ **Poll or stream runs** - runs are async, don't assume immediate completion
✅ **Check run status** - handle `requires_action`, `failed`, `cancelled`, `expired`
✅ **Handle function calls** - submit tool outputs when `requires_action`
✅ **Store thread IDs** - reuse threads for multi-turn conversations
✅ **Set timeouts** - vector store indexing can take minutes for large files
✅ **Validate file uploads** - check supported formats and size limits
✅ **Use structured instructions** - clear, specific assistant instructions
✅ **Handle rate limits** - implement exponential backoff
✅ **Clean up unused resources** - delete old assistants/threads to save costs
✅ **Use latest API version** - Assistants API v2 (v1 deprecated Dec 2024)

### Never Do

❌ **Never skip run polling** - runs don't complete instantly
❌ **Never reuse run IDs** - create new run for each interaction
❌ **Never assume file indexing is instant** - vector stores need time
❌ **Never ignore `requires_action` status** - function calls need your response
❌ **Never hardcode assistant IDs** - use environment variables
❌ **Never create new assistant per request** - reuse assistants
❌ **Never exceed file limits** - 10,000 files per vector store, 10GB per file
❌ **Never use Code Interpreter for production** - use sandboxed execution instead
❌ **Never skip error handling** - API calls can fail
❌ **Never start new projects with Assistants API** - use Responses API instead

---

## Top 5 Errors Prevention

This skill prevents **15 documented errors**. Here are the top 5:

### Error #1: "Thread Already Has Active Run"
**Error**: `Can't create run: thread_xyz already has an active run`
**Prevention**: Check for active runs before creating new one:
```typescript
// 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, {...})
```
**See**: `references/top-errors.md` #1

### Error #2: Vector Store Indexing Timeout
**Error**: File search returns empty results immediately after upload
**Prevention**: Wait for indexing to complete:
```typescript
// 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)
}
```
**See**: `references/top-errors.md` #2

### Error #3: Run Status Polling Infinite Loop
**Error**: Polling never terminates, hangs forever
**Prevention**: Add timeout and terminal status check:
```typescript
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')
}
```
**See**: `references/top-errors.md` #3

### Error #4: Function Call Not Submitted
**Error**: Run stuck in `requires_action` status forever
**Prevention**: Submit tool outputs when required:
```typescript
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,
  })
}
```
**See**: `references/top-errors.md` #4

### Error #5: File Upload Format Not Supported
**Error**: `Invalid file format for Code Interpreter`
**Prevention**: Validate file format before upload:
```typescript
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',
})
```
**See**: `references/top-errors.md` #5

**For complete error catalog** (all 15 errors): See `references/top-errors.md`

---

## Common Use Cases

### Use Case 1: Simple Q&A Chatbot
**Template**: `templates/basic-assistant.ts` | **Time**: 10 minutes
```typescript
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
```

### Use Case 2: Document Q&A with RAG
**Template**: `templates/file-search-assistant.ts` | **Time**: 30 minutes
**References**: Load `references/file-search-rag-guide.md` and `references/vector-stores.md` for complete implementation.

### Use Case 3: Code Execution Assistant
**Template**: `templates/code-interpreter-assistant.ts` | **Time**: 20 minutes
**References**: Load `references/code-interpreter-guide.md` for setup, alternatives, and troubleshooting.

### Use Case 4: Function Calling Assistant
**Template**: `templates/function-calling-assistant.ts` | **Time**: 25 minutes

### Use Case 5: Streaming Chatbot
**Template**: `templates/streaming-assistant.ts` | **Time**: 15 minutes

---

## When to Load Detailed References

**Load `references/assistants-api-v2.md` when:**
- User needs complete API reference
- User asks about specific endpoints or parameters
- User needs rate limit information or quotas
- User wants architecture details

**Load `references/code-interpreter-guide.md` when:**
- User implementing code execution
- User asks about supported file formats for Code Interpreter
- User needs Code Interpreter alternatives (E2B, Modal)
- User encounters Code Interpreter errors

**Load `references/file-search-rag-guide.md` when:**
- User building RAG application
- User asks about vector stores setup
- User needs file search optimization strategies
- User scaling document search beyond basic setup

**Load `references/migration-from-v1.md` when:**
- User mentions Assistants API v1
- User upgrading from v1 to v2
- User asks about breaking changes (retrieval → file_search)
- User encounters v1 deprecation errors

**Load `references/migration-to-responses.md` when:**
- User planning future migration to Responses API
- User asks about Responses API comparison
- User mentions deprecation timeline
- User building new projects (recommend Responses API)

**Load `references/thread-lifecycle.md` when:**
- User building multi-turn conversations
- User asks about thread persistence patterns
- User needs conversation management strategies
- User optimizing thread usage or cleanup

**Load `references/top-errors.md` when:**
- User encounters any error (all 15 documented)
- User asks about troubleshooting
- User wants to prevent known issues
- User debugging production issues

**Load `references/vector-stores.md` when:**
- User scaling file search beyond basic setup
- User asks about file limits (10,000 files)
- User needs indexing optimization
- User managing vector store costs ($0.10/GB/day)

---

## Templates Available

**Production-ready code examples in `templates/`:**

- **`basic-assistant.ts`** - Minimal assistant setup (getting started)
- **`code-interpreter-assistant.ts`** - Code execution (Python code runner)
- **`file-search-assistant.ts`** - Document Q&A (RAG application)
- **`function-calling-assistant.ts`** - External tools (API integration)
- **`streaming-assistant.ts`** - Real-time responses (streaming output)
- **`thread-management.ts`** - Multi-turn conversations (chatbot)
- **`vector-store-setup.ts`** - Vector store configuration (file search setup)
- **`package.json`** - Dependencies (project setup)

---

## Dependencies

**Required**:
- **[email protected]** - OpenAI Node.js SDK

**Optional**:
- **fs** - File system operations (built-in)
- **path** - Path utilities (built-in)

---

## Official Documentation

- **Assistants API**: https://platform.openai.com/docs/assistants/overview
- **API Reference**: https://platform.openai.com/docs/api-reference/assistants
- **Responses API**: https://platform.openai.com/docs/guides/responses (recommended for new projects)
- **Migration Guide**: https://platform.openai.com/docs/guides/migration
- **Community Forum**: https://community.openai.com/

---

## Package Versions (Verified 2025-10-25)

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

**Version Notes:**
- OpenAI SDK 6.7.0 is latest stable
- Supports Assistants API v2
- Assistants API v1 deprecated Dec 18, 2024
- Assistants API v2 sunset planned H1 2026

---

## Production Example

This skill is based on production usage:
- **Token Savings**: ~60% vs manual implementation
- **Errors Prevented**: 15 documented issues
- **Setup Time**: < 30 minutes for basic chatbot
- **Validation**: ✅ File search working, ✅ Streaming functional, ✅ Function calling tested

---

## Complete Setup Checklist

- [ ] Installed `[email protected]`
- [ ] Set `OPENAI_API_KEY` environment variable
- [ ] Created at least one assistant
- [ ] Tested thread creation and message addition
- [ ] Implemented run polling or streaming
- [ ] Handled `requires_action` status (if using function calling)
- [ ] Tested file uploads (if using Code Interpreter or File Search)
- [ ] Implemented error handling for all API calls
- [ ] Stored thread IDs for conversation persistence
- [ ] Planned migration to Responses API (for new projects)
- [ ] Set up monitoring for rate limits
- [ ] Implemented cleanup for unused resources

---

**Questions? Issues?**

1. Check official docs: https://platform.openai.com/docs/assistants/overview
2. Review `references/top-errors.md` for all 15 documented errors
3. See `templates/` for production-ready code examples
4. Check `references/migration-to-responses.md` for future-proofing
5. Join community: https://community.openai.com/

---

**⚠️ Reminder: This API is deprecated. For new projects, use the Responses API instead. See `references/migration-to-responses.md` for migration guide.**