Python: Handoff causes unwanted confirmation messages in sub-agent context

[lbbniu]

Issue Description

When using the handoff mechanism in a multi-agent setup, the coordinator generates an unwanted confirmation message after calling the handoff tool. This confirmation message then gets included in the sub-agent's context, causing logical inconsistencies.

Current Behavior

After coordinator calls handoff tool:

1. Framework automatically inserts tool_result
2. Coordinator sends tool_result back to LLM
3. LLM generates confirmation message like "已为您分配数学学习方法的讲解任务，将由数学科目专家为您提供详细指导。" (Task assigned, math expert will help you)
4. This confirmation message is included in the sub-agent's context

Actual sub-agent request context:

{
  "messages": [
    {
      "role": "system",
      "content": [{"type": "text", "text": "# Role\nYou are a math teacher..."}]
    },
    {
      "role": "user",
      "content": [{"type": "text", "text": "给我讲解数学的学习方法"}]
    },
    {
      "role": "assistant",
      "content": [{"type": "text", "text": "已为您分配数学学习方法的讲解任务，将由数学科目专家为您提供详细指导。"}]
    }
  ]
}

Problems

1. Role confusion: The confirmation message is from the coordinator saying "math expert will help", but it appears in the math expert's own context
2. Unnecessary context pollution: Sub-agent doesn't need to see coordinator's routing logic
3. Poor UX: May cause duplicate confirmations or confused responses
4. Cost: Extra unnecessary LLM call after every handoff
5. Wrong message source: Sub-agent should receive messages from handoff function call parameters, not from conversation history

Expected Behavior

The sub-agent should receive clean context from handoff function call parameters:

When coordinator calls handoff:

{
  "role": "assistant",
  "content": [{
    "type": "function_call",
    "name": "handoff_to_math_teacher",
    "arguments": {
      "query": "给我讲解数学的学习方法",
      "context": "User needs systematic learning method guidance"
    }
  }]
}

Sub-agent should receive:

{
  "messages": [
    {
      "role": "system",
      "content": [{"type": "text", "text": "# Role\nYou are a math teacher..."}]
    },
    {
      "role": "user",
      "content": [{"type": "text", "text": "给我讲解数学的学习方法"}]
    }
  ]
}

Key principle: The message passed to sub-agent should come from the handoff function call's parameters (e.g., query or message argument), not extracted from conversation history.

Proposed Solutions

Option 1: Framework-level fix (Recommended)

• After handoff tool call, don't send tool_result back to coordinator's LLM
• Extract message from function call parameters (not conversation history)
• Directly transfer to sub-agent with clean context constructed from parameters

Option 2: Middleware support

• Provide built-in middleware to intercept post-handoff LLM requests
• Allow users to short-circuit the confirmation message generation

Option 3: Configuration flag

coordinator = chat_client.create_agent(
    handoff_skip_confirmation=True  # Skip LLM call after handoff
)

Root Cause Analysis

The issue stems from two design decisions:

1. Sending tool_result back to coordinator's LLM - This triggers an unnecessary generation of confirmation message
2. Message extraction logic - If sub-agent context is built from conversation history instead of function call parameters, it will include unwanted coordinator messages

Both issues need to be addressed for a complete fix.

Workaround

We've implemented a custom middleware HandoffShortCircuitMiddleware to intercept and block the post-handoff LLM request. However, this feels like something the framework should handle natively.

Environment

• Framework: agent-framework
• Using handoff mechanism with coordinator pattern

Additional Context

This issue becomes more significant in production scenarios with:

• High handoff frequency
• Cost-sensitive applications
• Multi-turn conversations where context cleanliness is important

Would appreciate guidance on the recommended approach to handle this scenario.

[moonbox3]

This does look like a deeper bug in the function calling code that when the middleware' context.terminate = True, we should be able to kick out of the loop so we don't make another hop to the LLM.