Debian 13 “Trixie” provides a clean, stable base for Java agent development. On a
workstation, virtual machine, or cloud instance, you can compile Java projects, run
local web servers, use the Google Agent Development Kit (ADK) Dev UI, and deploy an
agent to Google Cloud Run.
This guide builds a small ADK agent with time and weather tools. The complete project
is available in the
Start with a Debian 13 installation and a user account that can run sudo
. Confirm
the operating-system version:
. /etc/os-release
printf '%s %s (%s)\n' "$NAME" "$VERSION_ID" "$VERSION_CODENAME"
Update the package index and install the base development tools:
sudo apt-get update
sudo apt-get install -y curl git maven unzip zip
This project compiles with Java 25. One convenient way to install a matching JDK is
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk list java
Select an available Java 25 identifier from the list and install it (for example, 25-open
):
sdk install java 25-open
java --version
mvn --version
Both commands should report Java 25, and Maven must be version 3.6.3 or newer. The
build enforces this minimum Maven version.
Add Google's Debian package repository:
sudo apt-get install -y apt-transport-https ca-certificates gnupg
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg \
| sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" \
| sudo tee /etc/apt/sources.list.d/google-cloud-sdk.list
sudo apt-get update
sudo apt-get install -y google-cloud-cli
Verify the installation:
gcloud version
The Google Cloud CLI is required for Vertex AI authentication and Cloud Run
deployment. It is not required if you only run the agent locally with a Gemini API
key.
git clone https://github.com/xbill9/adk-hello-world-java
cd adk-hello-world-java
The agent lives at
src/main/java/agents/multitool/MultiToolAgent.java
. Its public
ROOT_AGENT
field lets the ADK Dev UI discover it:
public static final BaseAgent ROOT_AGENT = initAgent();
public static BaseAgent initAgent() {
return LlmAgent.builder()
.name("multi_tool_agent")
.model("gemini-2.5-flash")
.description("Agent to answer questions about the time and weather in a city.")
.tools(
FunctionTool.create(MultiToolAgent.class, "getCurrentTime"),
FunctionTool.create(MultiToolAgent.class, "getWeather"))
.build();
}
The tools return structured maps with a status
and a human-readable report
. The
time tool uses IANA time zones and includes aliases for cities such as San Francisco,
Beijing, and Mumbai.
This sample uses ADK for Java 1.7.0, the latest release available from Maven
Central as of July 27, 2026. Both runtime dependencies use the same property so the
core library and Dev UI cannot drift to different versions:
<properties>
<google-adk.version>1.7.0</google-adk.version>
</properties>
<dependency>
<groupId>com.google.adk</groupId>
<artifactId>google-adk</artifactId>
<version>${google-adk.version}</version>
</dependency>
<dependency>
<groupId>com.google.adk</groupId>
<artifactId>google-adk-dev</artifactId>
<version>${google-adk.version}</version>
</dependency>
Recent changes relevant to this project include:
VertexAiSessionService
.gen_ai.usage.input_tokens
.gemini-2.5-flash
for a stable, broadly available tutorial baseline.These are framework improvements; the sample does not reimplement them. Keeping the
ADK dependencies pinned to 1.7.0 is what brings them into the application.
Run the setup script:
./init.sh
It offers two modes:
~/gemini.key
with user-only permissions.The selected mode is stored in ~/.adk-hello-world-java-auth
. Run ./init.sh
again
whenever you want to switch modes. The launch scripts source set_env.sh
automatically, so you do not need to export the variables by hand.
For Vertex AI, your account and the Cloud Run service identity must have the required
Vertex AI permissions. Cloud Run uses its service identity at runtime rather than a
downloaded credential file.
Compile the project and run its eight JUnit Jupiter tests:
make build
make test
The tests cover agent initialization, supported and unsupported cities, time-zone
aliases, and null input. Run Checkstyle separately:
make lint
The lint target fails when Google Java Style warnings are found, which makes it useful
in local development and continuous integration.
./cli.sh
Example session:
You > What is the current time in Tokyo?
Agent > The current time in Tokyo is 08:24.
You > What is the weather in New York?
Agent > The weather in New York is sunny with a temperature of 25 degrees Celsius
(77 degrees Fahrenheit).
You > quit
Start the local server:
./devui.sh
Open http://127.0.0.1:8080 in your browser. ADK scans the Maven
output under target/classes
and makes multi_tool_agent
available in the UI.
The web.sh
script is retained as an alias for devui.sh
.
ADK 1.6 tightened WebSocket origin handling and warns when the Dev UI uses the *
CORS default. That default is convenient for local development but should not be
treated as an access-control mechanism for a public deployment.
Cloud Run deployment uses Vertex AI rather than copying a local API key into the
service. If you selected API-key mode, run ./init.sh
again and choose Vertex AI.
Then deploy:
./cloudrun.sh
The script runs one source deployment for the adk-hello-world-java
service in
us-central1
. Because the repository contains a Dockerfile, Cloud Run builds that
Dockerfile remotely; Docker does not need to be installed on the Debian system.
The container reads Cloud Run's PORT
environment variable and starts the ADK web
server. When deployment completes, gcloud prints the service URL.
The deployment is private by default because the service includes the ADK Dev UI and
API. Configure authenticated callers with Cloud Run IAM. For a disposable public
demonstration, replace --no-allow-unauthenticated
with --allow-unauthenticated
in
cloudrun.sh
; do not rely on CORS as access control.
.
├── .dockerignore
├── .gcloudignore
├── Dockerfile
├── Makefile
├── cli.sh
├── cloudrun.sh
├── devui.sh
├── init.sh
├── pom.xml
├── set_env.sh
└── src
├── main/java/agents/multitool/MultiToolAgent.java
└── test/java/agents/multitool/MultiToolAgentTest.java
Debian Trixie provides everything needed to build and test a Java ADK agent locally.
This sample keeps local authentication explicit, verifies the tool logic with JUnit,
enforces Java style with Checkstyle, and uses Vertex AI service identity when deployed
to Cloud Run.