Gen AI

Sub-Agents and Handoffs

Instead of an agent doing the work itself, it acts like a dispatcher. When a user asks for a refund, the Main Agent transfers the conversation to a specialized 'Refund Agent', handing over the context seamlessly.

A Triage Agent greets the user, determines intent, and then executes a Handoff Tool to transfer the conversation state to a highly specialized Sub-Agent (like a Refund Agent).

Why Does This Exist?

In a Multi-Agent System, you have a team of highly specialized agents. But when a user logs into your website and types "I need help", which agent should answer them?

You need a way to route the user to the correct specialist, exactly like calling a corporate customer service hotline (Press 1 for Sales, Press 2 for Support).

Sub-Agents and Handoffs is the architectural pattern of using a primary "Triage Agent" that greets the user, figures out what they want, and then seamlessly transfers the conversation to a specialized "Sub-Agent".

Think of It Like This

The Hospital Triage Desk

Without Handoffs: A patient walks into the hospital with a broken arm. A heart surgeon is standing at the front door. The heart surgeon tries to fix the arm, realizes they don't have the right tools, and the patient suffers.

With Handoffs: A patient walks in and talks to the Triage Nurse (The Main Agent). The nurse asks, "What's wrong?" The patient says, "My arm is broken." The nurse says, "Please wait," and physically transfers the patient and their medical chart to the Orthopedics Wing (The Sub-Agent). The Orthopedic doctor fixes the arm perfectly.

How It Actually Works

A Handoff is quite literally implemented as an Agent Tool. Just like an agent has a tool called get_weather(city), a Triage Agent is given a suite of tools called transfer_to_sales() or transfer_to_refunds().

The Execution Flow

User: "I want to return my shoes."
Triage Agent: Analyzes intent. It sees the transfer_to_refunds() tool in its prompt.
Action: The LLM outputs Action: transfer_to_refunds().
The Backend Orchestrator: This is where the magic happens. The Python code intercepts this tool call. Instead of calling an API, the Python code halts the Triage Agent's execution loop.
Context Injection: The Python code takes the chat history, injects it into a brand new System Prompt for the Refund Agent, and starts a new execution loop.
Sub-Agent: The Refund Agent takes over the chat: "I can help you return those shoes. What is your order number?"

Show Me the Code

Frameworks like OpenAI's Swarm (an experimental multi-agent framework) are designed explicitly around this Handoff pattern.

1# Conceptual example of a Handoff mechanism2import openai3
4# 1. Define our Sub-Agent Logic5def run_refund_agent(chat_history):6    print("\n[System] Handoff successful. Refund Agent taking over.")7    prompt = "You are a Refund Specialist. Ask the user for their Order ID."8    9    # We pass the existing chat history so the user doesn't have to repeat themselves!10    messages = [{"role": "system", "content": prompt}] + chat_history11    12    response = openai.chat.completions.create(13        model="gpt-4o",14        messages=messages15    )16    return response.choices[0].message.content17
18# 2. Define the Main Triage Agent19def run_triage_agent(user_message):20    history = [{"role": "user", "content": user_message}]21    22    # The Triage agent has NO tools other than routing tools23    tools = [{24        "type": "function",25        "function": {26            "name": "transfer_to_refunds",27            "description": "Call this immediately if the user mentions returns, refunds, or broken items."28        }29    }]30    31    print("[System] Triage Agent analyzing intent...")32    response = openai.chat.completions.create(33        model="gpt-4o",34        messages=[{"role": "system", "content": "You are a receptionist. Route the user."}] + history,35        tools=tools36    )37    38    message = response.choices[0].message39    40    # 3. The Orchestrator handles the routing41    if message.tool_calls and message.tool_calls[0].function.name == "transfer_to_refunds":42        # Execute the handoff! Pass the context.43        return run_refund_agent(history)44    else:45        # Fallback if no routing needed46        return message.content47
48# --- Execution ---49user_input = "These shoes don't fit, I want my money back."50final_response = run_triage_agent(user_input)51
52print(f"\nResponse to User: {final_response}")53
54# -> [System] Triage Agent analyzing intent...55# -> [System] Handoff successful. Refund Agent taking over.56# -> 57# -> Response to User: I can certainly help you with returning those shoes. 58# -> Could you please provide your Order ID so I can pull up your account?

Watch Out For

Lost in Translation

The entire point of a handoff is to prevent the user from having to repeat themselves. If a user tells the Triage Agent their name and account number, and the Triage Agent transfers them to the Refund Agent without passing the chat history (or a summary of the facts), the Refund Agent will say "Hello, what is your name?" This creates a terrible, frustrating user experience. You must ensure your orchestration code seamlessly passes the State or the Chat History into the Sub-Agent's context window.

The Quick Version

Large systems require multiple specialized agents.
The user cannot talk to all of them at once. They must be routed.
A "Triage Agent" acts as a router. It uses NLP to determine intent.
Handoffs are implemented as Agent Tools (e.g., transfer_to_x()).
When the tool is called, the Python backend halts the main agent, transfers the conversation context, and spins up the specialized Sub-Agent to continue the chat.