Delegating Tasks Between Agents Using Handoffs

Introduction And Context

Welcome back! In the last lesson, you learned how to chain multiple OpenAI agents together, passing the output and conversation history from one agent to the next. This approach allowed you to break down complex tasks into smaller, manageable steps, with each agent playing a specific role. You saw how to use the to_input_list() method to transfer context and how to build collaborative workflows by running agents in sequence. In this unit, you will take the next step in coordinating agent workflows: delegating tasks dynamically using handoffs . Instead of always following a fixed sequence, you will learn how to set up agents that can route requests to the most appropriate specialist agent based on the user's needs. This lesson will show you how to configure the handoffs parameter and use prompting strategies to guide agent behavior, making your multi-agent systems more flexible and intelligent.

Understanding Handoffs

In the OpenAI Agents SDK, a handoff is a way for one agent to delegate a task to another agent. Think of it as a transfer of responsibility: when an agent receives a request that is better handled by a specialist, it can "hand off" the task to that specialist agent. This is especially useful in situations where different agents have different areas of expertise. For example, imagine a travel assistant system. You might have one agent that is great at recommending destinations and another that specializes in travel safety. With handoffs, you can create a triage agent that listens to the user's request and decides which specialist should handle it. This makes your system more modular, easier to maintain, and able to provide higher-quality responses by letting each agent focus on what it does best. Handoffs are not just about splitting up work — they also help create a seamless user experience. The user interacts with a single system, but behind the scenes, their request is routed to the right expert. This delegation happens automatically, making your AI workflows smarter and more adaptable.

Defining Specialist Agents

Before setting up delegation, start by defining your specialist agents. For example, you might have one agent focused on travel recommendations and another dedicated to travel safety advice: Pythonfrom agents import Agent, ModelSettings # Define the travel genie agent travel_genie = Agent( name="Travel Genie", instructions=( "You are Travel Genie, a friendly and knowledgeable travel assistant. " "Recommend exciting destinations and offer helpful travel tips." ), model="gpt-5.6-terra", model_settings=ModelSettings(reasoning={"effort": "none"}), ) # Define the travel safety expert agent safety_expert = Agent( name="Travel Safety Expert", instructions=( "You are a travel safety expert. " "Provide safety advice and important precautions for travelers." ), model="gpt-5.6-terra", model_settings=ModelSettings(reasoning={"effort": "none"}), )from agents import Agent, ModelSettings # Define the travel genie agent travel_genie = Agent( name="Travel Genie", instructions=( "You are Travel Genie, a friendly and knowledgeable travel assistant. " "Recommend exciting destinations and offer helpful travel tips." ), model="gpt-5.6-terra", model_settings=ModelSettings(reasoning={"effort": "none"}), ) # Define the travel safety expert agent safety_expert = Agent( name="Travel Safety Expert", instructions=( "You are a travel safety expert. " "Provide safety advice and important precautions for travelers." ), model="gpt-5.6-terra", model_settings=ModelSettings(reasoning={"effort": "none"}), ) Each specialist agent has clear instructions that focus on its area of expertise. This ensures that when a request is handed off, the agent can provide the most relevant and high-quality response.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Recommended Prompts For Handoffs

When working with handoffs, it’s important to provide clear and specific instructions to each agent. The OpenAI Agents SDK offers a recommended prompt prefix to help agents understand their role in a multi-agent system and handle handoffs correctly.

The recommended prompt prefix is available as RECOMMENDED_PROMPT_PREFIX in the SDK. This prefix provides essential system context for the agent. You can inspect its contents like this:

Python

from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX

# Print the recommended prompt prefix
print(RECOMMENDED_PROMPT_PREFIX)

from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX

# Print the recommended prompt prefix
print(RECOMMENDED_PROMPT_PREFIX)

At the time this course is being developed. The recommended prompt prefix look like this:

text

# System context
You are part of a multi-agent system called the Agents SDK, designed to make agent coordination and execution easy. 
Agents uses two primary abstraction: **Agents** and **Handoffs**. An agent encompasses instructions and tools and 
can hand off a conversation to another agent when appropriate. Handoffs are achieved by calling a handoff function, 
generally named `transfer_to_<agent_name>`. Transfers between agents are handled seamlessly in the background; do 
not mention or draw attention to these transfers in your conversation with the user.

# System context
You are part of a multi-agent system called the Agents SDK, designed to make agent coordination and execution easy. 
Agents uses two primary abstraction: **Agents** and **Handoffs**. An agent encompasses instructions and tools and 
can hand off a conversation to another agent when appropriate. Handoffs are achieved by calling a handoff function, 
generally named `transfer_to_<agent_name>`. Transfers between agents are handled seamlessly in the background; do 
not mention or draw attention to these transfers in your conversation with the user.

To use this prefix, you can prepend it to your agent’s specific instructions. For example, when defining a triage agent:

Python

from agents import Agent, ModelSettings
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX

# Define the triage agent with the recommended prompt prefix
triage = Agent(
    name="Travel Triage",
    instructions=(
        f"{RECOMMENDED_PROMPT_PREFIX}\n"
        "You are a travel triage agent. Given a request:\n"
        "- For destination or itinerary questions, transfer to Travel Genie\n"
        "- For safety or health concerns, transfer to the Travel Safety Expert"
    ),
    handoffs=[
        travel_genie,
        safety_expert
    ],
    model="gpt-5.6-terra",
    model_settings=ModelSettings(reasoning={"effort": "none"}),
)

from agents import Agent, ModelSettings
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX

# Define the triage agent with the recommended prompt prefix
triage = Agent(
    name="Travel Triage",
    instructions=(
        f"{RECOMMENDED_PROMPT_PREFIX}\n"
        "You are a travel triage agent. Given a request:\n"
        "- For destination or itinerary questions, transfer to Travel Genie\n"
        "- For safety or health concerns, transfer to the Travel Safety Expert"
    ),
    handoffs=[
        travel_genie,
        safety_expert
    ],
    model="gpt-5.6-terra",
    model_settings=ModelSettings(reasoning={"effort": "none"}),
)

This approach ensures the agent receives both the system context and its specific task instructions, which helps it delegate tasks better.

Using the Prompt With Handoff Instructions Helper Method

The SDK also provides a helper function, prompt_with_handoff_instructions, which automatically combines your agent’s instructions with the recommended handoff context:

Python

from agents import ModelSettings

from agents.extensions.handoff_prompt import prompt_with_handoff_instructions

# Write your agent's specific instructions
agent_instructions = (
    "You are a travel triage agent. Given a request:\n"
    "- For destination or itinerary questions, transfer to Travel Genie\n"
    "- For safety or health concerns, transfer to the Travel Safety Expert"
)

# Use the helper to combine your instructions with the recommended handoff context
full_instructions = prompt_with_handoff_instructions(agent_instructions)

# Define the triage agent with the combined instructions and handoff targets
triage = Agent(
    name="Travel Triage",
    instructions=full_instructions,
    handoffs=[
        travel_genie,
        safety_expert
    ],
    model="gpt-5.6-terra",
    model_settings=ModelSettings(reasoning={"effort": "none"}),
)

from agents import ModelSettings

from agents.extensions.handoff_prompt import prompt_with_handoff_instructions

# Write your agent's specific instructions
agent_instructions = (
    "You are a travel triage agent. Given a request:\n"
    "- For destination or itinerary questions, transfer to Travel Genie\n"
    "- For safety or health concerns, transfer to the Travel Safety Expert"
)

# Use the helper to combine your instructions with the recommended handoff context
full_instructions = prompt_with_handoff_instructions(agent_instructions)

# Define the triage agent with the combined instructions and handoff targets
triage = Agent(
    name="Travel Triage",
    instructions=full_instructions,
    handoffs=[
        travel_genie,
        safety_expert
    ],
    model="gpt-5.6-terra",
    model_settings=ModelSettings(reasoning={"effort": "none"}),
)

Using either approach ensures your agents are properly primed to handle handoffs, resulting in more reliable and context-aware delegation in your multi-agent workflows.

Running Requests Through The Triage Agent

Let’s walk through an example to see how this works in practice. You have three agents: a triage agent, a travel recommendation agent, and a travel safety expert. When a user submits a request, the triage agent analyzes it and decides which specialist agent should handle the response.

Python

import asyncio
from agents import Runner

# Example requests to demonstrate delegation
requests = [
    "Where should I go for a relaxing beach vacation?",
    "Is it safe to travel to Peru right now?"
]

async def main():
    # Run each request through the triage agent
    for req in requests:
        result = await Runner.run(
            starting_agent=triage,
            input=req
        )
        print("Request:", req)
        print("Delegated to:", result.last_agent.name)
        print("Response:\n" + result.final_output + "\n")

if __name__ == "__main__":
    asyncio.run(main())

import asyncio
from agents import Runner

# Example requests to demonstrate delegation
requests = [
    "Where should I go for a relaxing beach vacation?",
    "Is it safe to travel to Peru right now?"
]

async def main():
    # Run each request through the triage agent
    for req in requests:
        result = await Runner.run(
            starting_agent=triage,
            input=req
        )
        print("Request:", req)
        print("Delegated to:", result.last_agent.name)
        print("Response:\n" + result.final_output + "\n")

if __name__ == "__main__":
    asyncio.run(main())

When you run this code, the triage agent receives each user request and decides which specialist should handle it. For the first request, "Where should I go for a relaxing beach vacation?", the triage agent delegates to the Travel Genie. For the second request, "Is it safe to travel by airplane?", it delegates to the Travel Safety Expert.

The output might look like this:

text

Request: Where should I go for a relaxing beach vacation?
Delegated to: Travel Genie
Response:
For a relaxing beach vacation, here are a few top destinations, each with its own unique vibe...

Request: Is it safe to travel to the Amazon?
Delegated to: Travel Safety Expert
Response:
Traveling to the Amazon can be an incredible adventure, but it does come with unique risks...

Request: Where should I go for a relaxing beach vacation?
Delegated to: Travel Genie
Response:
For a relaxing beach vacation, here are a few top destinations, each with its own unique vibe...

Request: Is it safe to travel to the Amazon?
Delegated to: Travel Safety Expert
Response:
Traveling to the Amazon can be an incredible adventure, but it does come with unique risks...

Notice how the triage agent does not answer the questions itself. Instead, it routes each request to the appropriate specialist, and the user receives a helpful, context-aware response from the right expert.

Introduction And Context

Understanding Handoffs

Defining Specialist Agents

Join the 1M+ learners on CodeSignal

Configuring the Triage Agent with Handoffs

How Handoffs Are Represented Internally

Recommended Prompts For Handoffs

Using the Prompt With Handoff Instructions Helper Method

Running Requests Through The Triage Agent

Summary And Next Steps