refactor: Refine AgentProvider interface and auto-wire it directly into AdkWebServer

- Change to `listAgents` and `getAgent` two methods, so that later we can implement config-based agent easily with reload feature.
- Adds `@ThreadSafe` annotation to remind user to implement it in a thread-safe manner.

PiperOrigin-RevId: 793917077

Author: Jacksunwei

maven_plugin/examples/simple-agent/README.md

@@ -43,26 +43,39 @@ Example modifications:
 ### Add a New Agent
 ```java
 private BaseAgent createMathTutor() {
-    return LlmAgent.builder()
-        .name("math_tutor")
-        .description("A mathematics tutoring agent")
-        .model("gemini-2.0-flash")
-        .instruction("You are a patient math tutor. " +
-                    "Help students understand mathematical concepts step by step.")
-        .build();
+  return LlmAgent.builder()
+      .name("math_tutor")
+      .description("A mathematics tutoring agent")
+      .model("gemini-2.0-flash")
+      .instruction(
+          "You are a patient math tutor. "
+              + "Help students understand mathematical concepts step by step.")
+      .build();
 }
 ```
 
-Then add it to the `getAgents()` map:
+Then add it to the `listAgents()` method and `getAgent()` switch statement:
 ```java
 @Override
-public Map<String, BaseAgent> getAgents() {
-    return Map.of(
-        "chat_assistant", createChatAssistant(),
-        "search_agent", createSearchAgent(),
-        "code_helper", createCodeHelper(),
-        "math_tutor", createMathTutor()  // Add the new agent
-    );
+@Nonnull
+public ImmutableList<String> listAgents() {
+  return ImmutableList.of("chat_assistant", "search_agent", "code_helper", "math_tutor");
+}
+
+@Override
+public BaseAgent getAgent(String name) {
+  switch (name) {
+    case "chat_assistant":
+      return createChatAssistant();
+    case "search_agent":
+      return createSearchAgent();
+    case "code_helper":
+      return createCodeHelper();
+    case "math_tutor":
+      return createMathTutor();  // Add the new agent
+    default:
+      throw new NoSuchElementException("Agent not found: " + name);
+  }
 }
 ```
 

maven_plugin/examples/simple-agent/src/main/java/com/example/SimpleAgentProvider.java

@@ -20,20 +20,43 @@
 import com.google.adk.agents.LlmAgent;
 import com.google.adk.maven.AgentProvider;
 import com.google.adk.tools.GoogleSearchTool;
-import java.util.Map;
+import com.google.common.base.Suppliers;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableMap;
+import java.util.NoSuchElementException;
+import java.util.function.Supplier;
+import javax.annotation.Nonnull;
+import javax.annotation.concurrent.ThreadSafe;
 
 /** Example AgentProvider that creates simple agents for demonstration. */
+@ThreadSafe
 public class SimpleAgentProvider implements AgentProvider {
 
-  // Static instance for easy access
   public static final SimpleAgentProvider INSTANCE = new SimpleAgentProvider();
 
+  private final ImmutableMap<String, Supplier<BaseAgent>> agentSuppliers;
+
+  public SimpleAgentProvider() {
+    this.agentSuppliers =
+        ImmutableMap.of(
+            "chat_assistant", Suppliers.memoize(this::createChatAssistant),
+            "search_agent", Suppliers.memoize(this::createSearchAgent),
+            "code_helper", Suppliers.memoize(this::createCodeHelper));
+  }
+
+  @Override
+  @Nonnull
+  public ImmutableList<String> listAgents() {
+    return ImmutableList.copyOf(agentSuppliers.keySet());
+  }
+
   @Override
-  public Map<String, BaseAgent> getAgents() {
-    return Map.of(
-        "chat_assistant", createChatAssistant(),
-        "search_agent", createSearchAgent(),
-        "code_helper", createCodeHelper());
+  public BaseAgent getAgent(String name) {
+    Supplier<BaseAgent> supplier = agentSuppliers.get(name);
+    if (supplier == null) {
+      throw new NoSuchElementException("Agent not found: " + name);
+    }
+    return supplier.get();
   }
 
   private BaseAgent createChatAssistant() {

maven_plugin/src/main/java/com/google/adk/maven/AgentProvider.java

@@ -15,43 +15,65 @@
 package com.google.adk.maven;
 
 import com.google.adk.agents.BaseAgent;
-import java.util.Map;
+import com.google.common.collect.ImmutableList;
 import javax.annotation.Nonnull;
+import javax.annotation.concurrent.ThreadSafe;
 
 /**
  * Interface for providing agents to the ADK Web Server.
  *
- * <p>Users implement this interface to register their custom agents with the web server. The
- * implementation should return a map where keys are agent names (used as app names in the UI) and
- * values are the corresponding BaseAgent instances.
+ * <p>Users implement this interface to register their agents with ADK Web Server.
+ *
+ * <p><strong>Thread Safety:</strong> Implementation must be thread-safe as it will be used as
+ * Spring singleton beans and accessed concurrently by multiple HTTP requests.
  *
  * <p>Example usage:
  *
  * <pre>{@code
  * public class MyAgentProvider implements AgentProvider {
- *   public static final MyAgentProvider INSTANCE = new MyAgentProvider(); @Override
- *   public Map<String, BaseAgent> getAgents() {
- *     return Map.of("chat_bot", createChatBot(), "code_assistant", createCodeAssistant());
+ *   @Override
+ *   public ImmutableList<String> listAgents() {
+ *     return ImmutableList.of("chat_bot", "code_assistant");
+ *   }
+ *
+ *   @Override
+ *   public BaseAgent getAgent(String name) {
+ *     switch (name) {
+ *       case "chat_bot": return createChatBot();
+ *       case "code_assistant": return createCodeAssistant();
+ *       default: throw new java.util.NoSuchElementException("Agent not found: " + name);
+ *     }
  *   }
  * }
  * }</pre>
  *
  * <p>Then use with Maven plugin:
  *
  * <pre>{@code
- * mvn google-adk:web -Dagents=com.acme.MyAgentProvider.INSTANCE
+ * mvn google-adk:web -Dagents=com.acme.MyAgentProvider
  * }</pre>
  *
  * TODO: Add config-based agent registration in the future.
  */
+@ThreadSafe
 public interface AgentProvider {
 
   /**
-   * Returns a map of agent names to BaseAgent instances.
+   * Returns a list of available agent names.
    *
-   * @return Map where keys are agent names (app names) and values are BaseAgent instances. Must not
-   *     return null - return an empty map if no agents are available.
+   * @return ImmutableList of agent names. Must not return null - return an empty list if no agents
+   *     are available.
    */
   @Nonnull
-  Map<String, BaseAgent> getAgents();
+  ImmutableList<String> listAgents();
+
+  /**
+   * Returns the BaseAgent instance for the specified agent name.
+   *
+   * @param name the name of the agent to retrieve
+   * @return BaseAgent instance for the given name
+   * @throws java.util.NoSuchElementException if the agent doesn't exist
+   * @throws IllegalStateException if the agent exists but fails to load
+   */
+  BaseAgent getAgent(String name);
 }

maven_plugin/src/main/java/com/google/adk/maven/WebMojo.java

@@ -16,7 +16,6 @@
 
 package com.google.adk.maven;
 
-import com.google.adk.agents.BaseAgent;
 import com.google.adk.maven.web.AdkWebServer;
 import java.io.IOException;
 import java.lang.reflect.Field;
@@ -25,8 +24,6 @@
 import java.net.URLClassLoader;
 import java.util.ArrayList;
 import java.util.List;
-import java.util.Map;
-import java.util.concurrent.ConcurrentHashMap;
 import org.apache.maven.artifact.DependencyResolutionRequiredException;
 import org.apache.maven.plugin.AbstractMojo;
 import org.apache.maven.plugin.MojoExecutionException;
@@ -43,14 +40,14 @@
 /**
  * Maven plugin goal that starts the Google ADK Web Server with user-provided agents.
  *
- * <p>This Mojo provides a convenient way for developers to test and interact with their Google ADK
- * agents through a web-based user interface. The plugin dynamically loads user-defined agents and
- * makes them available through a browser interface.
+ * <p>This Mojo provides a convenient way for developers to test and interact with their agents
+ * through ADK Web UI. The plugin dynamically loads user-defined agents and makes them available
+ * through a browser interface.
  *
  * <h3>Basic Usage</h3>
  *
  * <pre>{@code
- * mvn google-adk:web -Dagents=com.example.MyAgentProvider.INSTANCE
+ * mvn google-adk:web -Dagents=com.example.MyAgentProvider
  * }</pre>
  *
  * <h3>Configuration Parameters</h3>
@@ -59,7 +56,8 @@
  *   <li><strong>agents</strong> (required) - Full class path to AgentProvider implementation
  *   <li><strong>port</strong> (optional, default: 8000) - Server port
  *   <li><strong>host</strong> (optional, default: localhost) - Server host address
- *   <li><strong>hotReloading</strong> (optional, default: true) - Enable hot reloading
+ *   <li><strong>hotReloading</strong> (optional, default: true) - Enable hot reloading for
+ *       config-based agents
  * </ul>
  *
  * <h3>AgentProvider Implementation</h3>
@@ -74,8 +72,8 @@
  *
  * <h3>Web Interface</h3>
  *
- * <p>Once started, the web interface is available at {@code http://host:port} where users can
- * interact with available agents.
+ * <p>Once started, ADK Web UI is available at {@code http://host:port} where users can interact
+ * with available agents.
  *
  * @author Google ADK Team
  * @since 0.2.1
@@ -103,7 +101,7 @@ public class WebMojo extends AbstractMojo {
    * <p>Example:
    *
    * <pre>{@code
-   * mvn google-adk:web -Dagents=com.example.MyAgentProvider.INSTANCE
+   * mvn google-adk:web -Dagents=com.example.MyAgentProvider
    * }</pre>
    */
   @Parameter(property = "agents")
@@ -168,37 +166,23 @@ public void execute() throws MojoExecutionException, MojoFailureException {
       getLog().info("Loading agent provider: " + agents);
       AgentProvider provider = loadAgentProvider();
 
-      getLog().info("Retrieving agents from provider...");
-      Map<String, BaseAgent> adkAgents = provider.getAgents();
-
-      if (adkAgents == null || adkAgents.isEmpty()) {
-        throw new MojoExecutionException(
-            "AgentProvider returned no agents. Please verify your provider implementation.");
-      }
-
-      getLog().info("Successfully loaded " + adkAgents.size() + " agents: " + adkAgents.keySet());
-
       // Set up system properties for Spring Boot
       setupSystemProperties();
 
-      // Create a registry that will be used by AdkWebServer
-      Map<String, BaseAgent> agentRegistry = new ConcurrentHashMap<>(adkAgents);
-
-      // Start the Spring Boot application with custom agent registry
+      // Start the Spring Boot application with custom agent provider
       SpringApplication app = new SpringApplication(AdkWebServer.class);
 
-      // Add the agent registry as a bean
+      // Add the agent provider as a bean
       app.addInitializers(
           ctx -> {
-            ctx.getBeanFactory().registerSingleton("userProvidedAgentRegistry", agentRegistry);
+            ctx.getBeanFactory().registerSingleton("agentProvider", provider);
           });
 
       getLog().info("Starting Spring Boot application...");
       applicationContext = app.run(new String[0]);
 
       getLog().info("🎉 ADK Web Server started successfully!");
       getLog().info("🌐 Web UI available at: http://" + host + ":" + port);
-      getLog().info("🛠️  Available agents: " + adkAgents.keySet());
       getLog().info("⏹️  Press Ctrl+C to stop the server...");
       getLog().info("");
 
@@ -361,7 +345,7 @@ private AgentProvider tryLoadFromConstructor() throws MojoExecutionException {
     }
   }
 
-  /** Cleans up all resources including application context, classloader, and executor service. */
+  /** Cleans up all resources including application context, classloader. */
   private void cleanupResources() {
     getLog().debug("Cleaning up resources...");