最近我正在开发一个小型研究助手，需要用它来查证各种说法是否有可靠的信息来源。我一开始选了一个热门的 agent 框架，结果跟抽象基类、依赖注入容器还有三个不同的配置文件死磕了两个小时，最后还是没跑通一个能用的原型。我只是想传一段话给模型，让它搜一下，然后告诉我这说法靠不靠谱而已。这根本不需要写 400 行模板代码吧。
正是这种抓狂的经历，让我找到了 Google 的 Agent Development Kit（ADK）。它是开源的，主打代码优先，承诺也很简单：用不到 100 行 Python 代码就能构建一个可用的 agent。我一开始是持怀疑态度的，但还是决定试一把。下面是我的真实体验，从环境搭建到跑通一个带本地 Web UI 的事实核查 agent，全流程分享。
环境搭建
首先，得把前置条件准备好。你需要 Python（我用的是 3.12）和 uv，这是一个超快的 Python 包管理器。如果你之前没用过 uv，光图个速度也绝对值得从 pip 换过来。我当时用的是 uv 0.11.7 版本。
你还需要从 Google AI Studio 获取一个 Gemini API 密钥。这点稍微让我有点意外——要想用这个 Gemini API 密钥，你得有一个开通了账单结算或还有有效额度的 Google Cloud Platform（GCP）账号。如果你之前没弄过这些，那就在 GCP 控制台里再预留 15 分钟的折腾时间吧。
拿到 API 密钥后，我创建了项目目录并设置了虚拟环境：
mkdir fact-checker-agent && cd fact-checker-agent
uv venv
source .venv/bin/activate
然后，安装 ADK 的 Python 包：
uv pip install google-adk
这会把框架和它的依赖都拉下来。整个过程干净利落——我电脑上居然没出现奇怪的依赖冲突，还真是个惊喜。
构建 Fact-Checker Agent
现在来写实际的代码。在 ADK 中，agent 是声明式定义的。你指定一下模型，起个名字，写清楚指令，再挂上它需要的工具就行了。我建了个 agent.py 文件：
from google.adk import Agent
from google.adk.tools import google_search
fact_checker = Agent(
name="fact_checker",
model="gemini-2.0-flash",
instruction="""You are a precise fact-checking assistant. When a user presents a claim,
you must:
1. Search for reliable sources to verify the claim
2. Evaluate the credibility of the sources you find
3. Provide a clear verdict: TRUE, FALSE, PARTIALLY TRUE, or UNVERIFIABLE
4. Cite the sources you used to reach your conclusion
5. If the claim is nuanced, explain the context
Always be transparent about your confidence level. If you cannot find sufficient
information, say so rather than guessing.""",
tools=[google_search]
)
就这些。这就是整个 agent 的定义。我来拆解一下这里面的内容：
- name：agent 的标识符。等你以后开始构建多 agent 系统时，这个会很重要，不过即使是单 agent 也是必填的。
- model：我选了
gemini-2.0-flash，因为在事实核查这个场景下，它又快又划算。当然，你可以根据自己的需求选其他 Gemini 模型。 - instruction：这就是系统提示词。我在这里花了不少心思打磨，因为 agent 输出质量很大程度上取决于你把它的行为约束得有多明确。这种结构化的格式（结论 + 来源 + 置信度）能让回复保持一致。
- tools：我给它配了
google_search，这是 ADK 的内置工具。有了它，agent 才能真正去网上查东西，而不是光靠训练数据瞎编。
我本来以为 google_search 工具的接入会很复杂，没想到 ADK 内部直接把工具调用的循环处理好了。agent 自己决定什么时候搜索、解析结果，然后把结果整合到回复里。我完全不用写任何处理 HTTP 请求或解析结果的代码。
在命令行（CLI）中运行 Agent
在搞花哨的 UI 之前，我想先在终端里测试一下。ADK 提供了一个 CLI 运行器，让你能直接跟 agent 交互。我写了个简单的入口文件：
# main.py
from agent import fact_checker
if __name__ == "__main__":
from google.adk.cli import run_agent
run_agent(fact_checker)
然后运行它：
python main.py
这会在终端里打开一个交互式提示符。我拿几个说法测试了一下：
我：“用肉眼从太空中能看到中国的长城。”
Agent：“结论：错误（FALSE）。这是一个常见的误解。多位宇航员，包括国际空间站上的宇航员，都证实过仅凭肉眼从近地轨道是看不到长城的。它太窄了（大部分路段只有约 6 米宽），而且跟周围的地形融为一体。来源：NASA 报告，宇航员 Jeffrey Hoffman 和国际空间站指令长 Chris Hadfield 的声明。”
我：“蜂蜜永远不会变质。”
Agent：“结论：正确（TRUE），但有前提。考古学家在古埃及墓葬中发现了 3000 多年前的蜂蜜罐，至今仍然完全可以食用。蜂蜜水分极低、pH 值呈酸性，加上天然产生的过氧化氢，共同营造了一个让细菌和微生物无法生存的环境。不过，如果接触到水分，蜂蜜也会发酵。来源：《史密森尼杂志》，《考古科学杂志》。”
回复的结构跟我在指令里规定的完全一致，而且搜索结果是实时拉取的。这种 CLI 模式非常适合快速迭代你的指令——你能立刻看到提示词的修改是怎么影响行为的。
我早期犯过一个错：第一版指令写得太含糊，只写了“查证说法是否属实”。结果 agent 给出的回答模棱两可，也不给来源。加上明确的结构（结论、来源、置信度）后，输出质量有了质的飞跃。
使用 Web UI 运行 Agent
CLI 用来开发还行，但 ADK 还自带了一个内置的 Web 测试场。这个功能真的让我惊艳了——真没想到开箱即用就能有这么精致的本地 UI。
启动命令如下：
adk web
这会启动一个本地服务器，并打开一个浏览器界面，你可以在里面跟 agent 聊天。Web UI 不仅显示对话内容，更重要的是，它还能显示 agent 的工具调用过程。你可以清楚地看到它什么时候决定搜索、发了什么查询词、返回了什么结果。这种透明度对调试来说简直是无价之宝。
我第一次运行 adk web 时报错了，因为我没把 API 密钥设为环境变量。解决办法很简单：
export GOOGLE_API_KEY="your-api-key-here"
adk web
在 Web UI 里，我能看到完整的工具调用轨迹。就拿那个蜂蜜的说法来说，我亲眼看着 agent 构思了一个搜索查询，拿到结果后，又构思了第二个更具体的查询去查考古证据，最后把两次的结果综合成最终答案。看到这条推理链，我才明白我的 agent 是真的在进行多步研究，而不是简单的模式匹配。
实用技巧与坦诚的局限性
花了一个周末用 ADK 搞开发，以下是我的经验总结：
从指令开始打磨。 agent 的质量 80% 取决于你指令提示词写得有多好。在增加复杂度之前，多花点时间在这上面。
**用 Web UI 调试。**光是工具调用的可视化这一点，就值得你运行 adk web 而不是只在 CLI 里测试了。你能更快地发现诸如 agent 搜错东西之类的问题。
内置工具少但精。 google_search 很好用，但如果你需要自定义工具（比如调你自己的 API 或数据库），就得用 @tool 装饰器把它们写成 Python 函数。自定义工具的文档还不太完善，所以得做好试错的心理准备。
Python 优先。 ADK 支持 TypeScript、Go、Java 和 Kotlin，但不管是看示例还是看社区活跃度，Python SDK 显然是最成熟的。如果你在选语言，目前首选 Python。
真正的局限在于单 agent 的范围。 这个事实核查 agent 单独运行很棒，但 ADK 真正的威力据说在于多 agent 系统，也就是 agent 之间可以互相委派任务。我还没探索到那一步，而且那部分的学习曲线看起来会更陡。
API 费用会积少成多。 每次事实核查至少涉及一次带搜索的 Gemini 调用。如果你要上生产环境，记得监控 API 用量。Gemini 2.0 Flash 虽然便宜，但也不是免费的。
总的来说，ADK 兑现了它的承诺。我在不到一小时内，用了不到 30 行实际代码，就从零做出了一个能用的 agent。内置的 Web 测试场和工具调用可视化让整个开发过程非常舒服。如果你也受够了框架的繁琐模板，只想赶紧做个能跑起来的东西，不妨试试看。