OpenAI Agents SDK in Practice: Build a Multi-Agent Support Triage Bot, Step by Step

Most teams don’t start with a blank page. They start with 600 lines of if/else statements that route support tickets by keyword, break every time a customer writes “my card isn’t working” instead of “billing issue”, and take a week to debug. Rewriting that with the OpenAI Agents SDK takes an afternoon, and the result is readable by anyone on the team.

Here’s the build we’ll walk through: a triage agent that reads an incoming ticket, classifies it with a typed output, hands it to the right specialist, refuses anything out of scope, and leaves a trace you can inspect when it gets something wrong. Every step below is code you can run today.

The four primitives you’ll actually use

The SDK is small on purpose. Four ideas cover 90% of production agents, and it’s worth knowing what each one is before you write anything.

• Agents — a model, a set of instructions, optional tools, and an optional output schema. Nothing more.
• Handoffs — one agent transferring control to another. The SDK implements this as a tool call under the hood, so the model decides when to route.
• Guardrails — validation that runs alongside or before the main agent and can trip the whole run.
• Sessions and tracing — conversation history that persists across turns, plus a dashboard showing every model call, tool call, and handoff.

If you want the wider picture of how these pieces fit into deployment and scaling, there’s a solid breakdown in building and scaling agents without the usual chaos. This piece stays on the ground, building one working thing.

Step 1: Get a single agent running

Install the package and set your API key:

pip install openai-agents

Then write the smallest useful agent. Resist the urge to add tools yet.

from agents import Agent, Runner

triage = Agent(
    name="Triage",
    instructions=(
        "Read each support message and decide whether it is billing, "
        "technical, or account-related. Reply with one word."
    ),
    model="gpt-4o-mini",
)

result = Runner.run_sync(triage, "I was charged twice for the Pro plan in March.")
print(result.final_output)

Two things to notice. Instructions are plain English, and the model is specified per agent — routing work does not need your most expensive model. Running this costs a fraction of a cent and takes about a second.

Step 2: Replace the prose output with a schema

“Reply with one word” works until the model replies with “billing-related.” Use output_type and Pydantic instead, and you get a validated object back rather than a string you have to parse with regex.

from pydantic import BaseModel

class Triage(BaseModel):
    category: str
    urgency: int      # 1-5
    summary: str      # one sentence, no jargon

triage = Agent(
    name="Triage",
    instructions="Classify the ticket. urgency runs from 1 (cosmetic) to 5 (outage).",
    output_type=Triage,
    model="gpt-4o-mini",
)

result = Runner.run_sync(triage, "Checkout is failing on Safari for every customer.")
ticket = result.final_output_as(Triage)
print(ticket.category, ticket.urgency)

That single change removes most of the error handling you’d otherwise write. If you like this style of type-driven agent design, the same philosophy shows up in type-safe AI agents built the FastAPI way — worth a read even if you stay on the OpenAI SDK, because the mental model transfers.

Step 3: Route work with handoffs

A triage agent that also tries to solve the ticket will solve it badly. Give it specialists and let it hand off.

billing = Agent(
    name="Billing",
    handoff_description="Invoices, refunds, failed payments, plan changes.",
    instructions="Resolve billing questions. If a refund exceeds $200, escalate to a human.",
)

technical = Agent(
    name="Technical",
    handoff_description="API errors, checkout bugs, webhook failures, integration problems.",
    instructions="Diagnose the problem and file an engineering ticket with reproduction steps.",
)

triage = Agent(
    name="Triage",
    instructions="Route the ticket to the right specialist. Never answer it yourself.",
    handoffs=[billing, technical],
)

The handoff_description field does more work than it looks like. It’s what the routing model reads when deciding where to send a ticket, so write it like a job posting, not a label. “Billing” tells the model almost nothing; “Invoices, refunds, failed payments, plan changes” gives it something to match against.

Step 4: Block bad input before it costs you money

Guardrails are the part teams skip and then regret. An input guardrail runs a cheap check on incoming messages and can abort the run before the expensive specialist agent ever sees the text.

from agents import GuardrailFunctionOutput, RunContextWrapper, input_guardrail

class ScopeCheck(BaseModel):
    is_support_ticket: bool
    reason: str

scope_agent = Agent(
    name="Scope check",
    instructions="Decide whether this message is a support request about our product.",
    output_type=ScopeCheck,
    model="gpt-4o-mini",
)

@input_guardrail
async def scope_guardrail(ctx: RunContextWrapper, agent: Agent, user_input: str):
    check = await Runner.run(scope_agent, user_input, context=ctx.context)
    return GuardrailFunctionOutput(
        output_info=check.final_output,
        tripwire_triggered=not check.final_output.is_support_ticket,
    )

Attach it with input_guardrail=scope_guardrail on the triage agent. A tripped wire raises InputGuardrailTripwireTriggered, which you catch and turn into whatever your product actually does — a soft rejection, a handoff to a human queue, a logging event.

Safety features have moved fast here, and the recent SDK updates aimed at safer enterprise agents are worth tracking as you harden a production deployment. The short version: budget one guardrail per real failure you’ve seen, not per failure you can imagine.

Step 5: Give agents tools, including a code sandbox

A specialist with no tools is just a chatbot with a job title. Function tools are plain Python, wrapped and described by their docstring.

from agents import function_tool

@function_tool
def lookup_account(email: str) -> dict:
    """Look up a customer account and recent invoices by email address."""
    return crm.find_by_email(email)

Two extensions worth knowing about. When you need the agent to touch Slack, HubSpot, Jira or Notion, hand-writing OAuth flows for each one is a week of your life — prebuilt tool integrations for agents let you skip that entirely. And when an agent needs to actually execute Python rather than describe it, running real code inside an isolated sandbox is the safe pattern. Never let generated code run on your application host.

Step 6: Add memory and switch on tracing

Without a session, every run starts cold. The customer says “still broken” and the agent has no idea what “still” refers to.

from agents import SQLiteSession

session = SQLiteSession("ticket-88213")
await Runner.run(triage, "Still broken after the fix you suggested.", session=session)

Swap SQLite for Redis or Postgres when you leave your laptop behind. If persistent agent memory becomes the core of what you’re building rather than a convenience, it’s worth comparing approaches — self-editing memory for long-running agents goes well past what a message-history session gives you.

Then turn on tracing, which is on by default once your API key is set. Every handoff, tool call, and token count lands in a dashboard. The first time a ticket goes to the wrong agent, you’ll open the trace and see the exact routing decision — usually within thirty seconds. That beats adding print statements.

Where teams actually get stuck

The code above compiles in an afternoon. The failures show up later, and they’re almost always the same five.

• Model choice drift. Someone upgrades every agent to a frontier model “for quality” and the monthly bill triples. Routing belongs on a small model. Reserve the expensive one for the specialist writing the final response.
• Guardrails on everything. Each guardrail is another model call on every message. One input check and one output check is usually enough.
• Runaway loops. A handoff that bounces between two agents will happily do it forever. Set max_turns on your runs and log when you hit it.
• Instructions that read like a policy document. Eight hundred words of instructions dilutes the three rules that matter. If a rule is important, it goes first and it’s one sentence.
• No evaluation set. Before launch, paste 20 real historical tickets into a test script and assert the expected category and handoff target for each. Re-run it after every prompt change. This is the single highest-return hour you’ll spend on the project.

Build the triage bot first, with the 20-ticket test set in place before you touch a prompt. Everything after that — more specialists, more tools, a human-in-the-loop approval step for refunds over $200 — is an incremental change to something already working, which is a much easier thing to argue for in a sprint review.