Delegating Tasks Between Agents Using Handoffs

Introduction & Context

Welcome back! In the last lesson, you learned how to chain multiple OpenAI agents together in JavaScript, 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. In this unit, you’ll take the next step in coordinating agent workflows: delegating tasks dynamically using handoffs. Instead of always following a fixed sequence, you’ll 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 for JavaScript, 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: JavaScript import { Agent } from '@openai/agents'; // Define the travel genie agent const travelGenie = new 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', modelSettings: { reasoning: { effort: 'none' } }}); // Define the travel safety expert agent const safetyExpert = new 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', 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:

JavaScript

import { RECOMMENDED_PROMPT_PREFIX } from '@openai/agents-core/extensions';

console.log(RECOMMENDED_PROMPT_PREFIX);

import { RECOMMENDED_PROMPT_PREFIX } from '@openai/agents-core/extensions';

console.log(RECOMMENDED_PROMPT_PREFIX);

At the time this course is being developed, the recommended prompt prefix looks 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:

JavaScript

import { Agent } from '@openai/agents';
import { RECOMMENDED_PROMPT_PREFIX } from '@openai/agents-core/extensions';

const triage = new Agent({
  name: 'Travel Triage',
  instructions:
    RECOMMENDED_PROMPT_PREFIX +
    '\nYou 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: [
    travelGenie,
    safetyExpert
  ],
  model: 'gpt-5.6-terra',
  modelSettings: { reasoning: { effort: 'none' } }
});

import { Agent } from '@openai/agents';
import { RECOMMENDED_PROMPT_PREFIX } from '@openai/agents-core/extensions';

const triage = new Agent({
  name: 'Travel Triage',
  instructions:
    RECOMMENDED_PROMPT_PREFIX +
    '\nYou 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: [
    travelGenie,
    safetyExpert
  ],
  model: 'gpt-5.6-terra',
  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.

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.

JavaScript

import { run } from '@openai/agents';

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

for (const req of requests) {
  const result = await run(triage, req);
  console.log('Request:', req);
  console.log('Handled by:', result.lastAgent.name);
  console.log('Response:\n' + result.finalOutput + '\n');
}

import { run } from '@openai/agents';

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

for (const req of requests) {
  const result = await run(triage, req);
  console.log('Request:', req);
  console.log('Handled by:', result.lastAgent.name);
  console.log('Response:\n' + result.finalOutput + '\n');
}

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 to Peru right now?", it delegates to the Travel Safety Expert.

The output might look like this:

text

Request: Where should I go for a relaxing beach vacation?
Handled by: 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 Peru right now?
Handled by: Travel Safety Expert
Response:
Traveling to Peru can be an incredible adventure, but it does come with unique risks...

Request: Where should I go for a relaxing beach vacation?
Handled by: 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 Peru right now?
Handled by: Travel Safety Expert
Response:
Traveling to Peru 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 & Context

Understanding Handoffs

Defining Specialist Agents

Join the 1M+ learners on CodeSignal

Configuring the Triage Agent with Handoffs

How Handoffs Work

Recommended Prompts For Handoffs

Running Requests Through The Triage Agent

Summary & Next Steps