Complete guide for OpenAI's Assistants API v2: stateful conversational AI with built-in tools (Code Interpreter, File Search, Function Calling), vector stores for RAG (up to 10,000 files), thread/run lifecycle management, and streaming patterns. Both Node.js SDK and fetch approaches. ⚠️ DEPRECATION NOTICE: OpenAI plans to sunset Assistants API in H1 2026 in favor of Responses API. This skill remains valuable for existing apps and migration planning. Use when: building stateful chatbots with OpenAI, implementing RAG with vector stores, executing Python code with Code Interpreter, using file search for document Q&A, managing conversation threads, streaming assistant responses, or encountering errors like "thread already has active run", vector store indexing delays, run polling timeouts, or file upload issues. 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
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.
This skill automatically activates when you mention:
openai assistantsassistants apiopenai threadsopenai runscode interpreter assistantfile search openaivector store openaiopenai ragassistant streamingthread persistencestateful chatbot openaidata analysis assistantdocument qa openaipython code execution openaisemantic search openaiconversational ai with memorycode_interpreter toolfile_search toolfunction calling assistantvector stores apiassistant file uploadsthread already has active runrun status pollingvector store errorassistant run failedthread not foundrun requires actioncode interpreter failedfile search not workingvector store indexing delay✅ Use openai-assistants when:
❌ Use openai-responses instead when:
❌ Use openai-api instead when:
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);
| 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 |
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
Without this skill:
With this skill:
npm install openai@6.7.0
Environment Variables:
export OPENAI_API_KEY="sk-..."
✅ Production Ready (with deprecation timeline)
Tested With:
Deprecation Timeline:
OpenAI announced plans to deprecate Assistants API in favor of Responses API:
openai-responses skill insteadThis skill remains valuable for:
Migrate to Responses API if:
Keep using Assistants if:
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
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer