Java Quickstart for ADK¶
ADK Java 快速入门¶
This guide shows you how to get up and running with Agent Development Kit for Java. Before you start, make sure you have the following installed:
本指南向您展示如何开始使用 Java 版智能体开发工具包。在开始之前,请确保您已安装以下内容:
- Java 17 or later Java 17 或更高版本
- Maven 3.9 or later Maven 3.9 或更高版本
Create an agent project¶
创建智能体项目¶
Create an agent project with the following files and directory structure:
创建一个具有以下文件和目录结构的智能体项目:
my_agent/
src/main/java/com/example/agent/
HelloTimeAgent.java # main agent code
# 主要智能体代码
AgentCliRunner.java # command-line interface
# 命令行界面
pom.xml # project configuration
# 项目配置
.env # API keys or project IDs
# API 密钥或项目 ID
Create this project structure using the command line
使用命令行创建此项目结构
Define the agent code¶
定义智能体代码¶
Create the code for a basic agent, including a simple implementation of an ADK
Function Tool, called getCurrentTime().
Add the following code to the HelloTimeAgent.java file in your project
directory:
创建基本智能体的代码,包括 ADK 函数工具 的简单实现,称为 getCurrentTime()。
将以下代码添加到项目目录中的 HelloTimeAgent.java 文件:
package com.example.agent;
import com.google.adk.agents.BaseAgent;
import com.google.adk.agents.LlmAgent;
import com.google.adk.tools.Annotations.Schema;
import com.google.adk.tools.FunctionTool;
import java.util.Map;
public class HelloTimeAgent {
public static BaseAgent ROOT_AGENT = initAgent();
private static BaseAgent initAgent() {
return LlmAgent.builder()
.name("hello-time-agent")
.description("Tells the current time in a specified city")
.description("返回指定城市的当前时间")
.instruction("""
You are a helpful assistant that tells the current time in a city.
Use the 'getCurrentTime' tool for this purpose.
您是一个有用的助手,可以告诉您城市的当前时间。
使用 'getCurrentTime' 工具来实现此目的。
""")
.model("gemini-2.5-flash")
.tools(FunctionTool.create(HelloTimeAgent.class, "getCurrentTime"))
.build();
}
/** Mock tool implementation */
/** 模拟工具实现 */
@Schema(description = "Get the current time for a given city")
@Schema(description = "获取给定城市的当前时间")
public static Map<String, String> getCurrentTime(
@Schema(name = "city", description = "Name of the city to get the time for")
@Schema(name = "city", description = "要获取时间的城市名称")
String city) {
return Map.of(
"city", city,
"forecast", "The time is 10:30am.",
"forecast", "时间是上午10:30。"
);
}
}
Caution: Gemini 3 compatibility
警告:Gemini 3 兼容性
ADK Java v0.3.0 and lower is not compatible with Gemini 3 Pro Preview due to thought signature changes for function calling. Use Gemini 2.5 or lower models instead.
ADK Java v0.3.0 及更低版本与 Gemini 3 Pro Preview 不兼容,这是因为函数调用的思维签名更改。请改用 Gemini 2.5 或更低版本的模型。
Configure project and dependencies¶
配置项目和依赖项¶
An ADK agent project requires this dependency in your
pom.xml project file:
ADK 智能体项目需要在您的 pom.xml 项目文件中包含此依赖项:
<dependencies>
<dependency>
<groupId>com.google.adk</groupId>
<artifactId>adk-core</artifactId>
<version>0.3.0</version>
</dependency>
</dependencies>
Update the pom.xml project file to include this dependency and
additional settings with the following configuration code:
更新 pom.xml 项目文件以包含此依赖项和以下配置代码中的其他设置:
Complete pom.xml configuration for project
项目的完整 pom.xml 配置
The following code shows a complete pom.xml configuration for
this project:
以下代码显示了此项目的完整 pom.xml 配置:
<?xml version="1.0" encoding="UTF-8"?>
<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>
<groupId>com.example.agent</groupId>
<artifactId>adk-agents</artifactId>
<version>1.0-SNAPSHOT</version>
<!-- Specify the version of Java you'll be using -->
<!-- 指定您将要使用的 Java 版本 -->
<properties>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<!-- The ADK core dependency -->
<!-- ADK 核心依赖项 -->
<dependency>
<groupId>com.google.adk</groupId>
<artifactId>google-adk</artifactId>
<version>0.3.0</version>
</dependency>
<!-- The ADK dev web UI to debug your agent -->
<!-- 用于调试智能体的 ADK 开发 Web UI -->
<dependency>
<groupId>com.google.adk</groupId>
<artifactId>google-adk-dev</artifactId>
<version>0.3.0</version>
</dependency>
</dependencies>
</project>
Set your API key¶
设置您的 API 密钥¶
This project uses the Gemini API, which requires an API key. If you don't already have a Gemini API key, create a key in Google AI Studio on the API Keys page.
本项目使用 Gemini API,该 API 需要 API 密钥。如果您还没有 Gemini API 密钥,请前往 Google AI Studio 在 API 密钥 页面创建密钥。
In a terminal window, write your API key into the .env file of your project
to set environment variables:
在终端窗口中,将您的 API 密钥写入项目的 .env 文件以设置环境变量:
Using other AI models with ADK
在 ADK 中使用其他 AI 模型
ADK supports the use of many generative AI models. For more information on configuring other models in ADK agents, see Models & Authentication.
ADK 支持使用多种生成式 AI 模型。有关在 ADK 智能体中配置其他模型的更多信息,请参阅模型和身份验证。
Create an agent command-line interface¶
创建智能体命令行界面¶
Create an AgentCliRunner.java class to allow you to run and interact with
HelloTimeAgent from the command line. This code shows how to create a
RunConfig object to run the agent and a Session object to interact with the
running agent.
创建 AgentCliRunner.java 类,允许您从命令行运行和与 HelloTimeAgent 交互。此代码展示如何创建 RunConfig 对象来运行智能体以及 Session 对象来与运行的智能体交互。
package com.example.agent;
import com.google.adk.agents.RunConfig;
import com.google.adk.events.Event;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.sessions.Session;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import io.reactivex.rxjava3.core.Flowable;
import java.util.Scanner;
import static java.nio.charset.StandardCharsets.UTF_8;
public class AgentCliRunner {
public static void main(String[] args) {
RunConfig runConfig = RunConfig.builder().build();
InMemoryRunner runner = new InMemoryRunner(HelloTimeAgent.ROOT_AGENT);
Session session = runner
.sessionService()
.createSession(runner.appName(), "user1234")
.blockingGet();
try (Scanner scanner = new Scanner(System.in, UTF_8)) {
while (true) {
System.out.print("\nYou > ");
String userInput = scanner.nextLine();
if ("quit".equalsIgnoreCase(userInput)) {
break;
}
Content userMsg = Content.fromParts(Part.fromText(userInput));
Flowable<Event> events = runner.runAsync(session.userId(), session.id(), userMsg, runConfig);
System.out.print("\nAgent > ");
events.blockingForEach(event -> {
if (event.finalResponse()) {
System.out.println(event.stringifyContent());
}
});
}
}
}
}
Run your agent¶
运行您的智能体¶
You can run your ADK agent using the interactive command-line interface
AgentCliRunner class you defined or the ADK web user interface provided by
the ADK using the AdkWebServer class. Both these options allow you to test and
interact with your agent.
您可以使用您定义的交互式命令行界面 AgentCliRunner 类或 ADK 使用 AdkWebServer 类提供的 ADK Web 用户界面运行您的 ADK 智能体。这两个选项都允许您测试和与智能体交互。
Run with command-line interface¶
使用命令行界面运行¶
Run your agent with the command-line interface AgentCliRunner class
using the following Maven command:
使用以下 Maven 命令通过命令行界面 AgentCliRunner 类运行您的智能体:
# Remember to load keys and settings: source .env OR env.bat
# 记住加载密钥和设置: source .env 或 env.bat
mvn compile exec:java -Dexec.mainClass="com.example.agent.AgentCliRunner"
Run with web interface¶
使用 Web 界面运行¶
Run your agent with the ADK web interface using the following Maven command:
使用以下 Maven 命令通过 ADK Web 界面运行您的智能体:
# Remember to load keys and settings: source .env OR env.bat
# 记住加载密钥和设置: source .env 或 env.bat
mvn compile exec:java \
-Dexec.mainClass="com.google.adk.web.AdkWebServer" \
-Dexec.args="--adk.agents.source-dir=target --server.port=8000"
This command starts a web server with a chat interface for your agent. You can access the web interface at (http://localhost:8000). Select your agent at the upper left corner and type a request.
此命令启动一个带有智能体聊天界面的 Web 服务器。您可以在 (http://localhost:8000) 访问 Web 界面。在左上角选择智能体并输入请求。
Caution: ADK Web for development only
警告:ADK Web 仅用于开发
ADK Web is not meant for use in production deployments. You should use ADK Web for development and debugging purposes only.
ADK Web 不适用于生产环境部署。您应该仅将 ADK Web 用于开发和调试目的。
Next: Build your agent¶
下一步:构建您的智能体¶
Now that you have ADK installed and your first agent running, try building your own agent with our build guides:
既然您已经安装了 ADK 并运行了第一个智能体,请尝试使用我们的构建指南构建您自己的智能体: