首页
/
文章
/
使用 Kotlin Agent 开发工具包（ADK）构建 AI 智能体
AI技术
使用 Kotlin Agent 开发工具包（ADK）构建 AI 智能体
✍️ zhirenhun
📅 2026/7/31
👁 222 阅读
⏱ 29 分钟
本教程将使用 Kotlin 和 Agent Development Kit（ADK）的原生 Kotlin 版本构建一个入门级的 "Hello World" 风格智能体。
完整的示例项目可在 GitHub 上获取：
Kotlin ADK 与 MCP Hello World
本项目是一个可运行的 Kotlin Agent Development Kit（ADK）演示。一个 Kotlin
LlmAgent 使用 Gemini 来决定何时调用从本地 Kotlin Model Context Protocol（MCP）服务器发现的 greet 工具。
该项目包含两个 Gradle 模块：
-
agent：Kotlin ADK 智能体、Gemini 模型配置、MCP 工具集和交互式 ReplRunner；
-
server：暴露 greet 的 Ktor MCP 服务器。
技术栈
-
Kotlin： 2.3.0
-
Kotlin ADK SDK：
com.google.adk:google-adk-kotlin-core (v0.6.0)
-
MCP Kotlin SDK：
io.modelcontextprotocol:kotlin-sdk-jvm (v0.8.1)
-
Ktor 框架： 3.0.0 (Netty, SSE, ContentNegotiation, CORS)
-
JDK： Java 25
-
构建系统： Gradle 9.2.1 (Kotlin DSL)
前提条件
- Java 25
- 一个 Gemini Developer API 密钥
已包含 Gradle wrapper。
配置 Gemini
创建本地环境文件：
设置 GOOGLE_API_KEY 在 .env 中，然后加载它：
该文件将被Git忽略。
运行演示
在一个…中启动Kotlin MCP服务器
什么是Kotlin？
Kotlin是由JetBrains创建的现代静态类型编程语言。它运行在Java虚拟机（JVM）上，可与现有Java库协同工作，并被广泛用于Android、后端和多平台开发。
静态类型在构建代理时尤其有用。代理配置、工具模式和工具结果都可以在提示词到达模型之前由编译器检查。
安装Java
此示例使用Java 25。如果未安装Java，SDKMAN!是在Linux和macOS上安装和切换JDK版本的便捷方式：
SDKMAN!是一种在大多数基于Unix的系统上管理多个软件开发工具包并行版本的工具。
sdkman.io
安装SDKMAN!后，列出可用的Java 25发行版：
安装您喜欢的Java 25发行版，然后验证当前版本：
该项目包含Gradle Wrapper，因此无需单独安装Gradle。
什么是智能体开发套件？
智能体开发套件（ADK）是Google用于构建和部署AI智能体的代码优先框架。它提供了配置模型、编写智能体指令、连接工具、管理会话以及在本地运行智能体所需的组件。
Google在此提供了Kotlin快速入门和API文档：
使用智能体开发套件（ADK）构建强大的多智能体系统
adk.dev
完整的Kotlin ADK源代码也可以在GitHub上获取：
面向 Kotlin 的 Agent 开发工具包 (ADK)
一个开源、代码优先的 Kotlin 工具包，用于灵活、可控地构建、评估和部署复杂的 AI 代理。
Agent 开发工具包 (ADK) 专为希望在构建与 Google Cloud 服务紧密集成的先进 AI 代理时实现细粒度控制和灵活性的开发者而设计。它允许您直接在代码中定义代理行为、编排和工具使用，从而实现在任何地方（从笔记本电脑到云端）进行可靠的调试、版本控制和部署。
✨ 主要功能
-
丰富的工具生态：利用预构建的工具、自定义函数、OpenAPI 规范，或集成现有工具，为智能体提供多样化的能力，所有这些都能与 Google 生态系统紧密集成。
-
代码优先开发：直接在 Kotlin 中定义智能体逻辑、工具和编排，以获得极致的灵活性、可测试性和版本控制能力。
-
模块化多智能体系统：通过组合多个专业化的…来设计可扩展应用。
Kotlin SDK 以 com.google.adk:google-adk-kotlin-core 的形式发布。本教程使用 Kotlin ADK 0.6.0。
Gemini API 密钥
你需要一个 Gemini 开发者 API 密钥才能运行交互式智能体。请在 Google AI Studio 中创建一个：
https://aistudio.google.com/apikey
MCP 服务器和工具发现冒烟测试不需要 API 密钥。
检查开发者环境
克隆示例仓库并运行初始化脚本。它会构建项目，并根据附带的模板创建本地 .env 文件：
git clone https://github.com/xbill9/adk-hello-world-kotlin
cd adk-hello-world-kotlin
source init.sh
输出：
Created .env from .env.example. Add your credentials before running the agent.
Setup complete. Start ./server.sh, then run ./run.sh in another terminal.
编辑 .env 并设置你的 API 密钥：
GOOGLE_API_KEY=your-api-key
将其加载到当前 shell 中：
source set_env.sh
注意：切勿提交.env。它已经列在.gitignore中。
Kotlin ADK 代理
该示例包含两个 Gradle 模块：
-
agent包含Kotlin ADK代理和交互式命令行运行器。
-
server包含一个Ktor MCP服务器，它暴露了greet工具。
核心代理在GreetingAgent.kt中定义。它配置Gemini，为代理提供指令，并连接一个MCP工具集：
return LlmAgent(
name = "kotlin_greeting_agent",
description = "A Kotlin ADK agent that greets people through an MCP tool.",
model =
Gemini(
name = modelName,
apiKey = apiKey,
),
instruction =
Instruction(
"""
You are a concise greeting assistant.
When the user asks you to greet someone, always call the greet tool with that
person's name. Return the greeting produced by the tool.
""".trimIndent(),
),
toolsets = listOf(mcpToolset),
)
LlmAgent 将模型、指令和可用工具整合在一起。模型默认使用 gemini-3.1-flash-lite，但你也可以通过 GEMINI_MODEL 环境变量选择其他模型。
将 Agent 连接到 MCP
与 TypeScript 天气示例不同，本项目将工具保存在单独的进程中。Agent 通过 模型上下文协议 发现并调用它。
GreetingAgent.kt 创建了一个连接到本地服务器的 McpToolset：
val mcpToolset =
McpToolset.McpToolsetConfig(
sseConnectionParams =
McpConnectionParameters.Sse(
url = mcpServerUrl,
sseEndpoint = "sse",
),
toolFilter = listOf("greet"),
).toToolset()
连接是惰性的。当代理需要其工具时，ADK会打开一个MCP会话，请求工具列表，并将greet模式提供给Gemini。工具过滤器将该代理限制为仅使用该单一工具。
服务器在Tools.kt中注册该工具：
server.addTool(
name = Config.Tools.GREET,
description = "Get a greeting from a local HTTP server.",
inputSchema =
ToolSchema(
properties =
buildJsonObject {
put(
Config.Tools.GREET_PARAM,
buildJsonObject {
put("type", "string")
put("description", "The name to greet")
},
)
},
required = listOf(Config.Tools.GREET_PARAM),
),
) { request ->
// Read the name and return: Hello, <name>!
}
智能体与服务器之间通过 HTTP 使用服务器推送事件（SSE）进行通信。默认情况下，服务器监听 http://localhost:8080，其中 /sse 用于事件流，/messages 用于客户端消息。
构建、测试与代码风格
一条命令即可构建两个模块、运行单元测试并检查 Kotlin 格式：
您可以直接调用Gradle任务：
./gradlew build ktlintCheck test
这些测试检查 ADK 代理是否包含其 MCP 工具集，以及问候逻辑是否返回预期的文本。由于问候格式化器是一个普通的 Kotlin 函数，因此无需调用 Gemini 即可对其进行测试：
@Test
fun testFormatGreeting() {
val result = Tools.formatGreeting("Kotlin Developer")
assertEquals("Hello, Kotlin Developer!", result)
}
如果 ktlintCheck 报告样式问题，请运行 make format。
从命令行运行 ADK
工具服务器和代理作为独立应用程序运行。在一个终端中启动 MCP 服务器：
在第二个终端中，加载环境并启动代理：
source set_env.sh
./run.sh
示例将活动的SSE会话存储在内存中，因此所提供的Cloud Run配置将服务限制为单个实例。它还允许为演示目的进行未经身份验证的访问。在生产环境中使用此设计之前，请添加身份验证、授权、更严格的CORS规则以及共享会话存储。
