OpenAI Assistants API: The Complete Guide

OpenAI Assistants API is a framework for building AI assistants with built-in tools. Let’s cover everything from creation to deployment.

What Is Assistants API

Assistants API provides three built-in tools:

1. Code Interpreter — execute Python code, analyze data, create visualizations
2. File Search — search through uploaded documents (RAG out of the box)
3. Function Calling — call your own custom functions

Creating an Assistant

from openai import OpenAI

client = OpenAI()

assistant = client.beta.assistants.create(
    name="Business Analyst",
    instructions="""You are a business analyst for a startup.
    Analyze data, create reports and visualizations.
    Be concise and actionable.""",
    model="gpt-4o",
    tools=[
        {"type": "code_interpreter"},
        {"type": "file_search"},
    ],
)

Working with Threads

Assistants API uses threads — persistent conversation contexts:

# Create a thread
thread = client.beta.threads.create()

# Add a message
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Analyze sales for the last quarter",
)

# Run the assistant
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant.id,
)

# Get the response
if run.status == "completed":
    messages = client.beta.threads.messages.list(thread_id=thread.id)
    for msg in messages.data:
        if msg.role == "assistant":
            print(msg.content[0].text.value)

Function Calling

Add your own functions for external integrations:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_sales_data",
            "description": "Gets sales data for a given period",
            "parameters": {
                "type": "object",
                "properties": {
                    "start_date": {
                        "type": "string",
                        "description": "Start date (YYYY-MM-DD)"
                    },
                    "end_date": {
                        "type": "string",
                        "description": "End date (YYYY-MM-DD)"
                    },
                },
                "required": ["start_date", "end_date"],
            },
        },
    }
]

Handling Function Calls

if run.status == "requires_action":
    tool_calls = run.required_action.submit_tool_outputs.tool_calls

    tool_outputs = []
    for tool_call in tool_calls:
        if tool_call.function.name == "get_sales_data":
            args = json.loads(tool_call.function.arguments)
            result = get_sales_from_db(args["start_date"], args["end_date"])
            tool_outputs.append({
                "tool_call_id": tool_call.id,
                "output": json.dumps(result),
            })

    run = client.beta.threads.runs.submit_tool_outputs_and_poll(
        thread_id=thread.id,
        run_id=run.id,
        tool_outputs=tool_outputs,
    )

File Search (Built-in RAG)

Upload documents and the assistant automatically searches through them:

# Create a vector store
vector_store = client.beta.vector_stores.create(name="Product Documentation")

# Upload files
file = client.files.create(
    file=open("docs/product-guide.pdf", "rb"),
    purpose="assistants",
)

client.beta.vector_stores.files.create(
    vector_store_id=vector_store.id,
    file_id=file.id,
)

# Attach to assistant
assistant = client.beta.assistants.update(
    assistant_id=assistant.id,
    tool_resources={
        "file_search": {"vector_store_ids": [vector_store.id]}
    },
)

Comparison with Claude Tool Use

Aspect	Assistants API	Claude Tool Use
State	Managed (threads)	Stateless
RAG	Built-in (file search)	Build your own
Code execution	Code Interpreter	None
Protocol	Proprietary	MCP (open)
Cost	Higher (threads + storage)	Lower

Recommendation

Assistants API is great when you need Code Interpreter or built-in RAG. For custom agents with external integrations, consider Claude Tool Use.