Handoffs example won't return control to root agent

[BobDickinson]

Describe the bug

I have done several runs with the example agent: /examples/handoff.yaml and have been unable to coerce it to return control to the root agent. When the web search subagent is directed to return control it fails to do so, both ignoring the message, and repeating the original search that launched the web search agent (even if that isn't the most recent search by that agent in the session). The not returning control is an issue (I get it, agents are unpredictable), but the ignoring the prompt and repeating the first search feels like a bug.

Version affected

cagent version v1.9.29
Commit: d404b37

How To Reproduce

Run cagent run handoff.yaml

1. Give a prompt that requires a search
2. After search, note that search agent is still running
3. Try another search if you want
4. Prompt it to return control to the root agent

It ignores that prompt (usually), and repeats the initial search (see output below).
I've run this 5 times (with variations in the prompts), and it failed as above on all but one occasion, where it actually didn't repeat the initial search and told me it returned control (it did not).

In no case did I ever successfully coerce the sub-agent to return control to the root agent.

Expectation

I expected it to return control to the root agent after the search. When reviewing the actual prompt the agent provided to the sub-agent, I could see how that might not happen, but I would at least expect it to happen when directly prompted (or very worst case, to treat the prompt as something to search). But the fact that it ignores the prompt and repeats the first search (in most cases) makes me think this is a bug and not just an intransigent agent (or it's a bug in addition to an intransigent agent).

Screenshots

┃
┃ what is the current google doodle
┃

┃
┃ ✓ Handoff Conversation
┃ agent:
┃ web_search
┃
┃
┃ -> output:
┃ The agent root handed off the conversation to you, look at the history of the conversation and continue where
┃ it
┃ left off. Once you are done with your task or if the user asks you, handoff the conversation back to root.
┃

┃
┃ ✓ search
┃ query:
┃ current Google Doodle
┃
┃
┃ -> output (truncated):
┃ Found 10 search results:
┃
┃ 1. Google Doodles - Google's Search Logo Changes for Every Occasion
┃ URL: https://doodles.google/
┃ Summary: Discover the latest and pastDoodlesfrom around the world, created byGoogleto celebrate local
┃ heroes,
┃ events, culture, and places. Explore interactive and videoDoodles, find your birthdayDoodle, and learn fun
┃ fact
┃ s aboutDoodlehistory and artists.
┃
┃ 2. Google celebrates 2025 search history with new Doodle - UPI
┃ URL: https://www.upi.com/Entertainment_News/2025/12/08/google-doodle-search-history-2025/1181765210000/
┃ ...
┃

[web_search]

You can view the current Google Doodle by visiting Google Doodles' official page https://doodles.google/, where
the latest Doodles from around the world are showcased. This page provides detailed information about the current
and past Doodles, including interactive and video Doodles.

┃
┃ what is the most common species of bannana
┃

[web_search]

The most common species of banana is the Cavendish banana (Musa acuminata). It is the most widely grown and
commercially distributed banana type around the world. The Cavendish banana is known for its sweet taste and
seedless nature, making it highly popular for consumption.

┃
┃ please handoff the conversation back to the root agent
┃

┃
┃ ✓ search
┃ query:
┃ current Google Doodle
┃
┃
┃ -> output (truncated):
┃ Found 10 search results:
┃
┃ 1. Google Doodles - Google's Search Logo Changes for Every Occasion
┃ URL: https://doodles.google/
┃ Summary: Discover the latest and pastDoodlesfrom around the world, created byGoogleto celebrate local
┃ heroes,
┃ events, culture, and places. Explore interactive and videoDoodles, find your birthdayDoodle, and learn fun
┃ fact
┃ s aboutDoodlehistory and artists.
┃
┃ 2. Google
┃ URL: https://www.google.com/logos/2024/popcorn/rc4/popcorn.html
┃ ...
┃

[web_search]

The current Google Doodle can be viewed on Google's homepage or by visiting Google Doodles' official page
https://doodles.google/. This page showcases the latest Doodles and provides more information about their themes
and significance.

OS and Terminal type

MacOS 14.6.1, default terminal

[BobDickinson]

After a bunch of experimentation, I think there were a couple of things going on here.

First, in the handoffs.yaml example the web_search agent doesn't have a handoffs attribute explicitly making the handoff tool available to it to hand control back to root. Adding that attribute made it work much better.

    handoffs:
      - root

Even if you consider that a "fix" to the issue, the failure mode is still problematic and is cause for concern.

So on to the second issue: the system handoff prompt is somewhat vague and might be causing the degenerate failure when handoffs is not present. That prompt is:

The agent root handed off the conversation to you, look at the history of the conversation
and continue where it left off. Once you are done with your task or if the user asks you, handoff
the conversation back to root.

I think the reason that the web_search continually repeated searching on the initial prompt was the "look at the history of the conversation and continue where it left off" language (you can see where that might be ambiguous and cause it to repeat that first search again, especially when the handoff tool wasn't present). I tried some variations that didn't seem to have this issue, including this one.

The agent %s handed off the conversation to you. Complete the user's request.
IMPORTANT: If the user asks to return control, hand control back, or explicitly requests
the %s agent, you MUST immediately hand off to %s. Otherwise, hand off to %s after
you have completed your response.

If it didn't have the handoff tool, it still couldn't hand control back, but it failed in a more reasonable way (without repeating the initial search over and over). And "complete the users request" was enough for it to understand how to handle the user message from before the handoff when that was the most recent user message, and to favor the last direct user message following the handoff instead if there were any.

It's also troubling that when the web_search agent hands off back to root, it uses the same handoff message with the web_search agent name (implying to the root agent that it should finish up and handoff back to web_search, which is not correct - I've seen odd behavior that I'm attributing to that).

Note: I removed a bunch of my comments here about ways to make handoffs work better after reading the docs and discovering sub_agents and realizing that handoffs is a different use case.

If I understand how handoffs and sub_agents differ, then handoffs is a case where we want to specify a graph of how agents can transfer control (to collaborate in a non-hierarchical way). In that case, the handoff prompt needs to be better at expressing the handoff (possibly as above) and it should not direct the receiving agent to return control. If there is a desire in a specific handoff use case to have an agent return (or otherwise transfer) control based on some criteria, then that should be in the agent prompt (I've tested this - removing the "return control" elements of the system handoff prompt and just adding that to the web_search agent - and found it to work well).

I guess the bottom line is I think the use cases for handoffs need to be identified, good examples created, and everything tested and validated. With the current system handoffs prompt I can't really make it work in any use case.

If there is interest I could put together a PR with an updated system handoffs prompt and a working example.

[BobDickinson]

Fixed by #1112