用Google ADK从零搭一个能调工具的AI Agent：Python实操全过程

上周在GitHub Trending翻到Google ADK（Agent Development Kit），点进去看了下——官方仓库 google/adk-python 两周涨了几千star。拉下来跑了一圈，发现这东西确实比我预期的好用，20分钟就能把一个带工具调用的Agent跑起来。

下面记录我从安装到踩坑到最后跑通多Agent协作的全过程。代码都贴了，你直接复制就能跑。

ADK是个什么东西

一句话：Google出的AI Agent开发框架，Python写的，开源。

和LangGraph、CrewAI这些比，ADK的思路不太一样。它不搞复杂的抽象层，核心就几个概念：Agent、Tool、Runner、Session。你定义一个Agent，给它挂几个Tool，用Runner跑起来，Session管上下文。就这么简单。

它还内置了一个Web调试界面，adk web一敲就能在浏览器里跟Agent对话，看工具调用的全过程。这个功能在调试的时候省了不少事。

支持的模型不止Gemini。官方文档写了可以接OpenAI、Anthropic的模型，不过我这次测试用的是Gemini 2.0 Flash，因为API免费申请，跑测试不花钱。

环境搭建

需要Python 3.10+。我用的3.11。

# 建虚拟环境（别污染全局）python3-mvenv.venvsource.venv/bin/activate# 装ADKpipinstallgoogle-adk

装完之后多了个adk命令行工具。用它创建项目：

adkcreatemy_agent

生成的目录结构：

my_agent/ agent.py # Agent主逻辑 .env # 放API Key __init__.py

够简洁。没有一堆配置文件。

申请Gemini API Key

去 https://aistudio.google.com/app/apikey 申请，免费的。拿到Key之后写进.env：

echo'GOOGLE_API_KEY="你的Key"'>my_agent/.env

如果你在国内访问Gemini API有问题，可以挂代理，或者换成OpenAI的模型（ADK支持，后面讲）。

第一个Agent：带工具调用

改my_agent/agent.py，写一个能查天气的Agent：

fromgoogle.adk.agents.llm_agentimportAgentimportrandomdefget_weather(city:str)->dict:"""查询指定城市的天气情况。"""# 这里用mock数据，实际项目换成真实APIweather_data={"北京":{"temp":"22°C","condition":"晴"},"上海":{"temp":"25°C","condition":"多云"},"深圳":{"temp":"30°C","condition":"雷阵雨"},}ifcityinweather_data:w=weather_data[city]return{"status":"success","city":city,"temperature":w["temp"],"condition":w["condition"]}return{"status":"error","message":f"暂无{city}的天气数据"}defget_current_time(city:str)->dict:"""返回指定城市的当前时间。"""fromdatetimeimportdatetime,timezone,timedelta# 简化处理，都用东八区tz=timezone(timedelta(hours=8))now=datetime.now(tz)return{"status":"success","city":city,"time":now.strftime("%H:%M")}root_agent=Agent(model='gemini-2.0-flash',name='weather_agent',description="查询城市天气和时间的助手。",instruction="你是一个天气助手。用户问天气就调 get_weather，问时间就调 get_current_time。用中文回复。",tools=[get_weather,get_current_time],)

跑起来：

# 命令行模式adkrunmy_agent# 或者Web界面模式adkweb--port8000

命令行模式下直接打字交互：

You > 北京今天天气怎么样？ Agent > 北京现在22°C，天气晴。

Web界面模式更直观，左边选Agent，右边聊天，中间能看到每次工具调用的参数和返回值。调试的时候特别好用。

踩坑点：工具函数的写法

这里有个坑我踩了半小时。ADK对工具函数有几个要求：

1. 参数必须有类型标注（city: str），不标注的话Agent不知道传什么类型
2. 必须写docstring（就是函数下面那个三引号注释），ADK拿这个当工具描述发给模型
3. 返回值最好是dict，别返回纯字符串

我一开始把docstring删了，Agent死活不调工具。加上之后就正常了。这块文档里提了一嘴但不显眼，容易漏。

另一个坑：如果你的函数参数名取得太抽象（比如x、param1），模型经常传错值。参数名尽量语义化。

进阶：接MCP Server

ADK原生支持MCP协议。意思是你可以把现成的MCP Server当工具挂到Agent上。

比如接一个文件系统的MCP Server，让Agent能读写文件：

fromgoogle.adk.agents.llm_agentimportAgentfromgoogle.adk.tools.mcp_toolimportMCPToolset,SseServerParams,StdioServerParams# 用npx跑MCP Server（需要Node.js环境）mcp_filesystem=StdioServerParams(command="npx",args=["-y","@modelcontextprotocol/server-filesystem","/tmp/workspace"])asyncdefbuild_agent():tools,exit_stack=awaitMCPToolset.from_server(connection_params=mcp_filesystem)agent=Agent(model='gemini-2.0-flash',name='file_agent',description="能读写文件的助手。",instruction="你是一个文件管理助手，可以帮用户读取、创建、修改文件。",tools=tools,)returnagent,exit_stack

几行代码干了一件事：用npx启动文件系统MCP Server，把它暴露的工具（read_file、write_file、list_directory等）全挂到Agent上。Agent就能操作/tmp/workspace目录下的文件了。

实测效果：

You > 帮我在workspace下创建一个hello.txt，内容写"测试ADK" Agent > 好的，已经创建了 /tmp/workspace/hello.txt，内容是"测试ADK"。

比自己写文件操作工具方便太多。MCP生态里有数据库、GitHub、飞书、Slack各种Server，拿来就用。

多Agent协作

ADK支持把多个Agent串起来。比如一个Agent负责搜索，一个Agent负责写总结：

fromgoogle.adk.agents.llm_agentimportAgent# 搜索Agentsearch_agent=Agent(model='gemini-2.0-flash',name='search_agent',description="负责搜索信息的Agent。",instruction="你负责根据用户的问题搜索相关信息，返回搜索结果。",tools=[web_search_tool],# 假设已定义搜索工具)# 写作Agentwriter_agent=Agent(model='gemini-2.0-flash',name='writer_agent',description="负责整理和撰写内容的Agent。",instruction="你负责根据提供的信息写一篇简洁的中文摘要，300字以内。",)# 协调Agent（root）root_agent=Agent(model='gemini-2.0-flash',name='coordinator',description="协调搜索和写作的主Agent。",instruction="""你是协调员。收到用户问题后：1. 先让search_agent搜索相关信息2. 把搜索结果交给writer_agent整理成摘要3. 把最终摘要返回给用户""",sub_agents=[search_agent,writer_agent],)

sub_agents这个参数就是多Agent协作的关键。root_agent会根据instruction自动决定什么时候调哪个子Agent。

实际跑的时候，Web界面里能看到消息在Agent之间流转的全过程，谁调了谁、传了什么参数、返回了什么结果，一目了然。

和LangGraph、CrewAI对比

用了几天之后说说感受：

ADK的优点是上手快。pip install加adk create两步就能开始写Agent，不需要理解一堆抽象概念。工具函数就是普通Python函数，加个docstring就行。

LangGraph适合需要复杂状态管理的场景。它的图结构定义比ADK灵活，但学习成本也高——你得先理解StateGraph、Node、Edge这些概念。

CrewAI偏重角色扮演和任务分配。如果你的场景是"几个Agent各有分工，合作完成一个大任务"，CrewAI的Role/Task/Crew模型比较直观。

我的选择标准：简单Agent用ADK（快），复杂工作流用LangGraph（灵活），多角色协作用CrewAI（语义清晰）。

不过有一点，ADK目前版本（1.0.0）的文档还不够全。有些高级用法得翻源码。社区也在起步阶段，Stack Overflow上相关问答不多。遇到问题主要靠GitHub Issues。

几个补充

ADK除了Python，还有Java和Go的SDK。Java版本可以直接和Spring Boot集成。如果你是Java技术栈，可以看google/adk-java这个仓库。

还有个 A2A（Agent-to-Agent）协议。这个协议是Google提的，让不同框架构建的Agent能互相通信。ADK原生支持A2A。不过A2A目前还在早期，实际落地的案例不多。

还有一个实用的：ADK支持adk eval命令做评估。你可以写测试用例，批量跑Agent看回答质量。做正式项目的时候这个功能很有用，不用手动一条条测。

总结

Google ADK的定位很清楚：降低Agent开发门槛。它做到了——一个Python函数就是一个工具，一个Agent类就是一个智能体，内置了调试界面和MCP支持。

如果你之前没碰过Agent开发，ADK是个不错的起点。如果你已经在用LangGraph或CrewAI，ADK可以作为快速原型验证的工具。

项目地址：https://github.com/google/adk-python 文档：https://adk.dev API Key申请：https://aistudio.google.com/app/apikey