The short answer
Install openai, set OPENAI_API_KEY, create an Assistant with instructions and tools, create a Thread for each conversation, add Messages, and Run the Assistant. The Assistant handles the loop between model and tools. You get a working agent in about 40 lines of Python. This guide walks a full working example with code interpreter and a custom function tool.
OpenAI’s Assistants API is their agent primitive. Instead of writing the tool-calling loop yourself, you create a persistent Assistant with its own instructions and tool set, then spawn Threads for each user conversation. The API keeps track of state, runs the agent loop, and returns results when the task is done.
This tutorial builds two agents from scratch: one that analyzes CSV files with the built-in code interpreter, and one with a custom function tool that calls an external API. By the end you will have the mental model and working code to adapt for your own use case.
Core concepts in three sentences
An Assistant is a reusable configuration: name, instructions, model, tools. A Thread is a conversation, holding a list of Messages. A Run is one turn of the Assistant on a Thread; it may call tools, and when it is done the latest Messages contain the answer.
Install and authenticate
pip install openai export OPENAI_API_KEY=your_key_here
Grab a key from platform.openai.com. Set up billing before you expect to go past the free tier.
First agent: a CSV data analyst
The code interpreter is a sandboxed Python environment OpenAI runs for you. Upload a file, ask the Assistant a question, and it writes and runs Python to answer.
from openai import OpenAI
client = OpenAI()
file = client.files.create(
file=open("sales_q4.csv", "rb"),
purpose="assistants",
)
assistant = client.beta.assistants.create(
name="CSV Analyst",
instructions="Analyze the uploaded CSV. Produce short answers with clear numbers.",
model="gpt-4o",
tools=[{"type": "code_interpreter"}],
tool_resources={"code_interpreter": {"file_ids": [file.id]}},
)
thread = client.beta.threads.create()
client.beta.threads.messages.create(
thread_id=thread.id,
role="user",
content="What was the top-selling product last month and its revenue?",
)
run = client.beta.threads.runs.create_and_poll(
thread_id=thread.id, assistant_id=assistant.id,
)
for msg in reversed(list(client.beta.threads.messages.list(thread.id).data)):
if msg.role == "assistant":
print(msg.content[0].text.value)
breakRun this against a CSV and it will work out the answer by writing pandas code, executing it in the sandbox, and returning the natural-language result. You did not write any pandas yourself.
Second agent: a custom function tool
For tools the Assistant cannot provide itself (your APIs, your databases), you define a function schema and handle the call yourself. The API tells you when a tool call is needed, you run it, and you submit the result back.
def get_weather(city: str) -> str:
# Call a real API in production. Dummy data here.
return f'{{"city": "{city}", "temp_c": 22, "condition": "sunny"}}'
assistant = client.beta.assistants.create(
name="Weather Agent",
model="gpt-4o",
tools=[{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather in a city.",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}],
)
thread = client.beta.threads.create()
client.beta.threads.messages.create(
thread_id=thread.id, role="user",
content="What's the weather in Tokyo?",
)
run = client.beta.threads.runs.create(thread_id=thread.id, assistant_id=assistant.id)
while True:
run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id)
if run.status == "requires_action":
outputs = []
for call in run.required_action.submit_tool_outputs.tool_calls:
if call.function.name == "get_weather":
args = eval(call.function.arguments) # use json.loads in prod
outputs.append({"tool_call_id": call.id, "output": get_weather(args["city"])})
client.beta.threads.runs.submit_tool_outputs(
thread_id=thread.id, run_id=run.id, tool_outputs=outputs,
)
elif run.status == "completed":
breakThe pattern holds for any function: declare it in tools, implement it in Python, poll until the run hits requires_action, dispatch, submit outputs. For production use json.loads instead of eval and add a timeout to the poll.
File search for retrieval-augmented generation
The file_search tool lets the Assistant answer questions grounded in documents you upload. Upload PDFs, markdown, or text files. The API chunks them, embeds them, and retrieves relevant chunks at query time.
vector_store = client.beta.vector_stores.create(name="product docs")
client.beta.vector_stores.file_batches.upload_and_poll(
vector_store_id=vector_store.id,
files=[open("product_manual.pdf", "rb"), open("faq.md", "rb")],
)
assistant = client.beta.assistants.create(
name="Docs Bot",
model="gpt-4o",
tools=[{"type": "file_search"}],
tool_resources={"file_search": {"vector_store_ids": [vector_store.id]}},
)Query the Assistant in a Thread like any other, and it cites which part of which document it used. Useful for internal knowledge bases and customer support.
Streaming responses
For a chat UI you want tokens as they arrive. Use create_and_stream instead of create_and_poll and iterate:
with client.beta.threads.runs.stream(
thread_id=thread.id, assistant_id=assistant.id,
) as stream:
for event in stream:
if event.event == "thread.message.delta":
print(event.data.delta.content[0].text.value, end="", flush=True)Pricing and quotas
You pay for the model’s tokens (same as Chat Completions) plus modest overhead for the Assistants infrastructure. Code interpreter runs are billed per session at a small flat fee. File search storage is a few cents per GB per day.
For a well-used internal tool handling 1,000 queries daily on GPT-4o, expect $50 to $150 monthly in token costs. Code interpreter sessions add maybe $5 to $20.
When Assistants API is the right choice
Use it when you need persistent state across turns, built-in code execution, or built-in RAG. If you want to ship a “chat with your docs” product without building the retrieval pipeline, Assistants API saves weeks.
Use the standard Chat Completions API when you want full control over the tool-calling loop, lower latency, or to avoid state on OpenAI’s side. For single-turn tasks, Chat Completions has lower overhead.
Common pitfalls to avoid
- Using eval on tool arguments. The model may return JSON that is also valid Python, but it can also return structures that evaluate dangerously. Always use json.loads with a try block.
- Polling with a fixed sleep. Use exponential backoff starting at 500 ms; most runs complete in under 5 seconds, no need to hammer the API.
- Creating a new Assistant on every request. Assistants are meant to be reusable; create once at startup, reuse across every Thread.
- Letting Threads grow unbounded. Very long Threads cost more tokens per turn as context grows; summarize and reset when the Thread becomes expensive.
- Skipping error handling on tool execution. If your tool raises, the Run fails. Catch exceptions inside the tool and return a structured error the model can reason about.
Production Assistants that run cleanly pair the API with your own observability: log every Run status transition, every tool call, every token count. Without that you cannot tell whether the model is thinking or stuck.
Frequently asked questions
What is the difference between Assistants API and Chat Completions?
Chat Completions is stateless; you send the full conversation on each call. Assistants API holds state for you (Threads), runs tools in a loop, and offers built-in tools like code interpreter and file search. Assistants trade some control for a lot of built-in machinery.
Which model should I use for an Assistant?
gpt-4o for quality, gpt-4o-mini for cost and speed. Start with 4o-mini for simple chat and function calling; upgrade to 4o when the task involves reasoning, long context, or complex tool chains.
How long does a Thread persist?
Indefinitely until you delete it. You can list Messages in a Thread at any time. For privacy-sensitive apps, explicitly delete Threads after the user session ends.
Can I use the same Assistant across many users?
Yes. The Assistant is the configuration; each user gets their own Thread. One Assistant can serve millions of users, each with their own conversation history.
Does the Assistants API support streaming?
Yes. Use create_and_stream or the stream parameter. You get events for message deltas, tool call deltas, and run status changes. The pattern is similar to streaming on Chat Completions but with more event types.
Is there a Node.js SDK?
Yes. The openai npm package mirrors the Python API. All the same concepts (Assistant, Thread, Run, Message) with the same method names. JavaScript developers can follow this tutorial with minor syntax changes.
