docs: clarify LlmAgent composition for workflow agents

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

@@ -30,6 +30,30 @@
  *
  * <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 publish
+ * via {@code outputKey} and the follow-up reads via {@code {key}} placeholders in its instruction:
+ *
+ * <pre>{@code
+ * var refiner =
+ *     LlmAgent.builder()
+ *         .name("refiner")
+ *         .model("gemini-flash-latest")
+ *         .instruction("Refine: {draft?}")
+ *         .outputKey("draft")
+ *         .build();
+ * var publisher =
+ *     LlmAgent.builder()
+ *         .name("publisher")
+ *         .model("gemini-flash-latest")
+ *         .instruction("Publish: {draft}")
+ *         .build();
+ * var loop =
+ *     LoopAgent.builder().name("loop").subAgents(refiner).maxIterations(3).build();
+ * var root = SequentialAgent.builder().name("root").subAgents(loop, publisher).build();
+ * }</pre>
  */
 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,38 @@
  * <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
+ * publishes via {@code outputKey} and the aggregator reads via {@code {key}} placeholders in its
+ * instruction:
+ *
+ * <pre>{@code
+ * var contacts =
+ *     LlmAgent.builder()
+ *         .name("contacts")
+ *         .model("gemini-flash-latest")
+ *         .instruction("List contacts.")
+ *         .outputKey("contacts")
+ *         .build();
+ * var schedule =
+ *     LlmAgent.builder()
+ *         .name("schedule")
+ *         .model("gemini-flash-latest")
+ *         .instruction("List schedule.")
+ *         .outputKey("schedule")
+ *         .build();
+ * var writer =
+ *     LlmAgent.builder()
+ *         .name("writer")
+ *         .model("gemini-flash-latest")
+ *         .instruction("Write: contacts={contacts}, schedule={schedule}")
+ *         .build();
+ * var gather =
+ *     ParallelAgent.builder().name("gather").subAgents(contacts, schedule).build();
+ * var root = SequentialAgent.builder().name("root").subAgents(gather, writer).build();
+ * }</pre>
  */
 public class ParallelAgent extends BaseAgent {
 

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

@@ -22,7 +22,32 @@
 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. Upstream publishes via {@code outputKey} and
+ * downstream reads via {@code {key}} placeholders in its instruction:
+ *
+ * <pre>{@code
+ * var draft =
+ *     LlmAgent.builder()
+ *         .name("draft")
+ *         .model("gemini-flash-latest")
+ *         .instruction("Draft a summary.")
+ *         .outputKey("draft")
+ *         .build();
+ * var reviewer =
+ *     LlmAgent.builder()
+ *         .name("reviewer")
+ *         .model("gemini-flash-latest")
+ *         .instruction("Polish the draft: {draft}")
+ *         .build();
+ * var pipeline =
+ *     SequentialAgent.builder().name("pipeline").subAgents(draft, reviewer).build();
+ * }</pre>
+ */
 public class SequentialAgent extends BaseAgent {
 
   private static final Logger logger = LoggerFactory.getLogger(SequentialAgent.class);