docs: clarify LlmAgent composition for workflow agents

Document on ParallelAgent, SequentialAgent, and LoopAgent that they do
not transfer control back to an LlmAgent orchestrator after they
complete, and that placing the workflow agent and any follow-up agent
as siblings inside a SequentialAgent (used as the root or transferred-to
agent) is the recommended pattern.

This matches the behavior of adk-python v1.x, which is
the line that Java ADK currently tracks. A more robust orchestration
will be available once Java reaches the Graph Workflows milestone aligned
with adk-python v2.0.

PiperOrigin-RevId: 922007532

Author: damianmomotgoogle

core/src/main/java/com/google/adk/agents/LoopAgent.java

@@ -30,6 +30,11 @@
  *
  * <p>The loop continues until a sub-agent escalates, or until the maximum number of iterations is
  * reached (if specified).
+ *
+ * <p><b>Composition with {@link LlmAgent}s:</b> a {@code LoopAgent} does not transfer control back
+ * to a parent {@link LlmAgent}. To react to loop results, place the {@code LoopAgent} and the
+ * follow-up {@link LlmAgent} as siblings inside a {@link SequentialAgent}. Loop sub-agents can
+ * publish via {@code outputKey}, and the follow-up reads via {@code {state_key}} placeholders.
  */
 public class LoopAgent extends BaseAgent {
   private static final Logger logger = LoggerFactory.getLogger(LoopAgent.class);

core/src/main/java/com/google/adk/agents/ParallelAgent.java

@@ -34,6 +34,12 @@
  * <p>This approach is beneficial for scenarios requiring multiple perspectives or attempts on a
  * single task, such as running different algorithms simultaneously or generating multiple responses
  * for review by a subsequent evaluation agent.
+ *
+ * <p><b>Composition with {@link LlmAgent}s:</b> a {@code ParallelAgent} does not transfer control
+ * back to a parent {@link LlmAgent}. To follow a fan-out with an aggregation step, wrap both in a
+ * {@link SequentialAgent} (used as the root or transferred-to agent). Each parallel sub-agent can
+ * publish its result via {@code outputKey}, and the aggregator reads them via {@code {state_key}}
+ * placeholders in its instruction.
  */
 public class ParallelAgent extends BaseAgent {
 

core/src/main/java/com/google/adk/agents/SequentialAgent.java

@@ -22,7 +22,15 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-/** An agent that runs its sub-agents sequentially. */
+/**
+ * An agent that runs its sub-agents sequentially.
+ *
+ * <p><b>Composition with {@link LlmAgent}s:</b> a {@code SequentialAgent} does not transfer control
+ * back to a parent {@link LlmAgent}. Use it as the root or transferred-to agent and place any
+ * follow-up {@link LlmAgent} as the next sibling. Sub-agents pass data via session state: an
+ * upstream {@link LlmAgent} publishes with {@code outputKey}, a downstream {@link LlmAgent} reads
+ * via {@code {state_key}} placeholders in its instruction.
+ */
 public class SequentialAgent extends BaseAgent {
 
   private static final Logger logger = LoggerFactory.getLogger(SequentialAgent.class);