feat: Agentic Planning for ADK

contrib/planners/pom.xml

@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2025 Google LLC
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>com.google.adk</groupId>
+        <artifactId>google-adk-parent</artifactId>
+        <version>1.0.1-SNAPSHOT</version><!-- {x-version-update:google-adk:current} -->
+        <relativePath>../../pom.xml</relativePath>
+    </parent>
+
+    <artifactId>google-adk-planners</artifactId>
+    <name>Agent Development Kit - Planners</name>
+    <description>Built-in planner implementations for the ADK PlannerAgent, including GOAP (Goal-Oriented Action Planning), P2P (Peer-to-Peer), and Supervisor planners.</description>
+
+    <dependencies>
+        <!-- Main dependencies -->
+        <dependency>
+            <groupId>com.google.adk</groupId>
+            <artifactId>google-adk</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>com.google.genai</groupId>
+            <artifactId>google-genai</artifactId>
+        </dependency>
+
+        <!-- Test dependencies -->
+        <dependency>
+            <groupId>com.google.adk</groupId>
+            <artifactId>google-adk</artifactId>
+            <version>${project.version}</version>
+            <type>test-jar</type>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.google.truth</groupId>
+            <artifactId>truth</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>

contrib/planners/src/main/java/com/google/adk/agents/Planner.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.adk.agents;
+
+import io.reactivex.rxjava3.core.Single;
+
+/**
+ * Strategy interface for planning which sub-agent(s) to execute next.
+ *
+ * <p>A {@code Planner} is used by {@link PlannerAgent} to dynamically determine execution order at
+ * runtime. The planning loop works as follows:
+ *
+ * <ol>
+ *   <li>{@link #init} is called once before the loop starts
+ *   <li>{@link #firstAction} returns the first action to execute
+ *   <li>The selected agent(s) execute, producing events and updating session state
+ *   <li>{@link #nextAction} is called with updated context to decide what to do next
+ *   <li>Steps 3-4 repeat until {@link PlannerAction.Done} or max iterations
+ * </ol>
+ *
+ * <p>Returns {@link Single}{@code <PlannerAction>} to support both synchronous planners (wrap in
+ * {@code Single.just()}) and asynchronous planners that call an LLM.
+ */
+public interface Planner {
+
+  /**
+   * Initialize the planner with context and available agents. Called once before the planning loop
+   * starts.
+   *
+   * <p>Default implementation is a no-op. Override to perform setup like building dependency
+   * graphs.
+   */
+  default void init(PlanningContext context) {}
+
+  /** Select the first action to execute. */
+  Single<PlannerAction> firstAction(PlanningContext context);
+
+  /** Select the next action based on updated state and events. */
+  Single<PlannerAction> nextAction(PlanningContext context);
+}

contrib/planners/src/main/java/com/google/adk/agents/PlannerAction.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.adk.agents;
+
+import com.google.common.collect.ImmutableList;
+
+/**
+ * Represents the next action a {@link Planner} wants the {@link PlannerAgent} to take.
+ *
+ * <p>This is a sealed interface with four variants:
+ *
+ * <ul>
+ *   <li>{@link RunAgents} — execute one or more sub-agents (multiple agents run in parallel)
+ *   <li>{@link Done} — planning is complete, no result to emit
+ *   <li>{@link DoneWithResult} — planning is complete with a final text result
+ *   <li>{@link NoOp} — skip this iteration (no-op), then ask the planner for the next action
+ * </ul>
+ */
+public sealed interface PlannerAction
+    permits PlannerAction.RunAgents,
+        PlannerAction.Done,
+        PlannerAction.DoneWithResult,
+        PlannerAction.NoOp {
+
+  /** Run the specified sub-agent(s). Multiple agents are run in parallel. */
+  record RunAgents(ImmutableList<BaseAgent> agents) implements PlannerAction {
+    public RunAgents(BaseAgent singleAgent) {
+      this(ImmutableList.of(singleAgent));
+    }
+  }
+
+  /** Plan is complete, no result to emit. */
+  record Done() implements PlannerAction {}
+
+  /** Plan is complete with a final text result. */
+  record DoneWithResult(String result) implements PlannerAction {}
+
+  /** Skip this iteration (no-op). */
+  record NoOp() implements PlannerAction {}
+}