Last month, I was building an internal tool to help our support team triage incoming tickets. I started with a simple chat prompt wrapped around the OpenAI API, but I quickly hit a wall. The model could suggest responses, but it couldn't do anything—it couldn't look up order statuses, categorize tickets, or escalate issues. It was just a fancy text generator. I needed something that could take actions based on context, follow specific rules, and hand off tasks when necessary.
That's when I started exploring the OpenAI Agent Platform and the Agents SDK. If you're in a similar spot—needing your LLM to move from just chatting to actually executing tasks—here's a practical walkthrough of how I got started, including the bumps I hit along the way.
The Core Concept: Agents vs. Chatbots
The biggest mindset shift for me was understanding that an agent is not just a chatbot. A standard chat LLM responds to "What's the weather in Paris?" by generating text based on its training data. An agent, on the other hand, can be instructed to always provide up-to-date information and equipped with a weather API tool to actually fetch the real data.
Agents are configurable. You give them a role, specific instructions, tools to interact with the outside world, and even guardrails to keep them from going off the rails. They can also delegate work to other specialized agents.
Step 1: Installation and Setup
First, you need to install the OpenAI Agents SDK. Make sure you have Python 3.8+ and your OpenAI API key ready.
pip install openai-agents
Set your API key as an environment variable. I prefer putting this in a .env file and loading it with python-dotenv, but do whatever works for your setup:
export OPENAI_API_KEY="sk-your-api-key-here"
Mistake #1: I initially tried just running pip install agents, which is a completely unrelated package. The correct package name is openai-agents. Save yourself the confusion.
Step 2: Defining Your First Agent
The SDK uses a straightforward, code-first approach. You define an agent by giving it a name, a set of instructions, and specifying which model it should use.
Here's the actual code I wrote for my ticket triage agent:
from agents import Agent, Runner
# Define the agent
triage_agent = Agent(
name="Ticket Triage Assistant",
instructions="""You are a support ticket triage agent.
Your job is to read incoming support tickets and:
1. Categorize them (billing, technical, account, general)
2. Determine urgency (low, medium, high, critical)
3. Provide a brief summary
Always be concise. Do not attempt to solve the problem yourself.
If a ticket is critical, explicitly flag it for immediate human review.""",
model="gpt-4o"
)
The instructions parameter is where the magic happens. Think of it like a detailed job description. The more specific you are, the better the agent performs. I learned this the hard way—my first draft just said "triage tickets," and the agent kept trying to solve the technical problems instead of just categorizing them. Adding "Do not attempt to solve the problem yourself" completely fixed that behavior.
Step 3: Running the Agent
Once you've defined the agent, you run it using the Runner class. This is what actually sends the input to the model and processes the response.
async def main():
# A sample ticket
ticket_text = """
Subject: Can't log in
Body: I've been trying to log into my account for the past hour.
I've reset my password twice but I keep getting an 'invalid credentials' error.
This is urgent—I have a presentation in 30 minutes!
"""
result = await Runner.run(triage_agent, ticket_text)
print(result.final_output)
# Run it
import asyncio
asyncio.run(main())
Here's the output I got:
Category: Technical
Urgency: Critical
Summary: User unable to log in despite multiple password resets; facing an 'invalid credentials' error. Flagged for immediate human review due to time-sensitive presentation.
Clean, structured, and exactly what I asked for.
Step 4: Adding Tools (Where Agents Get Powerful)
Text in, text out is fine, but the real power comes when you give agents tools. Let's add a function that looks up order status from our database.
from agents import Agent, Runner, function_tool
# Define a tool
@function_tool
def get_order_status(order_id: str) -> str:
"""Fetches the current status of an order given its ID."""
# In reality, this would query your database
mock_database = {
"ORD-1234": "Shipped - Expected delivery tomorrow",
"ORD-5678": "Processing - Fulfillment in progress",
}
return mock_database.get(order_id, "Order not found")
# Attach the tool to the agent
order_agent = Agent(
name="Order Status Agent",
instructions="""You help customers check their order status.
When a customer provides an order ID, use the get_order_status tool
to fetch real-time information. If they don't provide an order ID,
politely ask for one.""",
tools=[get_order_status],
model="gpt-4o"
)
Now when you run it:
result = await Runner.run(order_agent, "Where is my order ORD-1234?")
print(result.final_output)
Output:
Your order ORD-1234 is currently shipped and is expected to be delivered tomorrow!
The agent recognized the order ID in the text, decided to call the tool, and then formulated a natural language response based on the tool's output. No manual parsing required.
Surprise: The docstring on the tool function matters a lot. The agent uses the docstring to understand when and how to use the tool. I initially wrote a vague docstring and the agent kept calling the tool with the wrong arguments. Be explicit about what the tool does and what inputs it expects.
Step 5: Multi-Agent Handoffs
This was the feature I was most excited about. In our support system, I wanted the triage agent to hand off billing tickets to a billing specialist, and technical tickets to a tech support agent.
from agents import Agent, Runner, handoff
# Define specialist agents
billing_agent = Agent(
name="Billing Specialist",
instructions="You handle billing inquiries. Be empathetic and precise about charges and refunds.",
model="gpt-4o"
)
tech_agent = Agent(
name="Tech Support",
instructions="You troubleshoot technical issues. Ask clarifying questions and provide step-by-step solutions.",
model="gpt-4o"
)
# Triage agent with handoffs
triage_agent = Agent(
name="Ticket Triage",
instructions="""Read the support ticket and route it appropriately:
- Billing issues -> hand off to Billing Specialist
- Technical issues -> hand off to Tech Support
- General inquiries -> handle yourself with a brief response""",
handoffs=[
handoff(to_agent=billing_agent),
handoff(to_agent=tech_agent),
],
model="gpt-4o"
)
When you run the triage agent with a billing question, it automatically transfers the conversation to the billing agent. The SDK handles the context passing behind the scenes.
Practical Tips and Honest Limitations
Tips I wish I had on day one:
Be obsessively specific with instructions. Treat your agent like a new employee who knows nothing about your company. "Categorize tickets" is bad. "Categorize tickets into exactly one of: billing, technical, account, general. Output the category as a single word" is good.
Always include a docstring on your tools. The agent reads this to decide whether to use the tool. No docstring means the agent is basically guessing.
Start simple, then add complexity. Get a basic agent running first. Then add tools. Then add handoffs. Trying to build the whole multi-agent system on day one is a recipe for frustration.
Use
gpt-4ofor agents with tools. I tried usinggpt-4o-minito save costs, but it struggled with tool selection and following complex instructions. The cost difference is worth the reliability gain.
Honest limitations:
Agents can still hallucinate tool calls. If you describe a tool poorly, the agent might try to call it with made-up parameters. Guardrails help, but they aren't bulletproof.
Handoffs can lose context. When an agent hands off to another, the context transfer isn't perfect. Long conversation histories sometimes get truncated, leading to the second agent missing important details.
Debugging is still tricky. When a multi-agent workflow goes wrong, tracing exactly which agent made a bad decision and why requires digging through the Runner's trace logs. The tooling for this is still maturing.
Latency adds up. Each agent decision is an API call. A triage agent handing off to a specialist agent that then calls a tool is at least three sequential LLM calls. For real-time applications, this can feel sluggish.
Despite these limitations, the OpenAI Agent Platform is the most practical agent framework I've used. The code-first approach means I can version control my agent definitions, test them in CI, and deploy them like any other Python service. If you've been frustrated by chatbots that can't actually do anything, give it a shot—just start small and iterate.