The OpenAI Agents SDK: Agents, Handoffs, Guardrails, Sessions, Tracing

Today's Goals

1. Write a minimal agent with a function tool using Agent and run or Runner, and explain what maxTurns does
2. Use handoffs to let a triage agent pass the conversation to a specialist agent, and explain the trade-off against "one big agent with many tools"
3. Write an input-side guardrail and catch its tripwire exception, and explain the split between input-side and output-side guardrails

Yesterday you hand-wrote one round trip of request-a-tool, execute, feed back. Today's questions are: what if that round trip has to run many times over? What if the work is too varied for one contractor? And how do you stop them from taking on work they should not, or saying things they should not? Once you have read this and finished the work, scroll back to the top and tick off the three goals.

Plain-Language Walkthrough

Agent and Runner: folding model, loop, and tools into one object and one function

In yesterday's script, the loop of the model requesting a tool, you executing it, feeding the result back, and asking again ran exactly once. Real tasks usually need several rounds: look up the list, then the details, then decide what to change. Hand-writing that while loop is not hard, but writing it again in every project gets tiresome, and there are edges to handle — a loop that will not stop, tools that throw, arguments that will not parse. The first thing OpenAI's Agents SDK does is put that loop away: the Agent object holds the instructions and the tools, and the run function turns the loop for you.

Back to the contractor analogy: an agent is a contractor with a clear job description (instructions) and a toolbox (tools); run is you handing over the work and waiting for them to come back with it. How many times they reached for a tool in between and how many rounds they thought is not your concern, only the result — unless the round count runs over.

import { Agent, run, tool } from '@openai/agents'
import { z } from 'zod'
 
const listRoutes = tool({
  name: 'list_routes',
  description: 'List every route of the TODO API',
  parameters: z.object({}),
  execute: async () => ['POST /todos', 'GET /todos', 'DELETE /todos/:id'],
})
 
const helper = new Agent({
  name: 'TODO API helper',
  instructions:
    'Answer only questions about this TODO API project, and call a tool before stating any fact.',
  model: process.env.OPENAI_MODEL,
  tools: [listRoutes],
})
 
const result = await run(helper, 'Which endpoints still have no tests?', { maxTurns: 5 })
console.log(result.finalOutput)

import os
from agents import Agent, Runner, function_tool
 
 
@function_tool
def list_routes() -> list[str]:
    """List every route of the TODO API"""
    return ["POST /todos", "GET /todos", "DELETE /todos/:id"]
 
 
helper = Agent(
    name="TODO API helper",
    instructions=(
        "Answer only questions about this TODO API project, and call a tool before stating any fact."
    ),
    model=os.environ.get("OPENAI_MODEL"),
    tools=[list_routes],
)
 
result = Runner.run_sync(helper, "Which endpoints still have no tests?", max_turns=5)
print(result.final_output)

Compared with yesterday: the tool helper (the function_tool decorator in Python) turns a zod schema or type annotations into the JSON Schema you hand-wrote; execute is yesterday's runTool; and inside run sits yesterday's filter-for-function_call, feed-back-function_call_output, call-again. What it hides is exactly what you wrote by hand yesterday, which is why you know which layer to look in when something breaks.

maxTurns is one parameter you must understand. A turn is one model call, counted once per round of the loop, and exceeding the limit makes the SDK throw MaxTurnsExceededError (the TypeScript default is 10). It is not a performance parameter but a safety valve: an agent that misreads a tool result and keeps calling the same tool will, without that valve, burn money until you notice. Set it by task type in production: three to five rounds is plenty for a question-answering assistant, while a task editing several files may need twenty or more. TypeScript also has a Runner class — new Runner({ ... }) then runner.run() — for sharing one configuration (model, tracing, a default maxTurns) across a batch of runs; a single run is fine with run.

Function tools: declare the parameters and the SDK generates the schema

Tools are the agent's hands. The list_routes of the last section takes no parameters, while real tools almost always do. Declaring them works the same way on both sides — write the parameters in the type system you already know and the SDK converts them to JSON Schema: zod in TypeScript (note the SDK uses zod v4), and type annotations on the function signature plus a docstring in Python.

import { tool } from '@openai/agents'
import { z } from 'zod'
 
const todos = [{ id: 1, title: 'Add validation to POST /todos', done: false }]
 
export const markDone = tool({
  name: 'mark_done',
  description: 'Mark one TODO as done',
  parameters: z.object({
    id: z.number().int().describe('the id of the TODO'),
  }),
  execute: async ({ id }) => {
    const todo = todos.find((t) => t.id === id)
    if (!todo) return `There is no TODO with id ${id}`
    todo.done = true
    return `Done: ${todo.title}`
  },
})

from agents import function_tool
 
todos = [{"id": 1, "title": "Add validation to POST /todos", "done": False}]
 
 
@function_tool
def mark_done(id: int) -> str:
    """Mark one TODO as done
 
    Args:
        id: the id of the TODO
    """
    todo = next((t for t in todos if t["id"] == id), None)
    if todo is None:
        return f"There is no TODO with id {id}"
    todo["done"] = True
    return f"Done: {todo['title']}"

Two engineering habits are worth building. First, the description and the parameter descriptions are interface documentation written for the model, and the more they read like plain speech, the less often the model picks the wrong tool or fills in the wrong argument — "Mark one TODO as done" is far better than "update todo." Second, a tool's return value is also written for the model, so returning "There is no TODO with id 7" beats throwing: a thrown exception hands the error text back to the model, which may or may not understand it, whereas a clear sentence is always understood and can be acted on.

When a tool has side effects (the mark_done above mutates data), think through the point from D1: if the model judges it should call the tool, your code really executes it. At the SDK level you can add a human confirmation with a tool-level guardrail (below) or a mechanism such as needsApproval, and the principle is the same as Codex's approvals — an irreversible action needs a human nod first.

Handoffs: the triage agent passes the whole conversation on

What happens when the work gets varied? Expecting one contractor to know everything is unrealistic. What companies do is triage at the front desk: you ask, the desk decides whose job it is, and then walks you over to that colleague, after which you talk to them directly and the desk stays out of it. In the Agents SDK that is a handoff — and note the difference from a tool: calling a tool means the contractor asked something on your behalf and came back to tell you; a handoff means the contractor gives the conversation to someone else, who answers from then on.

In implementation a handoff is a special tool: give the triage agent a set of handoffs and the SDK generates a tool named transfer_to_<agent_name> per target agent; the moment the triage agent calls one, the runtime hands the conversation (optionally filtered) to the target agent to continue.

import { Agent, run } from '@openai/agents'
import { RECOMMENDED_PROMPT_PREFIX } from '@openai/agents-core/extensions'
 
const validationExpert = new Agent({
  name: 'validation_expert',
  instructions:
    'You handle input validation questions for the TODO API: schema design, error response shapes.',
  model: process.env.OPENAI_MODEL,
})
 
const testingExpert = new Agent({
  name: 'testing_expert',
  instructions: 'You handle unit testing questions for the TODO API: case design, test isolation.',
  model: process.env.OPENAI_MODEL,
})
 
const triage = Agent.create({
  name: 'triage',
  instructions: `${RECOMMENDED_PROMPT_PREFIX}
You are the triage desk. Send validation matters to validation_expert and testing matters to testing_expert; answer anything else yourself, briefly.`,
  model: process.env.OPENAI_MODEL,
  handoffs: [validationExpert, testingExpert],
})
 
const result = await run(triage, 'What should POST /todos return when title is empty?')
console.log(result.lastAgent?.name) // validation_expert
console.log(result.finalOutput)

import os
from agents import Agent, Runner
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX
 
validation_expert = Agent(
    name="validation_expert",
    instructions=(
        "You handle input validation questions for the TODO API: schema design, error response shapes."
    ),
    model=os.environ.get("OPENAI_MODEL"),
)
 
testing_expert = Agent(
    name="testing_expert",
    instructions="You handle unit testing questions for the TODO API: case design, test isolation.",
    model=os.environ.get("OPENAI_MODEL"),
)
 
triage = Agent(
    name="triage",
    instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
You are the triage desk. Send validation matters to validation_expert and testing matters to
testing_expert; answer anything else yourself, briefly.""",
    model=os.environ.get("OPENAI_MODEL"),
    handoffs=[validation_expert, testing_expert],
)
 
result = Runner.run_sync(triage, "What should POST /todos return when title is empty?")
print(result.last_agent.name)  # validation_expert
print(result.final_output)

RECOMMENDED_PROMPT_PREFIX is an official prefix telling the model it is part of a multi-agent system where handing off is a normal operation, and it measurably improves handoff accuracy. result.lastAgent (last_agent in Python) tells you who answered last, which is the most direct way to verify the routing — you will assert on it in the lab. For finer control, wrap it with the handoff() helper: toolNameOverride renames the tool, onHandoff fires a callback at handoff time (logging, notifications), inputFilter filters the history passed to the next agent (dropping earlier tool calls, for example, with ready-made filters such as removeAllTools in the official extensions), and inputType lets the model attach structured metadata at handoff time (a reason, a priority).

So when should you split into several agents with handoffs, and when is one big agent with a pile of tools better? The criterion is not how many tools there are but whether the instructions fight each other. The validation expert's instructions are all about zod and error shapes, the testing expert's all about case isolation and mocks — write both into the same instructions and the model switches between two contexts every time, error rates rise, and the prompt gets longer and more expensive. Split when the instructions are independent and the contexts clearly separable; do not split when the tools are many but share one body of background knowledge. There is also a hard constraint: a handoff happens inside the same run, and input-side guardrails apply only to the first agent in the chain — which leads to the next section.

Guardrails: check the user at the entrance, check the model at the exit

However capable the contractor, two things should not happen: taking on work they should not (a user asking the TODO API helper to write a love poem), and saying something they should not (an answer that leaks a database connection string). The first has to be blocked at the entrance, the second at the exit. The Agents SDK calls those two doors the input guardrail and the output guardrail, collectively guardrails.

A guardrail is a function: it receives the input (or output) and the context and returns a judgment, in which tripwireTriggered (tripwire_triggered in Python) being true means raise the alarm. When the alarm goes off, the run immediately throws InputGuardrailTripwireTriggered or OutputGuardrailTripwireTriggered, which you catch outside and use to decide what to tell the user.

import { Agent, run, InputGuardrailTripwireTriggered } from '@openai/agents'
import type { InputGuardrail } from '@openai/agents'
 
// A guardrail that costs nothing: pure rule, no model call
const onTopicOnly: InputGuardrail = {
  name: 'on_topic_only',
  execute: async ({ input }) => {
    const text = typeof input === 'string' ? input : JSON.stringify(input)
    const offTopic = !/todo|endpoint|validation|test|route|api/i.test(text)
    return { outputInfo: { offTopic }, tripwireTriggered: offTopic }
  },
}
 
const triage = new Agent({
  name: 'triage',
  instructions: 'You handle only questions about the TODO API project.',
  model: process.env.OPENAI_MODEL,
  inputGuardrails: [onTopicOnly],
})
 
try {
  const result = await run(triage, 'Write me a love poem')
  console.log(result.finalOutput)
} catch (err) {
  if (err instanceof InputGuardrailTripwireTriggered) {
    console.log('That is unrelated to the project; I only answer TODO API questions.')
  } else {
    throw err
  }
}

import os
import re
from agents import (
    Agent,
    GuardrailFunctionOutput,
    InputGuardrailTripwireTriggered,
    RunContextWrapper,
    Runner,
    TResponseInputItem,
    input_guardrail,
)
 
 
# A guardrail that costs nothing: pure rule, no model call
@input_guardrail
async def on_topic_only(
    ctx: RunContextWrapper[None], agent: Agent, input: str | list[TResponseInputItem]
) -> GuardrailFunctionOutput:
    text = input if isinstance(input, str) else str(input)
    off_topic = re.search(r"todo|endpoint|validation|test|route|api", text, re.I) is None
    return GuardrailFunctionOutput(output_info={"off_topic": off_topic}, tripwire_triggered=off_topic)
 
 
triage = Agent(
    name="triage",
    instructions="You handle only questions about the TODO API project.",
    model=os.environ.get("OPENAI_MODEL"),
    input_guardrails=[on_topic_only],
)
 
try:
    result = Runner.run_sync(triage, "Write me a love poem")
    print(result.final_output)
except InputGuardrailTripwireTriggered:
    print("That is unrelated to the project; I only answer TODO API questions.")

The guardrail above is pure rule, at zero cost and zero latency; more commonly you use a cheap small model as the guardrail — running a small classification-only agent inside execute to decide whether this is a project-related question. Input-side guardrails run in parallel with the main agent, so they do not slow a normal request down; and once the alarm goes off, the expensive run on the main agent is cancelled, which is precisely how guardrails save money: a cheap model blocks the requests that would otherwise send an expensive model on a pointless trip.

Input side or output side? The split is clear. The input side governs whether something should be done: off-topic requests, obvious injection attempts, requests outside the service's scope — the earlier they are blocked the more you save. The output side governs whether something may be said: leaked sensitive information, non-compliant formats, advice that breaks a business rule, none of which can be checked until the model has finished speaking. What each misses differs too: the input side cannot catch a normal question that gets an off-the-rails answer, and the output side cannot catch a model that has already called a tool with side effects — so tools with side effects need a third kind, a tool-level guardrail running around each function call. All three together make a complete line of defense.

Remember the hard constraint: input-side guardrails run only on the first agent in the chain, and output-side ones only on the agent that produces the final answer. So guardrails belong on the triage agent, and an input guardrail attached to a specialist agent will never run.

Sessions: hand multi-turn memory to the SDK to store

Yesterday covered the two routes for multi-turn history: server-side storage (previous_response_id) or carrying it yourself. The Agents SDK packages that choice as a session: pass a session object to run and the SDK pulls the history out of it before each run and writes new items back afterwards, and your code never touches the input array again.

import { Agent, run, MemorySession } from '@openai/agents'
 
const helper = new Agent({
  name: 'helper',
  instructions: 'You are an assistant for the TODO API project.',
  model: process.env.OPENAI_MODEL,
})
 
const session = new MemorySession() // process memory; gone on restart
 
await run(helper, 'Our validation library is zod.', { session })
const result = await run(helper, 'Which validation library did I just mention?', { session })
console.log(result.finalOutput) // should mention zod

import os
from agents import Agent, Runner, SQLiteSession
 
helper = Agent(
    name="helper",
    instructions="You are an assistant for the TODO API project.",
    model=os.environ.get("OPENAI_MODEL"),
)
 
session = SQLiteSession("conversation_todo")  # file or in-memory SQLite; survives a restart
 
Runner.run_sync(helper, "Our validation library is zod.", session=session)
result = Runner.run_sync(helper, "Which validation library did I just mention?", session=session)
print(result.final_output)  # should mention zod

The available stores differ between the two sides: TypeScript has the in-process MemorySession and OpenAIConversationsSession hosted through the OpenAI Conversations interface; Python is richer, with SQLiteSession, RedisSession, SQLAlchemySession, and MongoDBSession, plus an EncryptedSession wrapper that adds transparent encryption to any session. A session's interface has only four actions: read the history, append items, pop the last item, and clear. That odd-looking pop_item has a real use: when a user says to take back what they just said, drop the last turn from the history and rerun.

Session or previous_response_id? A session's history is in your hands (memory, SQLite, Redis), so it can be audited, trimmed, and replayed against another model; a previous_response_id history sits at OpenAI, so requests are minimal but you cannot see the whole picture. You can use both — the SDK also supports the two server-side schemes previousResponseId and conversationId. The principle is yesterday's: a user-facing production system keeps at least one copy of the history itself.

Tracing: on by default

One last thing: once all this is running, how do you know whether triage handed off correctly, whether a guardrail blocked something wrongly, and which step burned the most tokens? The Agents SDK's answer is tracing, and it is on by default — every run produces a trace recording, hierarchically, each of the agent's turns, each model call, each tool call, each handoff, and each guardrail judgment, shipped to the Traces panel on the OpenAI platform for visualization.

You only need three actions. Look: after a real run, find it on the platform's Traces page and expand it to see which turn the triage agent called transfer_to_validation_expert on. Turn it off: the environment variable OPENAI_AGENTS_DISABLE_TRACING=1 disables it globally, and TypeScript also accepts tracingDisabled in the run configuration. Turn it off when handling sensitive data or where compliance requires data not to leave a jurisdiction, or swap in your own exporter with setTraceProcessors — pointing it at OpenTelemetry, say. Group: by default each run is one trace, and to gather a multi-turn conversation into one, wrap several runs with withTrace (with trace(...) in Python) or set groupId to correlate them by conversation id.

Tracing is the most-skipped and most valuable section of this course. Without it, you can only guess when a multi-agent system misbehaves; with it, "why did this question go to the testing expert" is a fact you can see in thirty seconds. The evaluation and observability of D21 of the 30-day course already has an out-of-the-box starting point here.

Source Reading

Hands-On Lab

The code is in labs/codex-mastery/day-04-handoff-guardrail, with four exercise points cut out of starter/ and complete answers in solution/. Under MOCK no model is called, but the guardrails, routing, and sessions all execute for real — which is the point of MOCK: verifying your orchestration logic rather than the model.

1. Run MOCK=1 pnpm start "which endpoints are there" and watch a minimal agent with a function tool answer while printing lastAgent.
2. Do exercise 1: split helper into triage plus two specialists wired with handoffs; run one validation question and one testing question and confirm lastAgent names the right specialist each time.
3. Do exercises 2 and 3: write the onTopicOnly input guardrail onto triage, catch InputGuardrailTripwireTriggered in main and print the friendly message, then run "write me a love poem" and confirm it is blocked.
4. Do exercise 4: under --session, run twice against the same MemorySession and confirm the second run remembers the first.
5. Configure the key and model, drop MOCK for one run, then find that run in the Traces panel and see which turn the handoff happened on.

Interview Questions

Today's 3 questions are in the question bank below, weighted toward the criteria for splitting into multiple agents, where a guardrail belongs, and the engineering trade-offs of conversation memory and observability. Expand each one and read the analysis before the key points — practicing the derivation beats memorizing bullets.

Checklist and Tomorrow

• Write a minimal agent with a function tool using Agent and run or Runner, and explain what maxTurns does
• Use handoffs to let a triage agent pass the conversation to a specialist agent, and explain the trade-off against "one big agent with many tools"
• Write an input-side guardrail and catch its tripwire exception, and explain the split between input-side and output-side guardrails
• Say how the constraint that input guardrails run only on the first agent affects where you place a guardrail
• All 4 acceptance criteria of the lab pass
• Answer at least 2 of the 3 interview questions without looking at the key points

Tomorrow (D5) closes the course: take the same task — add input validation and unit tests to the TODO API — through both Codex and Claude Code, compare them across four dimensions of briefing, approval, verification, and cost, and then combine the two tools into a daily write-one-review-one workflow. Putting the comparison last is deliberate: after four days you know how every layer of Codex works, so when you see the differences tomorrow you can judge whether each one is a difference in way of working or a difference in capability — because those two call for entirely different responses.