How to Build an AI Agent with OpenAI Assistants API

Most people who try to build an AI agent with OpenAI end up with a glorified chatbot that can't actually do anything useful.

Why the Assistants API Still Matters (Even Though It's Sunsetting)

Here's something most tutorials won't tell you upfront: OpenAI announced the Assistants API beta will sunset on August 26, 2026. The Responses API is the future direction for building agents on OpenAI's platform.

So why write a tutorial covering it? Two reasons.

First, the Assistants API is still the simplest way to understand how OpenAI agents work. The concepts — Assistants, Threads, Messages, Runs — map cleanly to what an agent actually does. If you learn these, the transition to the Agents SDK or Responses API is trivial.

Second, the Assistants API handles conversation state management for you automatically. For many use cases in production right now, that built-in state management is still easier than rolling your own. You have until August 2026 to migrate, and OpenAI provides a migration guide.

The real takeaway: learn the concepts here, then build production systems with the Agents SDK.

What You Need Before You Start

Before writing a single line of code, get these three things set up:

An OpenAI API key. Sign up at platform.openai.com, add a payment method, and generate an API key. Store it as an environment variable — never hardcode it in your scripts.

Python 3.10 or newer. The Agents SDK requires Python 3.10 at minimum. Check your version with python --version and upgrade if needed.

A code editor. VS Code, PyCharm, or even a Jupyter notebook works. Pick whatever you're comfortable with.

Cost-wise, expect to spend $10-30 per month for basic agent usage with GPT-4o. If you're just experimenting, GPT-4o-mini drops costs by roughly 90% while still being capable enough for most agent tasks.

Step 1: Understand the Core Architecture

Every OpenAI agent — whether built with the Assistants API or the Agents SDK — has four components:

The Model. This is the LLM brain. GPT-4o is the default choice for agents because it handles complex reasoning and tool use well. GPT-4o-mini works for simpler tasks at a fraction of the cost.

Instructions. These are the system-level directives that tell the agent who it is, what it should do, and how it should behave. Think of instructions as the agent's job description. Clear instructions reduce ambiguity and improve decision-making — this is the single biggest lever you have for agent quality.

Tools. Tools are what make an agent more than a chatbot. OpenAI supports three built-in tool types: Function Calling (trigger external APIs and custom code), Code Interpreter (write and execute Python in a sandboxed environment), and File Search (perform RAG over uploaded documents). You can also define custom tools using the Model Context Protocol (MCP).

Orchestration. This is the loop that ties everything together — the agent receives input, decides which tool to use, executes it, evaluates the result, and either responds or takes another action. The Assistants API handles this loop for you. The Agents SDK gives you more control over it.

Step 2: Build a Basic Agent with the Assistants API

Install the OpenAI Python package:

pip install openai

Now create a simple research assistant that can search through documents:

import openai
import os

client = openai.OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

# Create an Assistant
assistant = client.beta.assistants.create(
    name="Research Assistant",
    instructions="""You are a research assistant that helps users
    find and summarize information. Always cite your sources and
    provide specific data points when available.""",
    model="gpt-4o",
    tools=[{"type": "code_interpreter"}, {"type": "file_search"}]
)

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

# Add a Message
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Analyze the quarterly revenue trends from the uploaded data."
)

# 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)

This creates an assistant with code interpretation and file search capabilities, starts a conversation thread, sends a message, and retrieves the response. The create_and_poll method handles the execution loop automatically.

Step 3: Add Function Calling for Real-World Actions

Function calling is where agents get powerful. Instead of just answering questions, your agent can trigger actual actions in external systems.

Here's how to add a custom function that checks inventory levels:

tools = [
    {
        "type": "function",
        "function": {
            "name": "check_inventory",
            "description": "Check current inventory levels for a product",
            "parameters": {
                "type": "object",
                "properties": {
                    "product_id": {
                        "type": "string",
                        "description": "The unique product identifier"
                    },
                    "warehouse": {
                        "type": "string",
                        "enum": ["east", "west", "central"],
                        "description": "Which warehouse to check"
                    }
                },
                "required": ["product_id"]
            }
        }
    }
]

assistant = client.beta.assistants.create(
    name="Inventory Agent",
    instructions="You help manage inventory. When asked about stock levels, use the check_inventory function.",
    model="gpt-4o",
    tools=tools
)

When the agent decides it needs inventory data, it generates a function call with the right parameters. Your code catches that call, executes the actual inventory lookup, and feeds the result back to the agent.

The key insight: the LLM decides when and how to call the function based on the conversation context. You define what functions exist and what they do — the model handles the decision logic.

Step 4: Migrate to the Agents SDK (The Future-Proof Path)

The OpenAI Agents SDK is where you should build production agents. It's lightweight, supports multiple LLM providers (not just OpenAI), and introduces concepts like guardrails and agent handoffs that the Assistants API doesn't have.

Install it:

pip install openai-agents

Here's the same research assistant, rebuilt with the Agents SDK:

from agents import Agent, Runner

agent = Agent(
    name="Research Assistant",
    instructions="""You are a research assistant. Provide specific
    data points and cite sources. Be concise and actionable."""
)

result = Runner.run_sync(agent, "What are the latest trends in AI automation?")
print(result.final_output)

That's dramatically simpler. The SDK handles the orchestration loop, and you focus on defining the agent's behavior.

Step 5: Build Multi-Agent Systems with Handoffs

The real power of the Agents SDK is multi-agent orchestration. You can create specialized agents and have a triage agent route conversations to the right specialist.

from agents import Agent, Runner

sales_agent = Agent(
    name="Sales Specialist",
    instructions="You handle pricing questions and product comparisons. Be persuasive but honest."
)

support_agent = Agent(
    name="Support Specialist",
    instructions="You troubleshoot technical issues. Ask diagnostic questions before suggesting solutions."
)

triage_agent = Agent(
    name="Triage",
    instructions="Route sales questions to Sales Specialist and technical issues to Support Specialist.",
    handoffs=[sales_agent, support_agent]
)

result = Runner.run_sync(triage_agent, "My API integration keeps timing out")
print(result.final_output)  # Routed to Support Specialist

The triage agent reads the user's message, determines which specialist should handle it, and hands off the conversation automatically. Each specialist agent has its own instructions, tools, and personality.

This pattern scales to complex workflows. I've built systems with five to eight specialist agents handling everything from lead qualification to technical onboarding — all orchestrated by a single triage agent.

Step 6: Add Guardrails and Safety Checks

Production agents need guardrails. The Agents SDK has built-in support for input and output validation:

from agents import Agent, InputGuardrail, GuardrailFunctionOutput

async def check_for_pii(ctx, agent, input_text):
    # Check if user input contains sensitive data
    pii_patterns = ["ssn", "social security", "credit card"]
    contains_pii = any(pattern in input_text.lower() for pattern in pii_patterns)
    return GuardrailFunctionOutput(
        output_info={"contains_pii": contains_pii},
        tripwire_triggered=contains_pii
    )

agent = Agent(
    name="Secure Agent",
    instructions="Help users with account inquiries. Never ask for or process PII.",
    input_guardrails=[
        InputGuardrail(guardrail_function=check_for_pii)
    ]
)

Guardrails run before the agent processes input and after it generates output. If a guardrail trips, the agent stops and returns an error instead of processing potentially harmful content.

Other guardrails worth implementing: content moderation via OpenAI's Moderation API, rate limiting to prevent abuse, and output validation to catch hallucinated data before it reaches users.

Step 7: Test, Debug, and Deploy

The Agents SDK includes built-in tracing that logs every step of the agent's decision process. Use it:

from agents import trace

with trace("customer-support-flow"):
    result = Runner.run_sync(triage_agent, user_message)

Tracing captures the full execution flow — which agent handled the request, what tools were called, what decisions were made, and how long each step took. This is invaluable for debugging agent behavior that doesn't match expectations.

For deployment, OpenAI's ChatKit provides an embeddable chat UI that connects to your agentic backend. For custom deployments, the SDK works with any Python web framework — FastAPI and Flask are the most common choices.

Assistants API vs. Agents SDK vs. Agent Builder: Which Should You Use?

My recommendation: start with the Agents SDK. Use the Assistants API only if you need managed conversation state and want something running in under an hour. Skip Agent Builder unless you specifically need a no-code solution.

Common Mistakes That Kill Agent Projects

Starting with multi-agent systems. Build a single agent that does one thing exceptionally well first. OpenAI's own practical guide to building agents says to start with a single agent and evolve to multi-agent systems only when needed. Most tasks don't need multiple agents.

Vague instructions. "Be helpful" is not an instruction. "You are a customer support agent for a SaaS platform. When users report bugs, ask for their account email, the browser they're using, and steps to reproduce. Then check the known issues database before escalating." That's an instruction.

Ignoring cost management. GPT-4o costs roughly $2.50 per million input tokens and $10 per million output tokens. An agent that makes 5-10 tool calls per conversation can cost $0.05-0.15 per interaction. At scale, that adds up. Use GPT-4o-mini for triage and routing, and reserve GPT-4o for complex reasoning steps.

No error handling for tool failures. External APIs go down. Databases timeout. Your agent needs to handle these failures gracefully — retry with backoff, fall back to alternative data sources, or tell the user what happened instead of silently failing.

What's Next: The Shift to Agentic AI

The agent ecosystem is moving fast. Gartner predicts 40% of enterprise applications will embed AI agents by end of 2026, up from less than 5% in 2025. OpenAI's enterprise data shows reasoning token consumption per organization increased 320x in the past 12 months.

The Assistants API taught developers the fundamentals. The Agents SDK and Responses API are now the production-ready tools for building agents that actually work in business contexts. The patterns you learn here — function calling, multi-agent handoffs, guardrails — transfer directly to whatever framework comes next.

Start with one agent. Give it one job. Make it reliable. Then scale.