OpenAI Assistants

Manages conversation history as immutable thread objects stored server-side, where each message appends to a thread rather than requiring clients to maintain conversation state. Threads persist across API calls and sessions, enabling stateless client implementations. The architecture decouples conversation management from model invocation, allowing assistants to be reused across multiple independent threads without state collision.

Provides a managed Python 3.11 execution environment accessible via the Code Interpreter tool, where assistants can write and execute arbitrary Python code with access to common libraries (pandas, numpy, matplotlib, scikit-learn). Code runs in isolated sandboxes with file I/O, plotting, and data visualization capabilities. Execution results (stdout, stderr, generated files) are returned to the assistant for further processing.

When an assistant calls a tool, the run enters a 'requires_action' state. Clients must submit tool call results via the submit_tool_outputs API, which resumes the run with the tool results injected into context. This enables iterative workflows where assistants can call tools, receive results, and refine responses based on results. Tool results are stored in the thread and visible to subsequent runs, enabling multi-turn tool-assisted reasoning.

Assistants can be created from scratch or cloned from existing assistants, copying all configuration (instructions, tools, model, file attachments). Cloning enables template-based assistant creation where a base assistant is configured once and then cloned for different use cases or users. Cloned assistants are independent — changes to one don't affect others. This reduces setup overhead for creating similar assistants.

Files uploaded to assistants are stored in OpenAI's managed file storage and associated with assistants or threads. Files can be deleted explicitly via API, and OpenAI automatically cleans up files after 30 days of inactivity. File storage is charged per file per assistant; deleting unused files reduces costs. Files can be reused across multiple assistants and threads, but each association incurs a separate storage charge.

The File Search tool indexes uploaded files (PDFs, text, code) using OpenAI's embedding model and enables assistants to retrieve relevant passages via semantic search. Files are chunked, embedded, and stored in a managed vector index. When an assistant queries the index, it retrieves the most relevant chunks based on cosine similarity, then includes them in the prompt context. This enables RAG-style retrieval without managing embeddings or vector databases.

Assistants can invoke multiple tools (Code Interpreter, File Search, custom functions) in parallel or sequence based on task requirements. Tool calls are defined via JSON schema (OpenAI function calling format), and the assistant decides which tools to invoke and in what order. Results from tool calls are fed back into the assistant's context, enabling iterative refinement. Supports both parallel execution (multiple tools called simultaneously) and sequential chaining (tool output feeds into next tool's input).

Assistants can receive file attachments (PDFs, images, code, data files) within messages, which are automatically indexed and made available for retrieval or analysis. Files are stored in OpenAI's managed file storage and can be referenced by subsequent messages in the thread. The assistant can analyze file content via Code Interpreter, search file content via File Search, or reference files in function calls. Files persist within a thread and are accessible across multiple turns.

Assistants support server-sent events (SSE) streaming for real-time response generation, where message content is streamed token-by-token to the client as it's generated. Streaming includes events for message creation, content blocks, and tool calls, enabling clients to display responses incrementally. This reduces perceived latency and allows users to see assistant reasoning in real-time, including tool invocations and code execution.

Assistants are configured with custom instructions (system prompts) that define behavior, tone, expertise, and constraints. Instructions are stored server-side and applied to all runs of the assistant without requiring clients to manage prompts. Instructions can be updated without creating new assistants, enabling behavior changes across all threads. Instructions are combined with user messages and tool results to form the complete context for each model invocation.

Assistants are bound to a specific model version (e.g., gpt-4-turbo, gpt-3.5-turbo) at creation time. The model can be updated via the API, enabling assistants to be upgraded to newer model versions without recreating threads or losing conversation history. Model selection affects capability, cost, and latency. OpenAI manages model versioning and deprecation; assistants can be migrated to new model versions as they become available.

Assistants can be configured to enforce structured output via JSON mode, where the model is constrained to generate valid JSON matching a specified schema. This enables reliable extraction of structured data from assistant responses without post-processing or parsing. JSON mode uses the model's native structured output capability (available in gpt-4-turbo and later), ensuring schema compliance at generation time rather than post-hoc validation.

Assistants execute via 'runs' — stateful objects representing a single invocation of an assistant on a thread. Runs have explicit lifecycle states (queued, in_progress, completed, failed, expired) that clients can poll or stream. Run status includes metadata like created_at, started_at, completed_at, and failure reasons. Clients can cancel runs, retrieve run history, and inspect tool calls and usage within a run. This enables observability and error handling at the run level.