AI技术

使用 Kotlin Agent 开发工具包（ADK）构建 AI 智能体

✍️ zhirenhun 📅 2026/7/31 👁 254 阅读 ⏱ 18 分钟

本教程将使用 Kotlin 和 Agent Development Kit（ADK）的原生 Kotlin 版本构建一个入门级的 "Hello World" 风格智能体。

完整的示例项目可在 GitHub 上获取：

安装SDKMAN!后，列出可用的Java 25发行版：

sdk list java

安装您喜欢的Java 25发行版，然后验证当前版本：

java --version

该项目包含Gradle Wrapper，因此无需单独安装Gradle。

什么是智能体开发套件？

智能体开发套件（ADK）是Google用于构建和部署AI智能体的代码优先框架。它提供了配置模型、编写智能体指令、连接工具、管理会话以及在本地运行智能体所需的组件。

Google在此提供了Kotlin快速入门和API文档：

完整的Kotlin ADK源代码也可以在GitHub上获取：

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 格式：

make check

您可以直接调用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 服务器：

./server.sh

在第二个终端中，加载环境并启动代理：

source set_env.sh
./run.sh

Gradle 命令提供相同的入口点：

./gradlew :server:run
./gradlew :agent:run

让智能体向某人问好：

Greet Kotlin Developer

Gemini 选择已发现的 greet 工具并提供：

{"param":"Kotlin Developer"}

MCP服务器返回：

Hello, Kotlin Developer!

输入 exit 以关闭代理。

无需调用 Gemini 即可测试 MCP

您可以独立于模型验证 MCP 连接。在服务器运行时，使用 Kotlin ADK 冒烟测试：

./gradlew :agent:smokeMcp

这通过 McpToolset 连接，并确认代理可以发现 greet。它不需要 GOOGLE_API_KEY。

该仓库还包含一个直接的 Python JSON-RPC 客户端：

python3 test_mcp.py

它初始化一个MCP会话，列出可用的工具，调用greet并传入Galaxy，然后验证响应Hello, Galaxy!。

将MCP服务器部署到Cloud Run

该项目将Ktor MCP服务器作为容器部署。ADK代理保持客户端身份，并通过MCP_SERVER_URL连接到已部署的服务。

gcloud auth login
gcloud config set project YOUR_PROJECT_ID
./cloudrun.sh

该脚本提交cloudbuild.yaml，该文件构建Docker镜像，将其推送到Container Registry，并将服务部署到Cloud Run。

示例将活动的SSE会话存储在内存中，因此所提供的Cloud Run配置将服务限制为单个实例。它还允许为演示目的进行未经身份验证的访问。在生产环境中使用此设计之前，请添加身份验证、授权、更严格的CORS规则以及共享会话存储。

检查Google Cloud Console

部署后，获取服务URL：

gcloud run services describe adk-hello-world-kotlin \
  --region us-central1 --format 'value(status.url)'

将本地代理指向该URL：

export MCP_SERVER_URL="https://your-service-url"
./run.sh

摘要

Kotlin Agent 开发套件借助熟悉的 Kotlin 和 Gradle 工具，将 Agent 开发带到 JVM：

类型化 Agent 配置： 使用 Kotlin 配置 LlmAgent、Gemini 和指令。
MCP 工具集成： 发现并调用由独立 Ktor 服务托管的工具。
确定性测试： 在不发起模型请求的情况下测试工具行为。
本地开发： 直接从 Gradle 运行服务器和交互式 Agent。
云部署： 将 MCP 服务器打包到容器中并部署到 Cloud Run。

——

🧑‍💻

zhirenhun

一个热爱技术的程序员，喜欢分享前沿AI知识和开发经验。

kotlin ai gemini webdev