第三篇：快速入门——构建并运行你的第一个 ADK 智能代理

在前两篇文章中，我们一起领略了 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环境：https://www.anaconda.com/download

下载对应的版本

开始安装

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

你就可以使用conda进行创建环境python3.12版本，环境命名为adk312：
conda create -n adk312 python=3.12Plain Text

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

1.2 安装 ADK激活虚拟环境后，使用 pip 安装 ADK：pip install google-adkPlain Text等待安装完成即可。

1.3 获取并配置 Google API KeyADK 需要借助 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

Plain Text项目结构如下：

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` 工具进行问候。"        
        "如果未提及名字，请友好地询问用户叫什么。"    
))

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 代理的道路上携手前行！