Python: Specialist-to-Specialist Handoff Interrupted by User Input Fallback on stop

[droideronline]

Description

Following the updates in #2037 and recent discussions, I would like to raise a clarification issue regarding the control flow behavior in specialist-to-specialist handoff scenarios.

I understand that the current framework design intentionally routes control back to user input (handoff-user-input) when an agent returns finish_reason="stop" without invoking a handoff tool. This is appropriate for interactive user-driven conversations.

However, I want to confirm whether this behavior is intended to apply even when the system is configured for specialist-to-specialist handoffs, where no user involvement is expected.

---

Observed Behavior

In a multi-specialist autonomous workflow:

1. A specialist agent returns a response with finish_reason="stop".
2. Control is automatically shifted to handoff-user-input.
3. Since the application is fully autonomous, no user input is provided.
4. The coordinator repeatedly attempts to deliver messages, resulting in multiple “dropped target mismatch” entries in telemetry.
5. The system eventually ends in _UserInputGateway, awaiting user input that will never be supplied.

This behavior blocks progress in an otherwise autonomous specialist-to-specialist flow.

---

Clarification Requested

Although I understand this fallback-to-user-input is by design, I would like to ask:

Should user input be required when the handoff builder is configured for specialist-to-specialist communication?

In a setup where specialists are meant to pass control among themselves (via add_handoff()), the expectation is that user input should not be needed unless explicitly requested.

---

Expected Behavior

For specialist-to-specialist configurations, it would be more consistent if:

• A finish_reason="stop" did not force control back to the user.
• Control remained with the same specialist.

---

Why This Matters

Autonomous specialist-to-specialist handoff workflows are a common pattern, and requiring user input in these cases:

• Interrupts agent-to-agent execution
• Produces unnecessary coordinator loops
• Prevents the system from running without human supervision

[droideronline]

CC - @moonbox3 , @ekzhu

[droideronline]

To work around this behavior, I created a middleware that prevents control from falling back to user input when a specialist returns finish_reason="stop" without invoking a handoff tool. In that case, the middleware simply calls the agent again so the specialist-to-specialist flow can continue autonomously.

@agent_middleware
async def handoff_control_middleware(
    context: AgentRunContext,
    next: Callable[[AgentRunContext], Awaitable[None]],
) -> None:
    iteration_count = 0

    while True:
        # Safety check: prevent infinite loops
        iteration_count += 1
        if iteration_count > MAX_ITERATIONS:
            raise RuntimeError(
                f"Handoff control middleware exceeded maximum iterations ({MAX_ITERATIONS}). "
                "This may indicate an infinite loop or missing handoff tool invocation."
            )

        # Execute the next middleware or agent
        await next(context)

        # Get the result from context
        result = context.result

        # Convert streaming response to complete response if needed
        if isinstance(result, AsyncIterable):
            result = await AgentRunResponse.from_agent_response_generator(
                result,
                output_format_type=None,
            )
            context.result = result

        # Ensure we have a valid result
        if result is None:
            break

        # Get finish reason from raw_representation (ChatResponse)
        finish_reason = result.raw_representation.finish_reason # type: ignore

        if finish_reason == FinishReason.STOP:
            # Check if any message contains a handoff tool call
            has_handoff_tool = any(
                isinstance(content, FunctionCallContent)
                and _HANDOFF_TOOL_PATTERN.search(content.name)
                for message in result.messages
                for content in message.contents
            )

            if has_handoff_tool:
                # Handoff tool detected - break the loop and yield control
                break

            # No handoff tool - agent wants to continue
            continue

        # Any other finish reason (tool_calls, error, completion, etc.)
        break

[moonbox3]

Thanks for the follow-up, @droideronline. Glad to see you're unblocked.

To support a fully autonomous flow, we will need to make some updates. As I have mentioned before (and I know you understand and re-iterated here) that the HITL is by design.

[moonbox3]

@droideronline without configuring the middleware, could you share you you're (ideally) configuring your autonomous handoff?

[droideronline]

@droideronline without configuring the middleware, could you share you you're (ideally) configuring your autonomous handoff?

I'm currently using add_handoff() to route control between specialists. In my setup, a coder agent is expected to perform a long autonomous task (50+ LLM calls). Ideally, the agent should continue iterating on its own until a handoff tool is invoked or the task is complete.

However, during the process the specialist sometimes returns finish_reason="stop" even though the work is not done. When that happens, the coordinator immediately falls back to handoff-user-input, which halts progress because the workflow is fully autonomous and no user input is expected.

With the middleware workaround, I intercept that situation and route control back to the same agent instead of dropping into user input — and the specialist continues working correctly until it reaches an intentional handoff.

[moonbox3]

@droideronline, I've got a PR out to handle a new "autonomous" interaction mode. Please have a look at #2497. There's a sample, too, showing this new behavior. I am able to have the agents run for a long time now, working on their tasks.