Python: Handoff Builder (specialist-to-specialist) — Agent loses control on finish_reason="stop" leading to dropped target mismatch messages

Description

When using the Handoff Builder for specialist-to-specialist handoffs, I observed an unexpected control flow behavior when an agent returns a finish_reason: "stop".
Ideally, even when an agent (let’s call it agent_a) finishes with "stop", the control should remain with the same agent (agent_a) unless an explicit handoff is performed.

However, based on telemetry traces, this does not appear to be the case. The control is incorrectly shifting, resulting in multiple “dropped target mismatch” messages in the pipeline.

Observed Behavior

From the telemetry logs:

agent_a returns with finish_reason: "stop".
Despite the "stop" reason (and no explicit handoff), the Handoff Coordinator sends 4 messages to agent_a, all of which are marked as “dropped target mismatch”.
The Handoff Coordinator then sends a message to handoff-user-input, which again results in a dropped target mismatch when checked against the edge group.
The control effectively leaves agent_a, even though it should have remained with it.

This suggests that the coordinator is rerouting messages prematurely or that the "stop" state is being treated as a terminal state rather than a “pause-and-wait” for the same agent.

Expected Behavior

When an agent returns finish_reason: "stop", control should remain with the same agent (agent_a) unless:
- An explicit handoff occurs, or
- The conversation/session ends intentionally.
This behavior is consistent with AutoGen, where even if an agent returns "stop", it continues to own the turn unless explicitly delegated.

Steps to Reproduce

Create a handoff builder with specialist-to-specialist handoff configuration.
Run a conversation where agent_a reaches a "stop" state.
Observe telemetry events:
- handoff-coordinator → agent_a → dropped target mismatch
- handoff-coordinator → handoff-user-input → dropped target mismatch
Verify that control incorrectly transfers away from agent_a.

Telemetry Evidence

Four "dropped target mismatch" messages observed from handoff-coordinator → agent_a.
One additional "dropped target mismatch" message from handoff-coordinator → handoff-user-input.
No explicit handoff request logged between these events.

Questions / Clarifications

Is this behavior (control leaving after "stop") intentional in MAF’s handoff coordinator logic?
If yes, what’s the reasoning behind treating "stop" as terminal for specialist agents?
If not, could this be an oversight in how the handoff coordinator interprets the agent’s stop event?

Eric Zhu (@ekzhu)

CC - Eric Zhu (@ekzhu) Evan Mattson (@moonbox3)

I tried setting up tool choice as required but that still did not help

I think I’ve identified the root cause of this behavior.

In the BaseChatClient implementation of:

async def get_response(
    self,
    messages: str | ChatMessage | list[str] | list[ChatMessage],
    *,
    frequency_penalty: float | None = None,
    logit_bias: dict[str | int, float] | None = None,
    max_tokens: int | None = None,
    metadata: dict[str, Any] | None = None,
    model_id: str | None = None,
    presence_penalty: float | None = None,
    response_format: type[BaseModel] | None = None,
    seed: int | None = None,
    stop: str | Sequence[str] | None = None,
    store: bool | None = None,
    temperature: float | None = None,
    tool_choice: ToolMode | Literal["auto", "required", "none"] | dict[str, Any] | None = "auto",
    tools: ToolProtocol
    | Callable[..., Any]
    | MutableMapping[str, Any]
    | Sequence[ToolProtocol | Callable[..., Any] | MutableMapping[str, Any]]
    | None = None,
    top_p: float | None = None,
    user: str | None = None,
    additional_properties: dict[str, Any] | None = None,
    **kwargs: Any,
) -> ChatResponse:

the tool_choice parameter defaults to "auto".
This value takes precedence during the _merge_chat_options() call — effectively overriding any tool choice defined at the chat agent level during initialization.

Because of that, even if a higher-level agent (e.g. in a workflow or builder) is explicitly configured with a tool_choice="required", it gets replaced with "auto" once the get_response method runs.

Proposed Change

We should consider changing the default value of tool_choice here from "auto" → None, so that the value provided at the agent or chat options level can persist.

That would make the function’s behavior more predictable and respect upstream configuration.

Additional Thoughts

While I think this change would make sense globally, there’s a nuance worth discussing:

In most workflow or autonomous agent cases, having tool_choice="auto" as the default is reasonable — it allows the model to decide when to call tools naturally.
However, in handoff builder scenarios (especially specialist-to-specialist or coordinator-driven flows), "auto" can lead to inconsistent control behavior — since the model might terminate early (finish_reason="stop") instead of invoking a required tool call.

So, we may need to think about handling this more explicitly in the handoff builder context — possibly by enforcing tool selection logic there, even if the base client keeps "auto" as default.

Dineshsuriya D (@droideronline)

Thanks for filing, Dineshsuriya D (@droideronline). I will look into this.

Thanks for filing, @droideronline. I will look into this.

I know this is intentional, but in the handoff builder, should the agent provide a response with a stop reason so the handoff tool can check and execute? Would it be better if we didn’t wait for the agent to finish and instead triggered the handoff tool as soon as it’s called from the service? I think we could still handle this through middleware.

Also, speaking of middleware, would it be nice if we could dynamically register middleware at runtime?

Currently, when tool_choice is set to "auto", the agent may produce a regular response mid-conversation because it can decide to stop on its own. This behavior disrupts the Handoff Builder’s expected flow.

On the other hand, when tool_choice is set to "required" — although this setting is currently not functioning correctly — the agent continuously issues tool calls and never produces a final agent response, causing the framework to miss registering an AgentResponse event.

Both of these cases need to be handled properly to ensure consistent control flow and predictable agent behavior during handoffs.

Evan Mattson (@moonbox3)

Hi Evan Mattson (@moonbox3) , I was testing the new enable_return_to_previous() method on HandoffBuilder, and here’s the scenario. I have 5 agents. In the middle of the conversation one of the agents (the coder agent) returns a stop_reason of stop. Control then shifts back to user input, and after that I see a bunch of handoff-coordinator messages trying to send things to the coder. Then at one point executor.process says it was delivered to the coder. But the coder responds with handoff-user-input, and I start seeing a bunch of edge group runner messages from handoff-coordinator to handoff-user-input. Eventually I end up with _UserInputGateway, as shown in the last screenshot.

Are we supposed to provide any input to the agent here? My application is autonomous, so I won’t be giving it any inputs. Please check the behavior and let me know your thoughts.

Evan Mattson (@moonbox3)

Hi @moonbox3 , I was testing the new enable_return_to_previous() method on HandoffBuilder, and here’s the scenario. I have 5 agents. In the middle of the conversation one of the agents (the coder agent) returns a stop_reason of stop. Control then shifts back to user input, and after that I see a bunch of handoff-coordinator messages trying to send things to the coder. Then at one point executor.process says it was delivered to the coder. But the coder responds with handoff-user-input, and I start seeing a bunch of edge group runner messages from handoff-coordinator to handoff-user-input. Eventually I end up with _UserInputGateway, as shown in the last screenshot.

Are we supposed to provide any input to the agent here? My application is autonomous, so I won’t be giving it any inputs. Please check the behavior and let me know your thoughts.

Evan Mattson (@moonbox3) - I wasn't able to debug it, but let me know if you need anything from me. I can open a new issue if necessary.

Dineshsuriya D (@droideronline)

Dineshsuriya D (@droideronline)

Are we supposed to provide any input to the agent here? My application is autonomous, so I won’t be giving it any inputs.

That's how this handoff is currently designed - if no handoff is triggered, it's expected to return control back to the user.

@droideronline

Are we supposed to provide any input to the agent here? My application is autonomous, so I won’t be giving it any inputs.

That's how this handoff is currently designed - if no handoff is triggered, it's expected to return control back to the user.

Makes sense, but in the case of specialist-to-specialist, is user input needed? Ideally, as per our design, it shouldn’t ask for user input when we use add_handoff(), if I’m not wrong.

Navigation Menu

Repository navigation

Python: Handoff Builder (specialist-to-specialist) — Agent loses control on `finish_reason="stop"` leading to dropped target mismatch messages #1972

Description

Observed Behavior

Expected Behavior

Steps to Reproduce

Telemetry Evidence

Questions / Clarifications

Proposed Change

Additional Thoughts

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Python: Handoff Builder (specialist-to-specialist) — Agent loses control on finish_reason="stop" leading to dropped target mismatch messages #1972

Description

Description

Observed Behavior

Expected Behavior

Steps to Reproduce

Telemetry Evidence

Questions / Clarifications

Activity

droideronline commented on Nov 6, 2025

droideronline commented on Nov 6, 2025

droideronline commented on Nov 6, 2025

Proposed Change

Additional Thoughts

moonbox3 commented on Nov 7, 2025

droideronline commented on Nov 8, 2025

droideronline commented on Nov 8, 2025

droideronline commented on Nov 13, 2025

droideronline commented on Nov 14, 2025

moonbox3 commented on Nov 14, 2025

droideronline commented on Nov 14, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Python: Handoff Builder (specialist-to-specialist) — Agent loses control on `finish_reason="stop"` leading to dropped target mismatch messages #1972