OpenAI Agents SDK · Chapter 8 of 24

Handoffs

By the end of this chapter you can build a triage agent that hands each message to the right desk, say what a handoff really is (a tool the SDK makes for you), find which desk answered and what each agent did, run code when a handoff happens with the reason the model gave, and say who owns the conversation after a handoff. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Several agents
  • 4 tasks
  • Python
  • In the all labs plan

The first 2 chapters of OpenAI Agents SDK are free. This one comes with the all labs plan.

Why you need this

Every message to Shikhar used to land on Bhanu's phone, and he passed each one on by hand: fees and refunds to Nidhi, timetables and doubt sessions to the academic office, rooms to himself. It works, until forty messages arrive in an hour.

The helpdesk agent so far is one agent with every tool. That does not grow well. Each new tool makes the instructions longer and the tool list bigger on every request, and a fees question still carries the hostel tools. Karthik wants Shikhar's own shape instead: a small triage agent at the front, and desks behind it, each with its own instructions and only its own tools. The triage agent reads the message and hands it over. That hand-over is a handoff.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    triage.py: triage to two desks

    Bhanu wants every message passed to the right desk without him. Make two desks for lab-chat, each with a handoff_description saying what it handles: a Fees desk (name "Fees desk", instructions You are Shikhar's fees desk. Use the tools.) with a fee_status(student_id) tool, and a Hostel desk (name "Hostel desk", instructions You are Shikhar's hostel desk. Use the tools.) with a find_hostel_beds(gender) tool. Each tool returns json.dumps of the shikhar function of the same name.

    Make a triage agent named "Triage" for lab-chat whose instructions start with the SDK's RECOMMENDED_PROMPT_PREFIX, then You are Shikhar's helpdesk. Hand each message to the right desk. on a new line, with handoffs to the two desks. Run it on each of these two messages, in this order:

    S2053 ki fees kitni baki hai?

    boys hostel me non-AC room khali hai?

    Print one line per message: the name of the agent that answered, a colon and a space, then the final output.

  2. Task 2

    which_desk.py: what each agent did

    Karthik wants to see who did what in one run. Make three desks as in task 1, each with a handoff_description: the Fees desk with fee_status, the Hostel desk with find_hostel_beds, and an Academic desk (name "Academic desk", instructions You are Shikhar's academic desk. Use the tools.) with a class_schedule(batch_id, day) tool returning json.dumps of shikhar.class_schedule. Make the triage agent of task 1 with handoffs to all three.

    Run it on the student's message: kal ki physics class kitne baje hai? JEE-28X

    Print one line per item of the run's new items, in order: the item's type, a colon and a space, then the name of the agent that made the item.

  3. Task 3

    handoff_log.py: a handoff that logs why

    Bhanu wants a log line every time a message goes to the hostel desk, with the reason. Make the Fees desk and the Hostel desk of task 1 and the triage agent of task 1, but give it the hostel desk through the SDK's handoff() function, with an input_type: a Pydantic model HandoffNote with one field, reason (a string), and an on_handoff function that receives it.

    on_handoff prints: Handoff to Hostel desk: and the reason. Run the triage agent on the parent's message: beti ke liye hostel me room chahiye

    and print, after it, the agent that answered, a colon and a space, then the final output.

  4. Task 4 · interview question

    Interview: who_owns.py, the conversation after a handoff

    Make the triage agent of task 1 with the Fees desk (with fee_status and refund_quote(student_id) tools, json.dumps of the shikhar functions) and the Hostel desk. Turn 1: run the triage agent on: S2052 ki fees kitni baki hai?

    Turn 2: the parent writes again: And how much refund if she leaves now? S2052

    Run turn 2 on the agent that answered turn 1, with the conversation so far (the first result as an input list) plus the new message as a user message. Print two lines: Turn 1: then the agent that answered, a colon and a space, and its final output; then the same for Turn 2.

    The interviewer will ask: after a handoff, who owns the conversation? What happens, and what does it cost, if turn 2 starts at the triage agent again?

What you will learn

  • Handoffs: handoffs=[...] on a triage agent, and handoff_description on each desk.
  • A handoff is a tool: transfer_to_<desk>, in the request the SDK sends.
  • Which desk answered: result.last_agent, and each item's agent.
  • handoff(): on_handoff and input_type, to log why.
  • RECOMMENDED_PROMPT_PREFIX, and who owns the conversation afterwards.

More in Several agents

Build "Handoffs" yourself

Shikhar Classes, a Kota coaching institute, answers parents and students on WhatsApp all day. You build its helpdesk assistant. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of OpenAI Agents SDK are free. This one comes with the all labs plan.