Delegation & Transfer Control Reference

adk-fluent -- How agents hand off work and control flow between each other
Sub-Agent vs Agent Tool
Two fundamentally different ways to connect agents
.sub_agent(agent) Transfer-based
Parent (inactive) transfer_to_agent Child (full control) sees full history
  • LLM sees a transfer_to_agent tool in its toolbox
  • Parent loses control when transfer fires
  • Child agent sees the full conversation history
  • Only one transfer per turn -- exclusive handoff
Use case: Routing to specialists -- customer service triage, domain-specific handoff
.agent_tool(agent) Tool-based
Parent (stays active) call tool response Child (as tool) sees structured input only
  • Child is wrapped as an AgentTool in the parent's toolbox
  • Parent stays in control throughout the interaction
  • Child sees only the structured input passed by the parent
  • Can call multiple agent tools per turn -- parallel sub-tasks
Use case: Orchestrating sub-tasks -- research + write + review in a single turn
Transfer Control Matrix
Four modes controlling where a sub-agent can transfer execution
(default) Full Transfer
Agent Parent Peer Peer Can go anywhere
disallow_parent: False disallow_peers: False
Agent can transfer to parent and any sibling agent. Default behavior.
.stay() Peers Only
Agent Parent Peer Peer Lateral handoffs only
disallow_parent: True disallow_peers: False
Agent can hand off to siblings but cannot return to parent. Good for sequential handoff chains.
.no_peers() Parent Only
Agent Parent Peer Peer Handle and return
disallow_parent: False disallow_peers: True
Agent can only return to parent. No lateral handoffs. Clean request-response pattern.
.isolate() Isolated
Agent Parent Peer Peer Complete task, auto-return
disallow_parent: True disallow_peers: True
Agent is fully isolated. Cannot transfer anywhere. Completes its task and control auto-returns to parent.
Decision Tree
How should I connect agents?
Does the parent need to stay in control? Yes .agent_tool() parent orchestrates No .sub_agent() child takes over Should the specialist return when done? Yes .isolate() complete and auto-return No Should it hand off to siblings? Yes .stay() lateral handoffs only No .no_peers() handle and return
Common Topologies
Battle-tested patterns for multi-agent systems
Coordinator + Specialists
Coordinator Billing .isolate() Support .isolate() Sales .isolate() auto-return
# Hub-and-spoke: isolated specialists coordinator = ( Agent("coord", "gemini-2.5-flash") .instruct("Route to the right team.") .sub_agent( Agent("billing").instruct("...").isolate() ) .sub_agent( Agent("support").instruct("...").isolate() ) .sub_agent( Agent("sales").instruct("...").isolate() ) .build() )
Sequential Handoff
Parent Draft .stay() Review .stay() Publish .isolate() auto-return one-way chain
# Sequential: .stay() chain, last .isolate() chain = ( Agent("parent", "gemini-2.5-flash") .instruct("Manage the pipeline.") .sub_agent( Agent("draft").instruct("...").stay() ) .sub_agent( Agent("review").instruct("...").stay() ) .sub_agent( Agent("publish").instruct("...").isolate() ) .build() )
Nested Coordinators
Root Research Web Papers Writing Draft Edit .isolate() .isolate() hierarchical delegation
# Nested: sub-coordinators with leaves root = ( Agent("root", "gemini-2.5-flash") .instruct("Coordinate research and writing.") .sub_agent( Agent("research").isolate() .sub_agent(Agent("web").isolate()) .sub_agent(Agent("papers").isolate()) ) .sub_agent( Agent("writing").isolate() .sub_agent(Agent("draft").isolate()) .sub_agent(Agent("edit").isolate()) ) .build() )
← Back to Transfer Control User Guide Home API Reference PyPI GitHub
adk-fluent · Delegation & Transfer Control Reference — adk-fluent documentation