Merge pull request #23897 from dvdksn/cagent-handoffs

cagent: explain sub_agents vs handoffs

Author: dvdksn

content/manuals/ai/cagent/best-practices.md

@@ -102,6 +102,12 @@ agents:
 Each agent has clear responsibilities. The writer doesn't worry about line
 wrapping. The editor doesn't generate content. The reviewer just runs tools.
 
+This example uses `sub_agents` where root delegates discrete tasks and gets
+results back. The root agent maintains control and coordinates all work. For
+different coordination patterns where agents should transfer control to each
+other, see the `handoffs` mechanism in the [configuration
+reference](./reference/config.md#task-delegation-versus-conversation-handoff).
+
 **When to use teams:**
 
 - Multiple distinct steps in your workflow

content/manuals/ai/cagent/reference/config.md

@@ -61,11 +61,70 @@ metadata: # Optional - author, license, readme
 
 ### Task delegation versus conversation handoff
 
-Use `sub_agents` to break work into tasks. The root agent assigns work to a
-sub-agent and gets results back while staying in control.
+Agents support two different delegation mechanisms. Choose based on whether you
+need task results or conversation control.
 
-Use `handoffs` to transfer the entire conversation to a different agent. The new
-agent takes over completely.
+#### Sub_agents: Hierarchical task delegation
+
+Use `sub_agents` for hierarchical task delegation. The parent agent assigns a
+specific task to a child agent using the `transfer_task` tool. The child
+executes in its own context and returns results. The parent maintains control
+and can delegate to multiple agents in sequence.
+
+This works well for structured workflows where you need to combine results from
+specialists, or when tasks have clear boundaries. Each delegated task runs
+independently and reports back to the parent.
+
+**Example:**
+
+```yaml
+agents:
+  root:
+    sub_agents: [researcher, analyst]
+    instruction: |
+      Delegate research to researcher.
+      Delegate analysis to analyst.
+      Combine results and present findings.
+```
+
+Root calls: `transfer_task(agent="researcher", task="Find pricing data")`. The
+researcher completes the task and returns results to root.
+
+#### Handoffs: Conversation transfer
+
+Use `handoffs` to transfer conversation control to a different agent. When an
+agent uses the `handoff` tool, the new agent takes over completely. The
+original agent steps back until someone hands back to it.
+
+This works well when different agents should own different parts of an ongoing
+conversation, or when specialists need to collaborate as peers without a
+coordinator managing every step.
+
+**Example:**
+
+```yaml
+agents:
+  generalist:
+    handoffs: [database_expert, security_expert]
+    instruction: |
+      Help with general development questions.
+      If the conversation moves to database optimization,
+      hand off to database_expert.
+      If security concerns arise, hand off to security_expert.
+
+  database_expert:
+    handoffs: [generalist, security_expert]
+    instruction: Handle database design and optimization.
+
+  security_expert:
+    handoffs: [generalist, database_expert]
+    instruction: Review code for security vulnerabilities.
+```
+
+When the user asks about query performance, generalist executes:
+`handoff(agent="database_expert")`. The database expert now owns the
+conversation and can continue working with the user directly, or hand off to
+security_expert if the discussion shifts to SQL injection concerns.
 
 ### Commands