Google ADK：Google Agent 开发套件

为什么需要 Google ADK：Agent 工程化缺的「最后一公里」

传统 Agent 开发方式存在三个断层。第一，原型与生产割裂：多数框架（如早期 LangChain）在 notebook 里跑通 demo 容易，但上线后缺乏流量治理、灰度发布、成本追踪手段，需要团队额外搭一套基础设施。第二，多 Agent 协作复杂度失控：当一个任务需要「规划 → 检索 → 工具调用 → 校验」多个子 Agent 协同（如 DeepMind 的 A2A 协议场景）时，手工用代码管理 Agent 间消息传递极易出错，且无法可视化排查卡点。第三，可观测性缺失：Agent 的「思考轨迹」（每一次模型调用、工具调用、中间状态）对调试至关重要，但通用日志框架难以结构化记录这种有向图执行过程。

Google ADK 的解决方案是「全生命周期覆盖」：开发阶段用 Python 装饰器（@agent）快速定义 Agent 与工具；调试阶段用官方可视化 UI（ADK UI）实时查看 Agent 执行轨迹；部署阶段可一键发布到 Vertex AI Agent Engine 获得托管基础设施，或导出为 Docker 镜像自托管。它在设计上强调「生产优先」——session 负责有状态对话管理，event 负责结构化追踪每次模型/工具调用，callback 提供流量拦截点（如限流、审计、内容审核），这些机制在社区框架中通常需要二次开发。

与 LangGraph（图状态机范式）和 AutoGen（多 Agent 对话范式）相比，ADK 的核心气质差异是「Google 官方背书 + 深度云集成」：它内置 Vertex AI 上的 Gemini 路由、函数调用 schema 自动生成、企业级 IAM 鉴权链路，如果你已经使用 Google Cloud 或 Gemini API，ADK 是学习成本最低的选择。

安装与环境配置：3 步就绪

步骤一·安装 Python 环境。Google ADK 要求 Python 3.10 及以上版本（官方推荐 3.10–3.13），建议使用 pyenv 或 conda 管理版本以避免污染系统环境。

步骤二·安装 google-adk 包。从 PyPI 安装核心库 google-adk，它自带默认的 Gemini 模型客户端；若需对接非 Google 模型（如 Anthropic、OpenAI），需同步安装 google-adk[litellm] 扩展以启用 LiteLLM 兼容层。

步骤三·验证安装。通过 Python 导入测试确认安装成功，并检查版本号。

补充配置：若使用 Google 模型，需设置 API 凭据——可用环境变量 GEMINI_API_KEY（Gemini Developer API）或通过 vertexai.init() 走 Vertex AI 企业的 OAuth 凭据。本地开发阶段建议直接用 Gemini API Key 快速验证，生产再切换 Vertex AI。

python --version   # 需要 3.10+，若版本过低先升级 pip install google-adk                       # 核心安装pip install "google-adk[litellm]"            # 可选：接入非 Google 模型pip install google-adk[dev]                  # 可选：安装 ADK UI 开发依赖 python -c "import google.adk; print(google.adk.__version__)"# 输出示例：1.2.0

export GEMINI_API_KEY="你的_API_KEY"

快速上手：10 分钟跑通第一个 Agent

最小可用流程的思路：用 @agent 装饰器把一个普通 Python 函数升级为 Agent，给它挂一个工具函数，然后用官方 ADK UI 或命令行脚本与它对话。无需手写消息循环或状态管理——框架替你处理。

操作步骤如下：

1. 创建项目目录：新建 my_agent.py，存放 Agent 定义。

2. 定义工具函数：写一个普通 Python 函数（如获取时间的 get_weather），用 @tool 装饰器标记，函数 docstring 会被自动转为模型可读的工具描述。

3. 定义 Agent：用 @agent 装饰器创建 Agent 实例，通过 model 参数指定 Gemini 模型（如 gemini-2.0-flash），通过 tools 参数挂载工具列表。

4. 启动交互：运行 adk run my_agent.py 启动命令行对话（该命令由 google-adk CLI 提供），或运行 adk ui my_agent.py 启动可视化调试界面。

结果说明：在 adk run 中输入问题时，CLI 会打印每一步的 Event 流转——你可以看到模型先解析用户意图、生成工具调用参数、执行 get_weather、再组织最终回复。在 adk ui 中，点击对话条目可展开完整的「模型调用 → 工具调用 → 响应生成」时间线，这是调试多步任务的核心手段。

进阶技巧：当 Agent 需要多轮工具协作（如「查询天气后再推荐穿衣」），直接在 instruction 中描述协作逻辑，模型会自动规划多步调用，无需手工编排。

# my_agent.pyfrom google.adk.agents import agentfrom google.adk.tools import tool @tooldef get_weather(location: str) -> str:    """获取指定城市的天气（模拟）。        Args:        location: 城市名，如 "北京"。    """    # 真实场景中此处调用天气 API    return f"{location} 当前晴，气温 25℃，湿度 40%" @agent(    model="gemini-2.0-flash",           # 模型标识    tools=[get_weather],                # 挂载工具    instruction="你是一个天气助手，用中文简洁回答。",)weather_agent = agent  # 导出的 Agent 变量，供 CLI 发现

# 终端运行（ADK CLI 会自动发现上述 weather_agent）adk run my_agent.py# 输入 "北京天气怎么样？" 观察模型调用 get_weather 工具的过程 # 启动可视化调试界面（浏览器打开 http://localhost:8000）adk ui my_agent.py

核心能力详解：5 大支柱

支柱一·多 Agent 编排（Workflow）。ADK 用有向图（DAG）管理多个 Agent 的协作关系，支持两种最常见模式——顺序流水线（SequentialAgent，如上一步清洗数据、下一步做分析）和路由分发（LoopAgent 或自定义 Router，根据意图把任务分发给不同子 Agent）。子 Agent 之间通过 Event 传递结构化消息（含文本、工具调用记录、中间状态），比裸函数调用多了一层可追踪性。官方推荐的典型架构是「主管 Agent + 专家子 Agent」：主管负责拆解任务，专家负责执行具体领域操作。

支柱二·工具调用与 MCP 集成。ADK 的 @tool 装饰器自动从函数签名与 docstring 生成 Gemini 所需的 Function Calling Schema（包含参数类型、必填项、描述），省去手写 JSON Schema 的繁琐。除了 Python 函数，ADK 原生支持接入 Model Context Protocol（MCP）服务器——用 mcp_toolset 把远程 MCP 工具（如 GitHub 操作、数据库查询）直接挂载为本地工具，这是它与只支持本地函数的框架的关键差异。

支柱三·Session 会话管理。Session 是 ADK 的有状态会话载体，存储对话历史、用户状态与 Agent 内部状态。默认支持内存 Session（开发用）、文件持久化 Session（跨重启保活）、以及通过扩展对接 Firestore 等外部存储。多轮对话中，模型自动从 Session 读取上下文，开发者无需手动拼接历史消息。

支柱四·可观测性（Events + Callbacks）。每次模型调用、工具执行都会生成结构化 Event，包含时间戳、调用方、输入输出、token 消耗。Callback 机制提供 before_model_call、after_tool_call、before_agent_end 等钩子，用于实现日志记录、流量限流、内容审核。生产环境可接入 OpenTelemetry 导出到 Cloud Logging 或自建监控，这是社区框架普遍薄弱而 ADK 默认内置的能力。

支柱五·模型无关与云集成。通过 LiteLLM 兼容层，同一个 Agent 代码可切换 100+ 模型（Gemini、GPT、Claude、开源模型等），仅需改 model 参数的标识符。若使用 Vertex AI，还能获得 Google Cloud 的 IAM 鉴权、VPC 网络控制、审核日志等企业级能力，模型路由自动走 Private Service Connect，不经过公网。

生产部署与监控：从上线到运维

部署方式一·Vertex AI Agent Engine（托管）。官方推荐的零运维部署路径：将本地 Agent 代码打包（要求代码与依赖可序列化），通过 SDK 上传并创建 AgentEngine 实例。Agent Engine 自动处理流量负载均衡、故障转移、自动扩缩容，并提供内置的对话日志与指标面板。适合已有 Google Cloud 基础设施、需要 SLA 保障的企业用户。部署仅需两次 API 调用（上传代码包 → 创建实例），与本地代码完全一致，无需改 Agent 定义。

部署方式二·Docker 自托管。对于多云或本地部署需求，ADK 提供 adk serve 命令启动 HTTP 服务（基于 FastAPI），暴露 /generate 等推理端点，可导出 Dockerfile 后用任意容器平台（GKE、ECS、K8s）托管。这种方式适合需要完全掌控基础设施、或对接自建网关的团队；官方提供带 gRPC 与 REST 双协议的服务模板。

可观测性。生产环境务必开启三层监控：第一层是框架日志（print 级别的 Event 追踪），用环境变量 ADK_LOG_LEVEL=INFO 控制；第二层是结构化指标，ADK 自动上报每次请求的 token 消耗、工具调用次数、延迟分布，导出到 Cloud Monitoring 或 Prometheus；第三层是会话级审计，通过 Callback 把每次用户输入与模型输出写入审计存储（如 BigQuery），满足合规要求。

<p class=“para-label“>避坑清单：</p><ul class=”dash-list”><li>坑 1：ADK 包名是 google-adk，但 Python 导入名是 google.adk——用 import adk 会报 ModuleNotFoundError；也注意与同名的 adk 其他第三方包区分，安装时务必指定 google-adk。</li><li>坑 2：@tool 装饰的函数必须写完整 docstring 且声明参数类型，否则框架无法生成正确的函数调用 Schema，模型会频繁传错参数——这是工具调用失败的头号原因。</li><li>坑 3：adk ui 默认监听 8000 端口，与本地已运行的 Jupyter/Django 等冲突时，用 --port 参数换端口，否则启动即报错。</li><li>坑 4：Python 3.13 在部分 Linux 发行版上有依赖编译问题（如 pydantic-core），官方推荐 3.10–3.12 生产使用，遇诡异报错先检查 Python 版本。</li><li>坑 5：生产环境切 Vertex AI 后，若本机用 GEMINI_API_KEY 调试，容易忘记在服务代码里初始化 vertexai.init()——结果部署后模型调用全部 401，需在 CI 里加环境检测。</li></ul>

版本迭代

Google ADK 于 2025 年 4 月在 Cloud Next '25 发布 0.1 版本，此后以月级频率迭代：5 月发布 0.2 带来 MCP 工具支持，7 月发布 1.0 稳定版确立 API 基线，随后通过 1.1/1.2 持续强化生产特性（会话持久化、模型路由、可观测性），截至 2025 年 12 月最新正式版为 1.2.x。整体演进主线是「从原型框架走向生产级 Agent 运行时」。

AI 应用场景

常见误区

面试题