Agents handing off to agents

[MervinPraison]

a-practical-guide-to-building-agents.pdf

[MervinPraison]

@claude review this request, implement with minimal code change with backward compatibility

Thsi is the implementation in another tool, do it similar

Handoffs
Handoffs allow an agent to delegate tasks to another agent. This is particularly useful in scenarios where different agents specialize in distinct areas. For example, a customer support app might have agents that each specifically handle tasks like order status, refunds, FAQs, etc.

Handoffs are represented as tools to the LLM. So if there's a handoff to an agent named Refund Agent, the tool would be called transfer_to_refund_agent.

Creating a handoff
All agents have a handoffs param, which can either take an Agent directly, or a Handoff object that customizes the Handoff.

You can create a handoff using the handoff() function provided by the Agents SDK. This function allows you to specify the agent to hand off to, along with optional overrides and input filters.

Basic Usage
Here's how you can create a simple handoff:

from agents import Agent, handoff

billing_agent = Agent(name="Billing agent")
refund_agent = Agent(name="Refund agent")

triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)])
Customizing handoffs via the handoff() function
The handoff() function lets you customize things.

agent: This is the agent to which things will be handed off.
tool_name_override: By default, the Handoff.default_tool_name() function is used, which resolves to transfer_to_<agent_name>. You can override this.
tool_description_override: Override the default tool description from Handoff.default_tool_description()
on_handoff: A callback function executed when the handoff is invoked. This is useful for things like kicking off some data fetching as soon as you know a handoff is being invoked. This function receives the agent context, and can optionally also receive LLM generated input. The input data is controlled by the input_type param.
input_type: The type of input expected by the handoff (optional).
input_filter: This lets you filter the input received by the next agent. See below for more.

from agents import Agent, handoff, RunContextWrapper

def on_handoff(ctx: RunContextWrapper[None]):
print("Handoff called")

agent = Agent(name="My agent")

handoff_obj = handoff(
agent=agent,
on_handoff=on_handoff,
tool_name_override="custom_handoff_tool",
tool_description_override="Custom description",
)
Handoff inputs
In certain situations, you want the LLM to provide some data when it calls a handoff. For example, imagine a handoff to an "Escalation agent". You might want a reason to be provided, so you can log it.

from pydantic import BaseModel

from agents import Agent, handoff, RunContextWrapper

class EscalationData(BaseModel):
reason: str

async def on_handoff(ctx: RunContextWrapper[None], input_data: EscalationData):
print(f"Escalation agent called with reason: {input_data.reason}")

agent = Agent(name="Escalation agent")

handoff_obj = handoff(
agent=agent,
on_handoff=on_handoff,
input_type=EscalationData,
)
Input filters
When a handoff occurs, it's as though the new agent takes over the conversation, and gets to see the entire previous conversation history. If you want to change this, you can set an input_filter. An input filter is a function that receives the existing input via a HandoffInputData, and must return a new HandoffInputData.

There are some common patterns (for example removing all tool calls from the history), which are implemented for you in agents.extensions.handoff_filters

from agents import Agent, handoff
from agents.extensions import handoff_filters

agent = Agent(name="FAQ agent")

handoff_obj = handoff(
agent=agent,
input_filter=handoff_filters.remove_all_tools,
)
Recommended prompts
To make sure that LLMs understand handoffs properly, we recommend including information about handoffs in your agents. We have a suggested prefix in agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX, or you can call agents.extensions.handoff_prompt.prompt_with_handoff_instructions to automatically add recommended data to your prompts.

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

billing_agent = Agent(
name="Billing agent",
instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
.""",
)

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[MervinPraison]

@claude review this request, implement with minimal code change with backward compatibility

Thsi is the implementation in another tool, do it similar

Handoffs
Handoffs allow an agent to delegate tasks to another agent. This is particularly useful in scenarios where different agents specialize in distinct areas. For example, a customer support app might have agents that each specifically handle tasks like order status, refunds, FAQs, etc.

Handoffs are represented as tools to the LLM. So if there's a handoff to an agent named Refund Agent, the tool would be called transfer_to_refund_agent.

Creating a handoff
All agents have a handoffs param, which can either take an Agent directly, or a Handoff object that customizes the Handoff.

You can create a handoff using the handoff() function provided by the Agents SDK. This function allows you to specify the agent to hand off to, along with optional overrides and input filters.

Basic Usage
Here's how you can create a simple handoff:

from agents import Agent, handoff

billing_agent = Agent(name="Billing agent")
refund_agent = Agent(name="Refund agent")

triage_agent = Agent(name="Triage agent", handoffs=[billing_agent, handoff(refund_agent)])
Customizing handoffs via the handoff() function
The handoff() function lets you customize things.

agent: This is the agent to which things will be handed off.
tool_name_override: By default, the Handoff.default_tool_name() function is used, which resolves to transfer_to_<agent_name>. You can override this.
tool_description_override: Override the default tool description from Handoff.default_tool_description()
on_handoff: A callback function executed when the handoff is invoked. This is useful for things like kicking off some data fetching as soon as you know a handoff is being invoked. This function receives the agent context, and can optionally also receive LLM generated input. The input data is controlled by the input_type param.
input_type: The type of input expected by the handoff (optional).
input_filter: This lets you filter the input received by the next agent. See below for more.

from agents import Agent, handoff, RunContextWrapper

def on_handoff(ctx: RunContextWrapper[None]):
print("Handoff called")

agent = Agent(name="My agent")

handoff_obj = handoff(
agent=agent,
on_handoff=on_handoff,
tool_name_override="custom_handoff_tool",
tool_description_override="Custom description",
)
Handoff inputs
In certain situations, you want the LLM to provide some data when it calls a handoff. For example, imagine a handoff to an "Escalation agent". You might want a reason to be provided, so you can log it.

from pydantic import BaseModel

from agents import Agent, handoff, RunContextWrapper

class EscalationData(BaseModel):
reason: str

async def on_handoff(ctx: RunContextWrapper[None], input_data: EscalationData):
print(f"Escalation agent called with reason: {input_data.reason}")

agent = Agent(name="Escalation agent")

handoff_obj = handoff(
agent=agent,
on_handoff=on_handoff,
input_type=EscalationData,
)
Input filters
When a handoff occurs, it's as though the new agent takes over the conversation, and gets to see the entire previous conversation history. If you want to change this, you can set an input_filter. An input filter is a function that receives the existing input via a HandoffInputData, and must return a new HandoffInputData.

There are some common patterns (for example removing all tool calls from the history), which are implemented for you in agents.extensions.handoff_filters

from agents import Agent, handoff
from agents.extensions import handoff_filters

agent = Agent(name="FAQ agent")

handoff_obj = handoff(
agent=agent,
input_filter=handoff_filters.remove_all_tools,
)
Recommended prompts
To make sure that LLMs understand handoffs properly, we recommend including information about handoffs in your agents. We have a suggested prefix in agents.extensions.handoff_prompt.RECOMMENDED_PROMPT_PREFIX, or you can call agents.extensions.handoff_prompt.prompt_with_handoff_instructions to automatically add recommended data to your prompts.

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

billing_agent = Agent(
name="Billing agent",
instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
.""",
)

[claude]

Claude finished @MervinPraison's task —— View job • claude/issue-491-20250628_070020 • Create PR ➔

---

✅ Agent Handoffs Implementation Complete

I've successfully implemented agent-to-agent handoffs with minimal code changes and full backward compatibility.

Implementation Summary:

Core Components:

1. Handoff class (src/praisonai-agents/praisonaiagents/handoff.py)

   • Configures handoff behavior between agents
   • Converts handoffs to tools that agents can use
   • Supports customization options

2. handoff() helper function

   • Convenient way to create handoff configurations
   • Matches the API pattern from OpenAI Agents SDK

3. Agent class updates (src/praisonai-agents/praisonaiagents/agent/agent.py)

   • Added optional handoffs parameter to __init__
   • Automatically converts handoffs to tools during initialization
   • Maintains full backward compatibility

Features Implemented:

• ✅ Basic handoffs with direct agent references
• ✅ Custom tool names and descriptions
• ✅ Handoff callbacks (sync and async)
• ✅ Structured input types with Pydantic models
• ✅ Input filters for conversation history
• ✅ Common filter patterns (remove tools, limit messages, etc.)
• ✅ Recommended prompt helpers

Examples Created:

1. Basic handoff (examples/handoff_basic.py) - Simple triage system
2. Advanced handoff (examples/handoff_advanced.py) - Callbacks, filters, and structured input
3. Customer service (examples/handoff_customer_service.py) - Complete real-world workflow

Backward Compatibility:

• All existing agent functionality preserved
• handoffs parameter is optional (defaults to None/empty list)
• Existing tools continue to work alongside handoffs
• Comprehensive test suite confirms no breaking changes

Usage Example:

from praisonaiagents import Agent, handoff

billing_agent = Agent(name="Billing Agent")
refund_agent = Agent(name="Refund Agent")

triage_agent = Agent(
    name="Triage Agent",
    handoffs=[billing_agent, handoff(refund_agent)]
)

Files Changed:

• src/praisonai-agents/praisonaiagents/handoff.py (new)
• src/praisonai-agents/praisonaiagents/agent/agent.py (modified)
• src/praisonai-agents/praisonaiagents/__init__.py (modified)
• examples/handoff_*.py (3 new examples)
• tests/test_handoff_compatibility.py (new)
• docs/handoffs.md (new)

The implementation follows the OpenAI Agents SDK pattern while adapting to PraisonAI's architecture. All changes are minimal and non-breaking.

---

[MervinPraison]

@claude review again if this implementation is correct

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[MervinPraison]

@claude review again if this implementation is correct

[claude]

Claude finished @MervinPraison's task —— View job

---

Code Review: Agent Handoff Implementation

After thoroughly reviewing the current codebase, I found that the handoff implementation is not present in the current branch. Here's what I discovered:

Current State:

• Review handoff.py implementation - File does not exist
• Check agent.py modifications - No handoff parameter found
• Verify examples match OpenAI SDK pattern - No handoff examples exist
• Validate backward compatibility - No changes to validate
• Provide detailed feedback on correctness

Detailed Findings:

1. No handoff.py file: The src/praisonai-agents/praisonaiagents/handoff.py file mentioned in the previous comments does not exist in the current codebase.

2. Agent class has only delegation parameter:

   • The Agent class (src/praisonai-agents/praisonaiagents/agent/agent.py:352) has an allow_delegation parameter
   • This parameter is documented but not actively used in the codebase
   • No handoffs parameter exists in the Agent constructor

3. No handoff mechanism:

   • No handoff() helper function exists
   • No handoff-related imports in __init__.py
   • No examples demonstrating handoff functionality

4. Current delegation support is limited:

   • The closest functionality is the "hierarchical" process mode where a Manager agent assigns tasks
   • This is task assignment at the beginning, not dynamic handoffs during execution

Conclusion:

The handoff implementation described in the issue request has not been implemented in the current branch. The codebase only contains a placeholder allow_delegation parameter that has no effect on agent behavior.

To implement the requested handoff functionality similar to OpenAI Agents SDK, you would need to:

1. Create the Handoff class and handoff() helper function
2. Add handoffs parameter to the Agent class
3. Implement the logic to convert handoffs to tools
4. Add handoff execution during agent runtime
5. Create examples demonstrating the functionality

The previous comments mentioning a completed implementation appear to reference work that is not present in the current branch.

[MervinPraison]

@claude check this branch and review claude/issue-491-20250628_070020

[claude]

Claude finished @MervinPraison's task —— View job

---

Code Review: Agent Handoff Implementation

I attempted to review the agent handoff implementation on branch claude/issue-491-20250628_070020, but encountered access limitations.

Todo List:

• Examine the handoff implementation on branch claude/issue-491-20250628_070020
• Review handoff.py implementation
• Check agent.py modifications for handoffs parameter
• Verify examples match OpenAI SDK pattern
• Validate backward compatibility
• Provide detailed feedback on correctness

Findings:

1. Branch Access Issue: The branch claude/issue-491-20250628_070020 exists on the remote repository but I cannot fetch or examine its contents due to permission limitations in my environment.

2. Current Codebase Analysis: I thoroughly examined the current codebase and found:

   • No handoff.py file exists
   • No handoff() helper function is present
   • The Agent class only has an allow_delegation parameter (line 352 in agent.py) which is not actively used
   • No handoff examples in the examples directory
   • No handoff-related tests
   • No handoff imports in __init__.py

3. Implementation Status: Based on the current state of the repository, the handoff functionality described in the issue (similar to OpenAI Agents SDK) has not been implemented or merged into the main codebase.

Recommendation:

To properly review the implementation on branch claude/issue-491-20250628_070020, you could:

1. Manually check out that branch locally and verify the implementation
2. Create a pull request from that branch to make the changes visible for review
3. Or merge the implementation if it was completed but not yet merged

Without access to the actual implementation branch, I cannot verify if the handoff functionality was correctly implemented according to the OpenAI Agents SDK pattern described in the issue.