OpenAI Agents SDK · Chapter 9 of 24

Agents as tools

By the end of this chapter you can turn a desk agent into a tool that another agent calls, read the desk's own requests in the log between the manager's, let one message ask two desks, choose what a desk sends back with a custom output extractor, and say when to use a handoff and when an agent tool. 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

The handoffs of chapter 8 work well for one-topic messages. Then Bhanu forwards this one, from a father in Patna:

beta ghar wapas aa raha hai, fees refund kitna milega? S2061. Also, boys hostel me room khali hai?

Two questions, two desks. With a handoff, the triage agent must pick one desk, and that desk owns the conversation: it cannot answer the hostel half. Kavita wants one voice talking to the parent, the front desk, which asks the specialists and writes one reply. Karthik: "Then the desks are not where the conversation goes. They are tools the front desk calls."

What you build: 4 tasks

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

  1. Task 1

    desk_tool.py: a desk as a tool

    Kavita wants one voice for the parents: the front desk asks the specialists and writes the reply. Make the Fees desk for lab-chat (name "Fees desk", instructions You are Shikhar's fees desk. Use the tools.) with the tools fee_status(student_id) and refund_quote(student_id), each returning json.dumps of the shikhar function of the same name.

    Make a manager agent, "Helpdesk", for lab-chat with the instructions You are Shikhar's helpdesk. Ask the desks, then answer the parent. and one tool: the fees desk turned into a tool named ask_fees_desk, with a description saying it asks the fees desk about fees, instalments, late fees and refunds. Run the Helpdesk on: S2072 ki next installment kab hai?

    Print two lines: the agent that answered, a colon and a space, then the final output; then Requests: and the run's request count from its usage.

  2. Task 2

    two_desks.py: two desks for a two-part message

    Make the Fees desk of task 1 and a Hostel desk for lab-chat (name "Hostel desk", instructions You are Shikhar's hostel desk. Use the tools.) with a find_hostel_beds(gender) tool returning json.dumps of shikhar.find_hostel_beds. Give the Helpdesk of task 1 both desks as tools: ask_fees_desk and ask_hostel_desk (asking the hostel desk about hostel beds, rooms and rent).

    Run it on the parent's message: S2052 ki fees kitni baki hai? aur girls hostel me room khali hai?

    For each tool call the manager made (the tool call items of the run's new items), print Asked and the tool's name. Then print the final output on a last line.

  3. Task 3

    extractor.py: the desk's data, not its prose

    Nidhi wants the manager to answer from the numbers, not from the desk's sentence. Make the Fees desk and the Helpdesk of task 1, but give the desk's as_tool a custom_output_extractor: an async function that gets the desk's run result and returns the output of the last tool call item in its new items (the fee_status JSON), or the desk's final output as text when it called no tool.

    Run the Helpdesk on: S2053 ki fees kitni baki hai?

    Print two lines: Manager got: and the output of the manager's tool call output item, then Reply: and the final output.

  4. Task 4 · interview question

    Interview: handoff_or_tool.py, handoff or agent tool

    Make the Fees desk (fee_status and refund_quote) and the Hostel desk (find_hostel_beds), each with a handoff_description, then two front agents for lab-chat: chapter 8's "Triage" (RECOMMENDED_PROMPT_PREFIX, then You are Shikhar's helpdesk. Hand each message to the right desk.) with handoffs to both desks, and the Helpdesk of task 2 with both desks as tools.

    Run the triage agent, then the Helpdesk, on the same message: S2030 ki fees kitni baki hai?

    Print one line per run: Handoff: (then Agent tool: for the second), the agent that answered, answered in, the run's request count from its usage, and requests. Like: Handoff: Fees desk answered in 3 requests

    The interviewer will ask: which would you choose for Shikhar's parents, and why? What does each cost, and who talks to the parent?

What you will learn

  • agent.as_tool(tool_name=..., tool_description=...): a desk as a function tool with one parameter, input.
  • A run inside a run: the desk's own requests in the log, and what the usage counts.
  • Two desks for a two-part message, called in one step.
  • custom_output_extractor: what the desk sends back to the manager.
  • Handoff or agent tool, and why.

More in Several agents

Build "Agents as tools" 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.