The Legacy Stateful API
The Assistants API was OpenAI's first attempt at stateful AI infrastructure. While now superseded by the Responses API for new projects, many production systems still use it.
Core Concepts
- Assistant: An AI entity with custom instructions, a model choice, and enabled tools.
- Thread: A persistent conversation session. You add Messages to a Thread.
- Message: Text or files added to a Thread by a user or Assistant.
- Run: The execution of an Assistant on a Thread (asynchronous).
The Workflow
- Create an Assistant with instructions and tools.
- Create a Thread when a user starts a conversation.
- Add a User Message to the Thread.
- Create a Run to process the Thread.
- Poll or stream the Run status until complete.
- Retrieve the Assistant's response Messages.
Built-in Tools
| Tool | Purpose |
|---|
| File Search | RAG over uploaded files (up to 10,000 per Vector Store) |
| Code Interpreter | Python sandbox for data analysis and file processing |
| Function Calling | Custom tool execution via requires_action status |
⚠️ Migration Note: The Assistants API still works but receives no new features. All new capabilities (web search, CUA, MCP, prompt caching) are Responses API only. Migrate when possible.