Welcome back! In the previous lessons, you learned how to chain OpenAI agents together and delegate tasks using handoffs, allowing your multi-agent workflows to be both modular and intelligent. Today, you will take your agent coordination skills to the next level by learning how to customize handoffs. This means you will not only delegate tasks, but also control exactly how information is passed between agents, validate the data being transferred, and even run custom logic at the moment of handoff.

Why is this important? In real-world applications, you often need to ensure that the data passed between agents is correct and safe. You might also want to log certain events, trigger notifications, or preprocess information before the next agent takes over. By customizing handoffs, you make your agent workflows more robust, secure, and adaptable to complex scenarios.

By the end of this lesson, you will know how to:

• Enforce input validation and schemas when handing off tasks between agents,
• Use callbacks to run custom code during a handoff,
• Integrate these features into a real-world multi-agent workflow.

Let’s begin by briefly reminding ourselves how handoffs work and why we might want more control over them.

In the last lesson, you learned how to use the handoffs parameter to delegate tasks between agents. For example, you set up a triage agent that could route travel questions to a travel expert or safety concerns to a safety expert. The handoff process was automatic: the triage agent analyzed the request and passed it to the right specialist, along with the conversation history.

This approach works well for many cases, but sometimes you need more control. For example, what if you want to make sure the information passed to the safety expert always includes both a destination and a specific concern? Or what if you want to log every time a safety concern is escalated? This is where customizing handoffs becomes useful.

Let’s explore how you can achieve this using the handoff() function and its customization options.

The OpenAI Agents SDK provides a handoff() function that lets you fine-tune how handoffs work. Instead of just listing agents in the handoffs parameter, you can use handoff() to specify extra details and behaviors.

The main parameters you can customize are:

• agent: The agent to which you want to hand off the task.
• tool_name_override: Lets you set a custom name for the handoff action, making it clearer in logs or debugging.
• tool_description_override: Lets you provide a custom description for the handoff, which can help with documentation or agent prompting.
• input_type: Lets you specify a schema (using a Pydantic model) that the input must match before the handoff occurs.
• on_handoff: Lets you define a callback function that runs when the handoff is triggered. This is useful for logging, preprocessing, or any custom logic.

Let’s see how to use input validation and schema enforcement in practice.

To ensure that every safety-related handoff includes both a destination and a concern, you can define a Pydantic model to represent the expected input schema. This model will be used to validate the data before the handoff occurs.

With this schema in place, you can be confident that any handoff to the safety expert will include the necessary information.

Next, you may want to log or announce every time a safety concern is escalated. You can do this by defining a callback function that will be triggered during the handoff. This function receives the validated input and can perform any custom logic you need.

This callback prints a message with the details of the safety concern, but you could also extend it to log to a file, send a notification, or preprocess the input.

Now, you can use the handoff() function to create a customized handoff to the safety expert. This allows you to specify the agent, override the tool name and description, enforce the input schema, and attach your callback.

This setup ensures that only validated requests are handed off, and your custom logic runs every time the handoff occurs.

With your customized handoff ready, you can now define the triage agent. This agent will use the handoffs you’ve set up to delegate requests to the appropriate specialist.

This agent will now route requests based on their content, using your customized handoff for safety concerns.

Finally, you can test your workflow by running a few example requests through the triage agent. This will demonstrate how the handoff logic works in practice.

When you run this code, you will see the safety handoff in action for relevant requests, along with the custom announcement printed by your callback.

Notice how the first request triggers the safety handoff, prints the announcement, and delegates to the safety expert. The second request goes to the travel genie without any extra processing.

This example shows how you can enforce input validation, customize handoff behavior, and run custom logic — all in a single, coordinated workflow.

In this lesson, you learned how to customize handoffs between OpenAI agents by enforcing input validation with Pydantic schemas and running custom callbacks during the handoff process. These techniques help you build safer, more reliable, and more flexible multi-agent workflows. You saw how to use the handoff() function to specify custom tool names, descriptions, input types, and callbacks, and you walked through a complete example that brings these ideas together.

You are now ready to practice these skills in hands-on exercises. In the next set of activities, you will get to define your own schemas, callbacks, and customized handoffs to solve real-world coordination problems. Keep experimenting and building — each step brings you closer to mastering agent workflows in Python!