docs: clarify LlmAgent composition for workflow agents

Document on ParallelAgent, SequentialAgent, and LoopAgent that they do
not transfer control back to parent LlmAgent orchestrator after they
complete, and that wrapping with a SequentialAgent is the recommended
pattern to chain a workflow agent's results into a follow-up step. This
matches the behavior of adk-python.

PiperOrigin-RevId: 922007532

Author: damianmomotgoogle

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

@@ -30,6 +30,12 @@
  *
  * <p>The loop continues until a sub-agent escalates, or until the maximum number of iterations is
  * reached (if specified).
+ *
+ * <p><b>Composition:</b> a {@code LoopAgent} does not transfer control back to a parent {@link
+ * LlmAgent}, so an LlmAgent orchestrator that transfers to a {@code LoopAgent} cannot react to the
+ * loop's results afterwards. To run a loop and then react to its result, place the {@code
+ * LoopAgent} and the follow-up agent as siblings inside a {@link SequentialAgent} (used as the root
+ * or transferred-to agent).
  */
 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,21 @@
  * <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:</b> a {@code ParallelAgent} does not transfer control back to a parent {@link
+ * LlmAgent}, so an LlmAgent orchestrator that transfers to a {@code ParallelAgent} cannot react to
+ * the parallel results afterwards. To follow a fan-out with an aggregation/follow-up step, place
+ * the {@code ParallelAgent} and the follow-up agent as siblings inside a {@link SequentialAgent}
+ * (used as the root or transferred-to agent):
+ *
+ * <pre>{@code
+ * SequentialAgent.builder()
+ *     .subAgents(ImmutableList.of(parallelDataAgent, aggregatorLlmAgent))
+ *     .build();
+ * }</pre>
+ *
+ * <p>The {@code SequentialAgent} runs the {@code ParallelAgent} first, then runs {@code
+ * aggregatorLlmAgent}, which can see the parallel sub-agents' events in the session.
  */
 public class ParallelAgent extends BaseAgent {
 

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

@@ -22,7 +22,14 @@
 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:</b> a {@code SequentialAgent} does not transfer control back to a parent
+ * {@link LlmAgent}, so an LlmAgent orchestrator that transfers to a {@code SequentialAgent} cannot
+ * react to its results afterwards. Use {@code SequentialAgent} itself as the root or transferred-to
+ * agent and place any follow-up LlmAgent as the next sibling sub-agent.
+ */
 public class SequentialAgent extends BaseAgent {
 
   private static final Logger logger = LoggerFactory.getLogger(SequentialAgent.class);