English for OpenAI Assistants API

The OpenAI Assistants API introduces its own set of abstractions for building stateful, tool-using AI applications, distinct from a simple chat completion call. Developers integrating the Assistants API need precise English to describe threads, runs, and tool invocations accurately, especially when writing integration docs or explaining asynchronous behavior to a team used to synchronous request-response APIs. This vocabulary will help you communicate clearly about the API’s specific building blocks.

Key Vocabulary

Assistant — a persistent configuration object that defines a model, instructions, and available tools, reused across many conversations rather than recreated on every request. “We created one assistant for customer support and configured it with our knowledge base through file search.”

Thread — a persistent conversation session that stores message history, allowing an assistant to maintain context across multiple turns without the client resending the full history each time. “Each customer gets their own thread, so we don’t have to manage conversation history manually on our side.”

Run — a single execution of an assistant against a thread, representing the process of the model reading the thread and generating a response, potentially invoking tools along the way. “The run stayed in the requires_action state because the assistant was waiting for us to submit the function’s output.”

Function calling — a mechanism that lets the assistant request execution of a developer-defined function, receiving structured arguments and later consuming the function’s output before continuing. “We used function calling to let the assistant check real-time inventory before confirming an order.”

Run status — the current state of a run, such as queued, in_progress, requires_action, or completed, which determines what action the client should take next. “Poll the run status until it reaches completed, and handle requires_action separately for function calls.”

File search — a built-in tool that lets the assistant retrieve relevant information from uploaded documents, functioning as managed retrieval-augmented generation. “We uploaded our product documentation and enabled file search so the assistant can answer questions with citations.”

Code interpreter — a built-in tool that gives the assistant a sandboxed environment to write and execute Python code, useful for data analysis or file manipulation tasks. “The code interpreter let the assistant generate a chart directly from the CSV file the user uploaded.”

Tool output submission — the step where the client sends the result of a called function back to the API so the run can continue and the assistant can incorporate the result into its response. “Don’t forget the tool output submission step — the run will stay stuck in requires_action until you send it.”

Common Phrases

• “The run is stuck in requires_action — did we submit the tool outputs yet?”
• “Let’s keep conversation state in the thread instead of resending message history ourselves.”
• “File search returned an irrelevant chunk — we may need to revisit how we split the documents.”
• “This looks like a good candidate for the code interpreter tool rather than a custom function.”
• “We’re polling run status every second; should we switch to streaming instead?”
• “The assistant’s instructions are too broad — let’s scope them down to reduce off-topic responses.”

Example Sentences

When explaining the Assistants API to a non-technical stakeholder: “This API lets our AI assistant remember the conversation and use tools, like searching our documents or running calculations, so it can give more accurate and personalized answers instead of just generating text from memory.”

When filing a support ticket: “A run remains in the requires_action state indefinitely after we submit tool outputs for a function call with an array argument. We’ve attached the thread ID and the exact payload we submitted.”

When discussing architecture in a team meeting: “I’d suggest we use one thread per customer session rather than one long-lived thread per customer, so context doesn’t grow unbounded and older, irrelevant messages don’t affect newer answers.”

Professional Tips

• Distinguish “thread” from “run” precisely — the thread holds the conversation, while a run is one execution against it; conflating them confuses async status-handling logic in code reviews.
• When reporting a bug, always include the run status and thread ID — these are the two most useful identifiers for reproducing issues with OpenAI support.
• Say “we submitted the tool outputs” rather than “we answered the function call” — it matches the API’s exact terminology and avoids ambiguity in technical discussions.
• Clarify whether a feature uses the built-in file search or a custom retrieval function when documenting architecture — they behave very differently in terms of cost and control.

Practice Exercise

1. A colleague new to the API asks what a thread is for. Write two to three sentences explaining threads versus runs in plain English.
2. Write a one-sentence PR description for adding a new function-calling tool that lets the assistant look up a user’s order status.
3. Explain in one sentence why polling run status is necessary when using function calling.