Google ADK 入门：Agent、Tools、Session 与 Graph Workflows

Google Agent Development Kit 官方文档

AI 参与说明（Agent：Codex）：本文由 Codex 根据 Google ADK 官方文档、Context7 检索材料与 PyPI 包元数据协助调研、撰写和校验，整理日期为 2026-10-09。Python 示例固定使用 google-adk==2.11.0；具体语言的功能支持以各官方页面为准。运行记录：模型 gpt-6.1-sol，reasoning effort ultra，执行入口 Codex Desktop，提供方 openai，运行记录中的 CLI 版本 0.162.0-alpha.17.2（不代表桌面 App 版本）。

基础设施边界补充（2026-10-09，Agent：Codex）：核对自托管、非 Google 模型、本地存储与可选 Google 服务，区分包依赖与在线服务依赖。运行记录：模型 gpt-6.1-sol，reasoning effort ultra，执行入口 Codex Desktop，提供方 openai，运行记录中的 CLI 版本 0.162.0-alpha.17.2（不代表桌面 App 版本）。

部署路径补充（2026-10-09，Agent：Codex）：将模型 API 与基础设施分别讨论，补充 Google 官方托管路径、Cloudflare Containers 的部署方向，以及 Workers 兼容性和持久化边界。本次依据官方文档核验，未实际部署到 Cloudflare 或 Google Cloud。运行记录：模型 gpt-6.1-sol，reasoning effort ultra，执行入口 Codex Desktop，提供方 openai，运行记录中的 CLI 版本 0.162.0-alpha.17.2（不代表桌面 App 版本）。

Google ADK 适合用代码开发能够调用工具、保留对话上下文并完成多步骤任务的 AI 应用。理解它时，先看一个问题：当模型决定“需要查资料或执行操作”之后，谁来运行代码、保存过程、接着调用模型，并让开发者检查发生了什么？ADK 把这些工作组织成一套框架。

ADK 提供什么

ADK is Google’s open-source framework for building, evaluating, and deploying AI agents. 官网提供 Python、TypeScript、Go、Java 和 Kotlin 入口，并将模型、工具、上下文管理与开发调试放在同一个开发体系中。ADK 首页

它的工程价值主要体现在三个地方：

• 把能力写成代码：定义 Agent 的模型、指令和 Tools，把查询、计算等操作接入已有系统。
• 把执行过程组织起来：由 Runner 驱动执行，用 Session、State 和 Events 管理上下文与过程；复杂任务可以拆成工作流或多个 Agent。
• 让过程可以检查和改进：用开发界面检查工具调用与状态变化，用 Evaluation 验证行为，再选择合适的部署环境。Technical Overview

例如一个售后助手，可以先理解问题，再通过 Tool 查询订单，读取结果后回答；当退款流程必须经过资格检查与人工批准时，可以把这些步骤写进明确的工作流。这里的业务场景是说明用途的例子，具体订单权限与退款规则仍由应用实现。

ADK 对 Gemini 的接入较直接，也提供其他模型的接入方式，例如 LiteLLM 和自定义模型适配。模型选择与部署位置可以分别决定，但切换模型时仍须核对工具调用、结构化输出和流式能力。Models for Agents LiteLLM

是否依赖 Google Cloud 或 Google 在线服务

ADK does not require Google Cloud infrastructure. 这里将模型 API 作为可替换的能力单独讨论；基础设施主要指执行服务、Session、Memory、文件存储与监控等。即使应用选择 Gemini，也不意味着这些基础设施必须使用 GCP。官方部署指南明确允许自行打包为容器，运行在支持容器的基础设施中，包括本地 Docker 或 Podman，以及不连接 Google Cloud 的环境。Deployment：Other Container-friendly Infrastructure

判断基础设施依赖时，需要分别看下面几层；具体服务实现与语言支持应按官方文档核对。

部署、存储和模型可以分别选。例如，应用服务器部署在 Cloudflare Containers，会话与文件保存到自行选择的存储，再调用兼容的模型 API，这种架构不需要 GCP。是否连接模型服务与是否依赖 Google 的托管基础设施，是两个不同的选型问题。Sessions Other Container-friendly Infrastructure

Google SDK package dependencies are not the same as Google service dependencies. google-adk==2.11.0 的基础 Python 安装包含 google-genai 与 google-auth，安装目录中出现 Google SDK 并不表示运行时必须连接 Google；实际外部请求仍取决于配置和执行路径。包的 optional extras 还提供其他集成依赖。固定版本包元数据

如果进一步要求完全离线，才需要提前准备依赖与模型权重，选择支持 Tool calling 的本地模型，并检查 Tools、Memory、Tracing 等是否访问外部服务。当前 ADK Web 的 usage telemetry 默认关闭、需主动启用；保留关闭状态即可避免这项可选外连。Ollama model choice Usage telemetry

本次在 ADK 2.11.0 下清空 Google 凭据并阻断 socket 连接，验证了 Agent 与 FunctionTool 构造、Tool 执行、一个不调用模型的本地 Agent 经 Runner 运行，以及内存 Session 的 State 和 Events 保存。这验证了本地执行框架的独立性；没有执行 Ollama 推理或完整离线部署。下文的温度转换示例选择了 gemini-flash-latest，实际对话需要模型 API，但不要求把应用部署到 GCP。

默认开发配置与 Google 官方部署路径

Local development defaults and production deployment choices are separate. ADK 没有要求所有应用采用同一种生产基础设施。以当前 Python adk web 为例，默认监听 127.0.0.1:8000，Session 保存到各 Agent 的 .adk/session.db，Artifacts 保存到 .adk/artifacts；运行开发界面不需要先创建 GCP 项目。这些默认值不能直接套到其他语言或生产部署。Web Interface defaults

如果“推荐”指官方提供了完整指南和部署工具的生产路径，主要有以下三种，另有通用容器部署路径。选择依据是需要多少托管能力与控制权，而不是安装 ADK 后自动绑定某种云服务。Deployment Options

Agent Runtime 路径的价值是减少 Agent 服务运行层面的工作。Google 还提供可选的 Sessions、Memory Bank、Code Execution，以及 Cloud Logging、Cloud Trace 和监控接入：分别覆盖会话上下文、长期记忆、隔离代码执行与运行过程检查。它们是可以选择和配置的托管服务，不能因应用使用了 ADK，就认为这些能力已经全部接通。Agent Runtime deployment Agent Platform services

Google 的 Agents CLI 还提供进一步的部署脚手架：可以配置 Google Cloud 资源、Terraform 与 CI/CD pipelines。它为生产环境准备提供了较完整的路径，但需要相应的 GCP 项目、计费与 IAM 权限。Agents CLI deployment

Cloud Run 路径更接近普通应用服务部署。官方明确推荐 Python 使用 adk deploy cloud_run，也提供自定义 FastAPI 与 Dockerfile 的方式；这份容器示例可以作为其他容器平台的起点。需要注意，当前该部署命令在未指定 Session / Artifact 服务 URI 时使用内存服务，实例回收后数据会丢失。因此，“托管计算与扩缩容”不等于“自动完成持久化”。Cloud Run deployment

在 Cloudflare 上运行 ADK

Cloudflare Containers is a viable deployment architecture for an ADK HTTP service; direct Workers compatibility needs separate verification. 对现有 Python ADK 应用，较直接的方向是把 ADK API server 或自定义 HTTP server 打包为 Linux 容器，放到 Cloudflare Containers，由 Workers 处理入口并通过 Durable Object 转发请求。这个判断来自 ADK 的通用容器部署能力与 Containers 的完整运行环境；本文没有执行真实云端部署，不能视为已通过 ADK 与 Cloudflare 的端到端验收。ADK container deployment Cloudflare Containers

下面是架构示意；模型提供方可以独立选择。

flowchart TB
    A[用户请求] --> B[Cloudflare Worker：入口、鉴权与路由]
    B --> C[Durable Object：控制 Container 生命周期]
    C --> D[Cloudflare Container：ADK HTTP server]
    D --> E[选择的模型 API 与业务 Tools]
    D --> F[持久化服务：Session、Memory 与 Artifacts]

Cloudflare 当前文档建议新应用采用 Durable Object Container API，通过 ctx.container 控制启动、停止与流量转发；已有应用可以继续使用 Container class。Containers 需要 Workers Paid plan，镜像按官方要求构建为 linux/amd64。Containers API Get started

后两条路径在本文中没有完成兼容测试。Workers 文档列出了 Python 包的支持条件和 Node.js API 的实现范围；ADK 的标准快速开始也不等于针对 Workers 的部署验收。Python Workers runtime Python packages Node.js compatibility ADK TypeScript Quickstart

持久化是 Containers 路径中必须单独设计的部分。默认容器磁盘是临时的，停止或休眠后不能把本地 SQLite 与文件 Artifacts 当作可靠的生产数据存储。ADK Python 的 DatabaseSessionService 支持 PostgreSQL、MySQL 等数据库，是可采用的外部 Session 存储路径。Container disk FAQ DatabaseSessionService

如果希望 Session 与 Artifacts 也使用 Cloudflare D1、Durable Objects 或 R2，需要实现相应的服务适配，例如让容器通过 HTTP 与 Worker 侧的 bindings 交互。ADK 不会自动把 D1 识别成一个本地 SQLite 文件，也不会自动把 R2 当作它的 Google Cloud Storage 实现。Connect to Workers and Bindings

对已有 ADK 项目，本文建议先评估 Containers 并完成以下验收：启动后 API 可访问、流式响应能够经过 Worker 返回、Container 重启后 Session 和 Artifacts 可恢复、重复请求不会重复执行有副作用的 Tool。这是部署选择与验收建议，不是已经完成的测试结果。如果主要目标是直接使用 Workers、Durable Objects 与 Cloudflare 原生状态管理，也可参考站内的 Cloudflare Agent 方案。

一次 Tool 调用怎样完成

The model proposes a tool call; application code performs the operation. 在 Python 中，把带类型标注的函数放进 tools，ADK 会将它包装成 FunctionTool，并根据函数名、参数及 docstring 生成模型可以理解的工具描述。Function tools

下面是一种常见的非流式交互顺序，用于理解各部分职责。Agent 在执行过程中持续产生 Events，Runner 负责协调处理；图中省略这些贯穿全过程的记录步骤，以及并发和流式细节。

flowchart TB
    A[用户输入请求] --> B[Runner 带上 Session 驱动 Agent]
    B --> C[Agent 向 Model 提供上下文和 Tools]
    C --> D[Model 请求调用 Tool]
    D --> E[Tool 执行函数并返回结果]
    E --> F[Agent 向 Model 提供 Tool 结果]
    F --> G[Model 生成答复]
    G --> H[Runner 输出答复]

Runner 协调执行与服务，Event 则记录过程中发生的事情。检查 Events 可以区分“模型没有选对 Tool”“参数生成错误”“Tool 本身返回错误”以及“结果被回答错误解释”等不同问题。Event Loop Events

Session、State 与 Memory 怎样分工

Session history and State provide conversational context; Memory is a separate cross-session capability. 一段对话的 Events 与工作数据通过 Session 和 State 管理，跨 Session 的检索则通过 MemoryService 接入。Sessions State Memory

可以把它们对应到同一个助手的三种需求：

具体保存多久、进程重启后能否恢复，由服务实现和配置决定。InMemorySessionService 适合临时实验；需要跨进程保存时，应选择持久存储。当前 Python adk web 的默认本地存储与自行编程时选择的服务也要分别看待。Session service implementations Web Interface

生成的文件与二进制内容还有独立的 Artifact 管理接口，例如报告或图片；它们不必全部塞进对话文本。Artifacts

ADK 2.0：把执行路径写清楚

ADK 2.0 introduces a graph-based Workflow Runtime. 官方 2.0 文档列出的支持语言是 Python、TypeScript 与 Go，不能由首页的五种语言入口推断所有语言都拥有同一组 2.0 功能。ADK 2.0

Graph Workflows 可以将 Agent、Tool 和普通函数组合成节点，再通过边指定执行顺序与分支。这让开发者能够把“必须先检查、再操作”的步骤直接写成程序结构；模型负责适合推理的部分，固定规则由代码执行。Graph-based agent workflows

例如一个资料整理任务，可以显式安排为下面的流程。图展示应用设计，不表示 ADK 内置了这些业务步骤。

flowchart TB
    A[用户提交主题] --> B[Agent 提取检索条件]
    B --> C[Tool 获取资料]
    C --> D[函数检查资料是否齐全]
    D -->|齐全| E[Agent 撰写摘要]
    D -->|缺少信息| F[请求补充输入]
    E --> G[输出结果]

选择组合方式时，先看流程是否必须遵守明确顺序：

• 单个 Agent 与 Tools：模型按请求选择操作，适合较短、相对灵活的任务。
• Graph Workflows：需要显式路径、分支与数据传递时使用。
• Dynamic workflows：控制流更适合用程序中的循环、条件或递归表达时使用。
• Collaborative workflows：任务需要协调多个专业 Agent 时使用。Graph workflows Dynamic workflows Collaborative workflows

工作流明确的是执行结构，模型节点的输出仍可能变化。固定路径不会自动保证答案正确；应继续验证资料、参数与最终结果。

旧教程常见的 SequentialAgent、ParallelAgent 与 LoopAgent 属于预置流程组合。阅读时要核对语言和版本；例如 TypeScript 2.0 已将这三个类标为 deprecated，但仍继续兼容。Python 1.x 升到 2.0 也要检查 Event schema 与自定义执行扩展等 breaking changes。ADK 2.0 compatibility

Python 最小示例：让 Agent 调用一个真实函数

下面采用 macOS / Linux shell、Python 3.10+ 和 google-adk==2.11.0。这个包版本是 2026-10-09 核验的 PyPI 版本；固定版本用于复现。真实对话需要 Gemini API key 和可访问的模型服务。PyPI Python Quickstart

在自己的练习目录执行：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "google-adk==2.11.0"
adk create temperature_agent

按 adk create 的提示选择 Gemini API 接入方式。项目包含 agent.py、__init__.py 与 .env；将 temperature_agent/agent.py 替换为：

from google.adk import Agent


def convert_temperature(celsius: float) -> dict[str, float]:
    """Convert a Celsius temperature to Fahrenheit.

    Args:
        celsius: Temperature in degrees Celsius.
    """
    return {
        "celsius": celsius,
        "fahrenheit": round(celsius * 9 / 5 + 32, 2),
    }


root_agent = Agent(
    name="temperature_agent",
    model="gemini-flash-latest",
    description="Converts Celsius temperatures to Fahrenheit.",
    instruction=(
        "Use convert_temperature for every temperature conversion. "
        "Ask for the Celsius value if it is missing. "
        "Report the tool result with clear units."
    ),
    tools=[convert_temperature],
)

root_agent 是 CLI 加载的入口。函数签名与 docstring 描述 Tool 的输入和用途，真正的温度转换则由 Python 执行。这个例子没有使用伪造的天气或实时数据。Python Quickstart Function tools

在 temperature_agent/.env 中填写自己的凭据，下面只是占位内容：

GOOGLE_API_KEY=YOUR_GEMINI_API_KEY

将 .env 和 .venv/ 加入练习项目的 Git 忽略规则。gemini-flash-latest 沿用官方入门示例，是会随时间变化的模型选择；需要稳定对比时，应换成账户可用的明确模型版本。区域端点也须核对该模型选择是否受支持。Gemini model configuration

回到包含 temperature_agent/ 的父目录，任选一个入口：

# 终端交互
adk run temperature_agent

# 浏览器开发界面；与上面的命令分开启动
adk web --port 8000

浏览器打开 http://localhost:8000，选择 temperature_agent，输入：

请把 25 摄氏度转换为华氏度。

验收时应在 Event history 中看到 convert_temperature 调用，参数为 celsius=25，Tool 结果包含 fahrenheit=77.0，答复中的数值与单位一致。再尝试 0 与 -40，预期分别为 32.0 与 -40.0；缺少数值时，应请求补充。这里只给出了预期行为，模型是否正确选择 Tool 仍须通过真实对话检查。

也可以先验证确定性部分：在父目录执行以下命令，不需要 API key。

python - <<'PY'
from temperature_agent.agent import convert_temperature, root_agent

assert root_agent.name == "temperature_agent"
for celsius, fahrenheit in [(25, 77.0), (0, 32.0), (-40, -40.0)]:
    result = convert_temperature(celsius)
    assert result["fahrenheit"] == fahrenheit
    print(result)
PY

本次在 Python 3.13.11 与 ADK 2.11.0 下验证了 Agent 构造、FunctionTool 参数描述生成和上述三个转换结果；没有执行真实 Gemini 请求。adk web 只用于开发与调试，生产接入须另行配置 API 服务、界面与访问控制。Web Interface

从最小示例扩展到应用

Tool 的函数体可以逐步换成数据库查询或业务 API 调用。外部能力还可以通过 MCP 接入；远程 Agent 之间的协作可参考 A2A。MCP 主要解决工具接入，A2A 主要解决 Agent 互操作，功能和稳定性要按各语言的具体指南核对。MCP tools Introduction to A2A

当工具增多或任务变长时，建议按下面的顺序推进。这是本文的工程建议：

1. 先验证一个 Tool：明确输入、输出与错误情况，检查真实结果，再让模型调用。
2. 检查一次完整交互：确认 Events 中的 Tool、参数与最终答复符合预期。
3. 再固定必要流程：必须遵守的顺序与检查写进 Graph Workflows，把确实需要推理的步骤交给 Agent。
4. 保存可重复的场景：当前官方 Evaluation 页面以 Python 为支持入口，可检查工具使用轨迹与最终答复；不要把一次成功演示当作所有场景都已通过。Evaluation
5. 选择部署方式：根据运行环境与语言选择容器部署、Cloud Run、GKE 或 Agent Runtime on Agent Platform，分别检查服务身份、会话存储与访问控制。Deployment Cloud Run

如果应用只需要一次输入、一次模型输出，可以先使用模型 API；当工具调用、上下文与多步骤执行开始占据大量应用代码时，再引入 ADK 更容易看到实际收益。这是使用范围的判断，不是性能测试结论。

关联阅读

• Agent 文档导航：继续查阅工作流、工具接入与测试方法。
• Agent 开发中的测试方法：Specification、Test Oracle 与验证证据：区分确定性检查与模型行为评估。