在前两篇文章中，我们一起领略了 AI 代理的崛起，初步认识了 Google 推出的 Agent Development Kit（ADK）的理念与能力。我们不仅了解了 ADK 的核心概念，也掌握了其模块化架构和关键组件。在铺垫了这些理论之后，现在，是时候动手实践了！

本篇将以 一步步带你构建第一个可运行的 ADK 智能代理 为目标，手把手完成从环境配置、项目搭建，到功能实现、交互测试的全过程。如果你渴望通过一个轻量级示例理解 ADK 的开发流程，那这篇文章就是为你量身打造的“Hello World”指南。

---

一、准备工作：开发环境与安装

1.1 安装 Python 与创建虚拟环境

ADK 是一个 Python 库，因此你首先需要具备一个 Python 环境。

Python版本： 建议使用 Python 3.9 或更高版本。

登录https://www.python.org/

下载文件如下

进行安装，勾选“Add python.exe to PATH”

验证安装是否成功,输入 python --version 有版本输出则表示成功

虚拟环境（推荐）： 为了保持项目依赖的清洁和隔离，强烈建议使用虚拟环境。

下载安装conda环境：Download Anaconda Distribution | Anaconda

下载对应的版本

开始安装

安装完成之后可以打开 Anaconda PowerShell Prompt

你就可以使用conda进行创建环境python3.12版本，环境命名为adk312：

conda create -n adk312 python=3.12

切换环境进入adk312环境，查看python版本为3.12.9

1.2 安装 ADK

激活虚拟环境后，使用 pip 安装 ADK：

pip install google-adk

等待安装完成即可。

1.3 获取并配置 Google API Key

ADK 需要借助 Google 的 Gemini 模型运行，因此你需要申请 API Key：

• 获取地址：Google AI Studio

• 获取后，建议将 API Key 写入项目根目录的 .env 文件：

.env 文件内容示例：

GOOGLE_GENAI_USE_VERTEXAI=FALSE

GOOGLE_API_KEY=AIzaS********************Y4tKmj0

💡 提示：将 .env 添加进 .gitignore，防止 API 密钥泄露。

---

二、构建项目结构

我们将创建一个名为 my_first_adk_project 的入门项目：

mkdir my_first_adk_project

cd my_first_adk_project

touch .env

mkdir my_agent_package

touch my_agent_package/__init__.py

touch my_agent_package/agent.py

项目结构如下：

my_first_adk_project/

├── .env # 环境变量文件

└── my_agent_package/

├── __init__.py # 初始化模块

└── agent.py # 智能代理逻辑

---

三、编写第一个“问候世界”代理

我们将构建一个最简代理——它能够识别用户的名字，并用热情的话语欢迎用户。

3.1 编写 agent.py

打开 my_agent_package/agent.py，输入以下代码：

from google.adk.agents import Agent

# 一个简单的工具函数

def hello_world_tool(name: str) -> str:

return f"你好，{name}！欢迎来到 ADK 的世界！很高兴与你互动。"

# 创建代理实例

root_agent = Agent(

name="WelcomeAgent",

model="gemini-2.0-flash",

tools=[hello_world_tool],

instruction=(

"你是一个友好的 AI 助手，名叫“小爱”。"

"你的任务是热情地欢迎用户。"

"当用户提到名字时，请调用 `hello_world_tool` 工具进行问候。"

"如果未提及名字，请友好地询问用户叫什么。"

)

)

Plain Text

3.2 配置 __init__.py

打开 my_agent_package/__init__.py，添加以下内容：

from .agent import root_agent

这一步确保 ADK 能自动识别并加载代理。环境变量采用之前创建的adk312.

---

四、运行与测试代理

4.1 启动 ADK Web 服务

确保位于项目根目录，激活虚拟环境，运行：

adk web

若启动成功，控制台会显示：

INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

4.2 打开浏览器访问 Dev UI

浏览器访问：http://localhost:8000

你将看到 ADK 提供的可视化开发界面。

4.3 与代理进行交互测试

测试一（未提供名字）：

输入： 你好

代理回复（预期）： 你好！请问我该怎么称呼你呢？

测试二（提供名字）：

输入： 我叫李明

代理回复（预期）： 你好，李明！欢迎来到 ADK 的世界！很高兴与你互动。

测试三（自然对话中提及名字）：

输入： 你好，我是王芳。

代理回复（预期）： 你好，王芳！欢迎来到 ADK 的世界！很高兴与你互动。

---

五、调试与进一步探索

5.1 Dev UI 中的事件追踪

点击界面中的“Events”面板，你可以观察代理运行的全过程：

• 用户输入

• LLM 解析意图

• 工具调用与返回结果

• 最终生成的回答

通过可视化事件流，你可以更好地理解代理背后的推理与执行机制。

5.2 常见问题排查

问题	排查建议
API Key 无效或错误	检查 .env 配置，确认 Key 正确且已启用相应模型权限
工具未触发	检查指令是否明确引导 LLM 使用工具
工具调用失败或报错	检查函数签名是否正确，参数类型是否匹配
代理未响应或报异常	查看终端输出的错误日志，必要时添加 print() 进行调试

---

六、总结与进阶方向

🎉 恭喜你！你已经完成了第一个 ADK 智能代理的构建与运行。通过这个入门项目，你掌握了以下核心流程：

• 配置开发环境与安装 ADK；

• 构建标准项目结构；

• 编写工具函数与代理指令；

• 启动本地 Web 服务与进行交互测试；

• 利用 Dev UI 可视化调试代理行为。

这只是 ADK 世界的冰山一角。在后续探索中，你可以尝试：

• 🔧 添加更复杂的工具（如天气查询、翻译服务等）；

• 🤖 构建多轮对话代理，使用记忆机制保持上下文；

• 🧠 使用多智能体协同（如 SequentialAgent、ParallelAgent）；

• 📦 集成外部 API，开发真实业务应用；

• 🛠 利用 ADK 的 Callbacks 和 Artifacts 打造完整智能系统。

---

写在最后

Google ADK 是一套极具潜力的 AI 代理开发工具，它以模块化、易扩展、支持工具调用为特性，为“行动型智能体”提供了广阔舞台。如果你对构建具备感知、思考与执行能力的 AI 系统充满兴趣，ADK 值得你深入研究与尝试。

🚀 现在，你已经踏出了第一步。欢迎留言分享你的构建体验或提出任何问题，让我们在 AI 代理的道路上携手前行！