Better document agent control flow patterns for multi-agent

[wietsevenema]

Based on feedback in issues https://github.com/google/adk-python/issues/147 ("Multi-Agent Architecture - Goes into sub-agent and not back up to the root agent") and https://github.com/google/adk-python/issues/371 ("Subsequent queries not routed to root agent in agent team session"), developers are confused about multi-agent control flow.

For both issues, there's an expectation that control automatically returns to the root agent at the beginning of the next user query within the same session - I think that's the AgentTool behavior, instead of the default AutoFlow

https://github.com/google/adk-python/issues/147:

• Reports the agent system getting "stuck" in a sub-agent and not going "up again to the root," preventing the root from handling subsequent, different tasks. Expresses confusion about the purpose of sub_agents if control doesn't return.
• Explicitly states being "unsure how control can be passed back to the root agent," preferring automatic routing.

https://github.com/google/adk-python/issues/371:

• Clearly describes that after delegation to greeting_agent, the next query ("What is the weather...") goes directly to greeting_agent instead of the root weather_agent_team, causing errors if the active agent lacks the necessary tools for the new query.

We should make sure to document these patterns better with clear & focused examples - it's a bit scattered now and the multi agent page is very dense.

Related pages

• https://google.github.io/adk-docs/tutorials/agent-team
• https://google.github.io/adk-docs/agents/multi-agents
• https://google.github.io/adk-docs/tools/function-tools

[wietsevenema]

One thing I don't know is if AgentTool supports that agent take turns (I don't think so). So maybe its more about the agent descriptions that prevent transferring back?

EDIT: AgentTool is really like a tool invocation. So no shared conversation history. AgentA invokes AgentB, and AgentB only gets the input from AgentA as first message.

[wietsevenema]

Some more thoughts. I think we should:

• Update multi-agents to explicitly clarify that transfer_to_agent changes the active agent for the session until another transfer occurs (and show how that happens).
• Provide a clearer comparison between the control flow implications of AutoFlow (transfer) and AgentTool (call/return).
• Add a code example showing how to force a return to root agent for every user message.

[wietsevenema]

disallow_transfer_to_parent might be useful here per https://github.com/google/adk-python/issues/371#issuecomment-2829185662

[wuliang229]

@lavinigam-gcp could you evaluate and prioritize this? There has been many issues with user not understanding how multi-agent systems transfer control among agents. If the concern has already been addressed, feel free to close it.

[cividanieltorres]

Hello,

I wanted to go a step further these two issues you are referring to in this thread. In our case, we are facing limitations with both AgentTool and subagents when implementing an orchestrator pattern.

Right now, as it's stated, we use AgentTool for these subagents, because we need the orchestrator to not only transfer the control to a specific subagent but to also request operations (e.g. "perform this action"). What we are encountering is that, as stated in the issues mentioned, when the orchestrator calls this "tool agent" multiple times, it has no record of the previous requests. Each request is independent of the others, so the orchestrator can't say "then do this instead", because the subagent with this new request would have no clue of what was performed before. Every agent call is isolated from the others.

I have seen that in every AgentTool call an internal session_id is created. These "subagents" don't share the same session_id as the orchestrator. The session_id is only shared at tool level, not internally. That's why the subagents don't have this context of the previous interactions, because every time they are called, they are creating a new session_id within a new runner.

To give you an overview of our process, our goal is to let the orchestrator "orchestrate" the process. If it needs to call only one subagent, then should do so. If it first needs to call agent A and then agent B, then it should also be able to.

The problem with the "subagents" parameter is that they can't transfer back the control to the orchestrator once they are done, so if the user asks for something that should involve two subagents to perform actions, with "subagents" right now it's not possible to do it, because once a subagent is called, then it doesn't transfer back the control to the orchestrator so it can transfer to the other subagent. Am I right?

In summary

Every time an AgentTool is called, it has no record of the previous interactions. It's like an isolated call. However, it does transfer back the control to the orchestrator. On the other hand, "subagents" do keep record of the session messages, but when transfered, they don't transfer back the control to the orchestrator so it can continue deciding which other subagent to call (if any).

I believe this is not an isolated case and that many people are suffering from this limitation. Is there anything we can do as a workaround right now?

Thank you so much!