Skip to content

Commit b02c559

Browse files
Jacksunweicopybara-github
Jacksunwei
authored and
copybara-github
committed
feat: Adds mvn google-adk:web ... cli via maven plugin to allow users debug agents with Web UI much easier.
Typical usage: ``` mvn google-adk:web -Dagents=com.example.SimpleAgentProvider ``` or ``` mvn google-adk:web -Dagents=com.example.SimpleAgentProvider.INSTANCE ``` Check out the included examples for more details of pom.xml PiperOrigin-RevId: 793871380
1 parent 5ffa984 commit b02c559

File tree

20 files changed

+7268
-0
lines changed

20 files changed

+7268
-0
lines changed

‎maven_plugin/README.md

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
# Google ADK Maven Plugin
2+
3+
This Maven plugin provides a convenient way to start the ADK Web Server with your custom agents for development and testing.
4+
5+
## Usage
6+
7+
### Basic Usage
8+
9+
```bash
10+
mvn google-adk:web -Dagents=com.example.MyAgentProvider.INSTANCE
11+
```
12+
13+
### Parameters
14+
15+
- **`agents`** (required): Full class path to your AgentProvider implementation
16+
- **`port`** (optional, default: 8000): Port for the web server
17+
- **`host`** (optional, default: localhost): Host address to bind to
18+
- **`hotReloading`** (optional, default: true): Whether to enable hot reloading
19+
20+
### Example with Custom Parameters
21+
22+
```bash
23+
mvn google-adk:web \
24+
-Dagents=com.example.MyAgentProvider.INSTANCE \
25+
-Dhost=0.0.0.0 \
26+
-Dport=9090 \
27+
-DhotReloading=false
28+
```
29+
30+
## Creating an AgentProvider
31+
32+
### 1. Implement the AgentProvider Interface
33+
34+
Create a class that implements `com.google.adk.maven.AgentProvider`:
35+
36+
```java
37+
package com.example;
38+
39+
import com.google.adk.agents.BaseAgent;
40+
import com.google.adk.agents.LlmAgent;
41+
import com.google.adk.maven.AgentProvider;
42+
import java.util.Map;
43+
44+
public class MyAgentProvider implements AgentProvider {
45+
46+
public static final MyAgentProvider INSTANCE = new MyAgentProvider();
47+
48+
@Override
49+
public Map<String, BaseAgent> getAgents() {
50+
return Map.of(
51+
"chat_bot", createChatBot(),
52+
"code_assistant", createCodeAssistant()
53+
);
54+
}
55+
56+
private BaseAgent createChatBot() {
57+
return LlmAgent.builder()
58+
.name("chat_bot")
59+
.description("A helpful chat bot")
60+
.model("gemini-2.0-flash")
61+
.instruction("You are a helpful assistant.")
62+
.build();
63+
}
64+
65+
private BaseAgent createCodeAssistant() {
66+
return LlmAgent.builder()
67+
.name("code_assistant")
68+
.description("A code assistance agent")
69+
.model("gemini-2.0-flash")
70+
.instruction("You are a coding assistant. Help users with programming questions.")
71+
.build();
72+
}
73+
}
74+
```
75+
76+
### 2. Add the Plugin to Your Project
77+
78+
Add the plugin to your `pom.xml`:
79+
80+
```xml
81+
<build>
82+
<plugins>
83+
<plugin>
84+
<groupId>com.google.adk</groupId>
85+
<artifactId>google-adk-maven-plugin</artifactId>
86+
<version>0.2.1-SNAPSHOT</version>
87+
</plugin>
88+
</plugins>
89+
</build>
90+
```
91+
92+
### 3. Run the Web Server
93+
94+
```bash
95+
mvn google-adk:web -Dagents=com.example.MyAgentProvider.INSTANCE
96+
```
97+
98+
## Alternative AgentProvider Patterns
99+
100+
### Using Default Constructor
101+
102+
```java
103+
public class SimpleAgentProvider implements AgentProvider {
104+
// No static field needed, uses default constructor
105+
@Override
106+
public Map<String, BaseAgent> getAgents() {
107+
return Map.of("simple_agent", createSimpleAgent());
108+
}
109+
110+
private BaseAgent createSimpleAgent() {
111+
return LlmAgent.builder()
112+
.name("simple_agent")
113+
.description("A simple agent")
114+
.model("gemini-2.0-flash")
115+
.instruction("You are a helpful assistant.")
116+
.build();
117+
}
118+
}
119+
```
120+
121+
Usage:
122+
```bash
123+
mvn google-adk:web -Dagents=com.example.SimpleAgentProvider
124+
```
125+
126+
### Using Other Static Fields
127+
128+
```java
129+
public class MultipleProviders implements AgentProvider {
130+
public static final MultipleProviders DEFAULT = new MultipleProviders();
131+
public static final MultipleProviders ADVANCED = new MultipleProviders(true);
132+
133+
private final boolean advanced;
134+
135+
public MultipleProviders() { this(false); }
136+
public MultipleProviders(boolean advanced) { this.advanced = advanced; }
137+
138+
@Override
139+
public Map<String, BaseAgent> getAgents() {
140+
if (advanced) {
141+
return Map.of("advanced_agent", createAdvancedAgent());
142+
}
143+
return Map.of("basic_agent", createBasicAgent());
144+
}
145+
146+
private BaseAgent createBasicAgent() {
147+
return LlmAgent.builder()
148+
.name("basic_agent")
149+
.description("A basic agent")
150+
.model("gemini-2.0-flash")
151+
.instruction("You are a basic helpful assistant.")
152+
.build();
153+
}
154+
155+
private BaseAgent createAdvancedAgent() {
156+
return LlmAgent.builder()
157+
.name("advanced_agent")
158+
.description("An advanced agent with more capabilities")
159+
.model("gemini-2.0-flash")
160+
.instruction("You are an advanced assistant with enhanced capabilities.")
161+
.build();
162+
}
163+
}
164+
```
165+
166+
Usage:
167+
```bash
168+
mvn google-adk:web -Dagents=com.example.MultipleProviders.ADVANCED
169+
```
170+
171+
## Web UI
172+
173+
Once the server starts, open your browser to:
174+
- Default: http://localhost:8000
175+
- Custom port: http://localhost:{port}
176+
- External access: http://0.0.0.0:{port} (if using -Dhost=0.0.0.0)
177+
178+
The web UI provides:
179+
- Interactive chat interface with your agents
180+
- Agent selection dropdown
181+
- Real-time streaming responses
182+
- Session management
183+
- Debug information
184+
185+
## Dependencies
186+
187+
Make sure your project has the necessary ADK dependencies:
188+
189+
```xml
190+
<dependencies>
191+
<dependency>
192+
<groupId>com.google.adk</groupId>
193+
<artifactId>google-adk</artifactId>
194+
<version>0.2.1-SNAPSHOT</version>
195+
</dependency>
196+
197+
<!-- Maven plugin dependency for AgentProvider interface -->
198+
<dependency>
199+
<groupId>com.google.adk</groupId>
200+
<artifactId>google-adk-maven-plugin</artifactId>
201+
<version>0.2.1-SNAPSHOT</version>
202+
<scope>compile</scope>
203+
</dependency>
204+
</dependencies>
205+
```
206+
207+
### Plugin Usage Options
208+
209+
**Option 1: With plugin declaration (shorter commands)**
210+
211+
Add the plugin to your `pom.xml` for convenience:
212+
213+
```xml
214+
<build>
215+
<plugins>
216+
<plugin>
217+
<groupId>com.google.adk</groupId>
218+
<artifactId>google-adk-maven-plugin</artifactId>
219+
<version>0.2.1-SNAPSHOT</version>
220+
</plugin>
221+
</plugins>
222+
</build>
223+
```
224+
225+
Then use the short command:
226+
```bash
227+
mvn google-adk:web -Dagents=com.example.MyAgentProvider.INSTANCE
228+
```
229+
230+
**Option 2: Without plugin declaration (no pom.xml changes)**
231+
232+
Use the full coordinates directly:
233+
```bash
234+
mvn com.google.adk:google-adk-maven-plugin:web -Dagents=com.example.MyAgentProvider.INSTANCE
235+
```
236+
237+
## Stopping the Server
238+
239+
Press `Ctrl+C` in the terminal to stop the server.

‎maven_plugin/examples/simple-agent/README.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Simple ADK Agent Example
2+
3+
This example demonstrates how to create and run custom ADK agents using the Maven plugin.
4+
5+
## What's Included
6+
7+
- **SimpleAgentProvider**: An implementation of `AgentProvider` that creates three example agents:
8+
- `chat_assistant`: A friendly general-purpose assistant
9+
- `search_agent`: An agent with Google Search capabilities
10+
- `code_helper`: A coding assistant
11+
12+
## How to Run
13+
14+
1. **Compile the project:**
15+
```bash
16+
mvn compile
17+
```
18+
19+
2. **Start the ADK Web Server:**
20+
```bash
21+
mvn google-adk:web -Dagents=com.example.SimpleAgentProvider.INSTANCE
22+
```
23+
24+
3. **Open your browser:**
25+
Navigate to http://localhost:8000
26+
27+
4. **Try the agents:**
28+
- Select an agent from the dropdown
29+
- Start a conversation
30+
- Test different agents to see their capabilities
31+
32+
## Customizing
33+
34+
You can modify `SimpleAgentProvider.java` to:
35+
- Add more agents
36+
- Change agent instructions
37+
- Add different tools
38+
- Use different models
39+
- Configure agent-specific settings
40+
41+
Example modifications:
42+
43+
### Add a New Agent
44+
```java
45+
private BaseAgent createMathTutor() {
46+
return LlmAgent.builder()
47+
.name("math_tutor")
48+
.description("A mathematics tutoring agent")
49+
.model("gemini-2.0-flash")
50+
.instruction("You are a patient math tutor. " +
51+
"Help students understand mathematical concepts step by step.")
52+
.build();
53+
}
54+
```
55+
56+
Then add it to the `getAgents()` map:
57+
```java
58+
@Override
59+
public Map<String, BaseAgent> getAgents() {
60+
return Map.of(
61+
"chat_assistant", createChatAssistant(),
62+
"search_agent", createSearchAgent(),
63+
"code_helper", createCodeHelper(),
64+
"math_tutor", createMathTutor() // Add the new agent
65+
);
66+
}
67+
```
68+
69+
### Configure Different Ports
70+
```bash
71+
mvn google-adk:web -Dagents=com.example.SimpleAgentProvider.INSTANCE -Dport=9090
72+
```
73+
74+
## Next Steps
75+
76+
- Explore the ADK documentation for more advanced features
77+
- Add custom tools to your agents
78+
- Implement agent hierarchies with sub-agents
79+
- Try different models (Claude, custom models, etc.)
80+
- Add memory and state management

‎maven_plugin/examples/simple-agent/pom.xml

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
7+
<groupId>com.example</groupId>
8+
<artifactId>simple-adk-agent</artifactId>
9+
<version>1.0-SNAPSHOT</version>
10+
<packaging>jar</packaging>
11+
12+
<name>Simple ADK Agent Example</name>
13+
<description>Example project showing how to create and run ADK agents with the Maven plugin</description>
14+
15+
<properties>
16+
<maven.compiler.source>11</maven.compiler.source>
17+
<maven.compiler.target>11</maven.compiler.target>
18+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
19+
<google-adk.version>0.2.1-SNAPSHOT</google-adk.version>
20+
</properties>
21+
22+
<dependencies>
23+
<dependency>
24+
<groupId>com.google.adk</groupId>
25+
<artifactId>google-adk</artifactId>
26+
<version>${google-adk.version}</version>
27+
</dependency>
28+
29+
<!-- Maven plugin dependency for AgentProvider interface -->
30+
<dependency>
31+
<groupId>com.google.adk</groupId>
32+
<artifactId>google-adk-maven-plugin</artifactId>
33+
<version>${google-adk.version}</version>
34+
<scope>compile</scope>
35+
</dependency>
36+
</dependencies>
37+
38+
<build>
39+
<plugins>
40+
<plugin>
41+
<groupId>org.apache.maven.plugins</groupId>
42+
<artifactId>maven-compiler-plugin</artifactId>
43+
<version>3.11.0</version>
44+
<configuration>
45+
<source>11</source>
46+
<target>11</target>
47+
</configuration>
48+
</plugin>
49+
50+
<!-- ADK Maven Plugin -->
51+
<plugin>
52+
<groupId>com.google.adk</groupId>
53+
<artifactId>google-adk-maven-plugin</artifactId>
54+
<version>${google-adk.version}</version>
55+
</plugin>
56+
</plugins>
57+
</build>
58+
</project>

0 commit comments

Comments
 (0)