This Maven plugin provides a convenient way to start the ADK Web Server with your custom agents for development and testing.
mvn google-adk:web -Dagents=com.example.MyAgentLoader.INSTANCEagents(required): Full class path to your AgentLoader implementation OR path to agent configuration directoryport(optional, default: 8000): Port for the web serverhost(optional, default: localhost): Host address to bind tohotReloading(optional, default: true): Whether to enable hot reloading
mvn google-adk:web \
-Dagents=com.example.MyAgentLoader.INSTANCE \
-Dhost=0.0.0.0 \
-Dport=9090 \
-DhotReloading=falseCreate a class that implements com.google.adk.web.AgentLoader:
package com.example;
import com.google.adk.agents.BaseAgent;
import com.google.adk.agents.LlmAgent;
import com.google.adk.web.AgentLoader;
import com.google.common.collect.ImmutableList;
import java.util.NoSuchElementException;
public class MyAgentLoader implements AgentLoader {
public static final MyAgentLoader INSTANCE = new MyAgentLoader();
@Override
public ImmutableList<String> listAgents() {
return ImmutableList.of("chat_bot", "code_assistant");
}
@Override
public BaseAgent loadAgent(String name) {
switch (name) {
case "chat_bot": return createChatBot();
case "code_assistant": return createCodeAssistant();
default: throw new NoSuchElementException("Agent not found: " + name);
}
}
private BaseAgent createChatBot() {
return LlmAgent.builder()
.name("chat_bot")
.description("A helpful chat bot")
.model("gemini-2.0-flash")
.instruction("You are a helpful assistant.")
.build();
}
private BaseAgent createCodeAssistant() {
return LlmAgent.builder()
.name("code_assistant")
.description("A code assistance agent")
.model("gemini-2.0-flash")
.instruction("You are a coding assistant. Help users with programming questions.")
.build();
}
}Add the plugin to your pom.xml:
<build>
<plugins>
<plugin>
<groupId>com.google.adk</groupId>
<artifactId>google-adk-maven-plugin</artifactId>
<version>0.3.0</version>
</plugin>
</plugins>
</build>mvn google-adk:web -Dagents=com.example.MyAgentLoader.INSTANCEpublic class SimpleAgentLoader implements AgentLoader {
// No static field needed, uses default constructor
@Override
public ImmutableList<String> listAgents() {
return ImmutableList.of("simple_agent");
}
@Override
public BaseAgent loadAgent(String name) {
if ("simple_agent".equals(name)) {
return createSimpleAgent();
}
throw new NoSuchElementException("Agent not found: " + name);
}
private BaseAgent createSimpleAgent() {
return LlmAgent.builder()
.name("simple_agent")
.description("A simple agent")
.model("gemini-2.0-flash")
.instruction("You are a helpful assistant.")
.build();
}
}Usage:
mvn google-adk:web -Dagents=com.example.SimpleAgentLoaderpublic class MultipleLoaders implements AgentLoader {
public static final MultipleLoaders DEFAULT = new MultipleLoaders();
public static final MultipleLoaders ADVANCED = new MultipleLoaders(true);
private final boolean advanced;
public MultipleLoaders() { this(false); }
public MultipleLoaders(boolean advanced) { this.advanced = advanced; }
@Override
public ImmutableList<String> listAgents() {
if (advanced) {
return ImmutableList.of("advanced_agent");
}
return ImmutableList.of("basic_agent");
}
@Override
public BaseAgent loadAgent(String name) {
if (advanced && "advanced_agent".equals(name)) {
return createAdvancedAgent();
} else if (!advanced && "basic_agent".equals(name)) {
return createBasicAgent();
}
throw new NoSuchElementException("Agent not found: " + name);
}
private BaseAgent createBasicAgent() {
return LlmAgent.builder()
.name("basic_agent")
.description("A basic agent")
.model("gemini-2.0-flash")
.instruction("You are a basic helpful assistant.")
.build();
}
private BaseAgent createAdvancedAgent() {
return LlmAgent.builder()
.name("advanced_agent")
.description("An advanced agent with more capabilities")
.model("gemini-2.0-flash")
.instruction("You are an advanced assistant with enhanced capabilities.")
.build();
}
}Usage:
mvn google-adk:web -Dagents=com.example.MultipleLoaders.ADVANCEDFor configuration-based agents using YAML files, you can provide a directory path instead of a class name. The plugin will automatically use ConfigAgentLoader to scan for agent directories.
Create a parent directory containing subdirectories, each representing an agent with a root_agent.yaml file:
my-agents/
├── chat-assistant/
│ └── root_agent.yaml
├── search-agent/
│ └── root_agent.yaml
└── code-helper/
├── root_agent.yaml
└── another_agent.yaml
mvn google-adk:web -Dagents=my-agentsOr with absolute path:
mvn google-adk:web -Dagents=/home/user/my-agentsWhen using config-based agents, hot reloading is enabled by default. The plugin will automatically detect changes to any YAML files within the agent directories and reload agents without restarting the server.
To disable hot reloading:
mvn google-adk:web -Dagents=my-agents -DhotReloading=falsename: "chat_assistant"
description: "A friendly chat assistant"
model: "gemini-2.0-flash"
instruction: |
You are a helpful and friendly assistant.
Answer questions clearly and concisely.
Be encouraging and positive in your responses.Once the server starts, open your browser to:
- Default: http://localhost:8000
- Custom port: http://localhost:{port}
- External access: http://0.0.0.0:{port} (if using -Dhost=0.0.0.0)
The web UI provides:
- Interactive chat interface with your agents
- Agent selection dropdown
- Real-time streaming responses
- Session management
- Debug information
Make sure your project has the necessary ADK dependencies:
<dependencies>
<dependency>
<groupId>com.google.adk</groupId>
<artifactId>google-adk</artifactId>
<version>0.3.0</version>
</dependency>
<!-- Dev module dependency for AgentLoader interface -->
<dependency>
<groupId>com.google.adk</groupId>
<artifactId>google-adk-dev</artifactId>
<version>0.3.0</version>
<scope>compile</scope>
</dependency>
</dependencies>Option 1: With plugin declaration (shorter commands)
Add the plugin to your pom.xml for convenience:
<build>
<plugins>
<plugin>
<groupId>com.google.adk</groupId>
<artifactId>google-adk-maven-plugin</artifactId>
<version>0.3.0</version>
</plugin>
</plugins>
</build>Then use the short command:
mvn google-adk:web -Dagents=com.example.MyAgentLoader.INSTANCEOption 2: Without plugin declaration (no pom.xml changes)
Use the full coordinates directly:
mvn com.google.adk:google-adk-maven-plugin:web -Dagents=com.example.MyAgentLoader.INSTANCEPress Ctrl+C in the terminal to stop the server.
Replace version numbers with the latest version available on Maven Central.