Demystifying AI Agents with Turtle & Gemma

刚刚在 Dev.to 热门榜上看到一篇文章，标题是「Demystifying AI Agents with Turtle & Gemma」，作者是 bebechien。36 个 reactions，3 分钟阅读量，在技术区算是相当不错的成绩。这个标题引起了我的兴趣——Turtle 和 Gemma，听起来像是两个实际存在的项目，但又不像是 Google 官方发布的产品名称。花时间研究了一下，发现这个主题背后涉及 Google 当前的 Agent 开发工具链和开源模型战略，信息量不小，值得认真聊聊。

这篇文章的写作思路是：先把 Turtle 和 Gemma 是什么搞清楚，再把它们放在一起看——它们组合起来代表了什么趋势，以及作为一个普通开发者，要不要跟进。

Turtle 是什么？

先说 Turtle。我在 Google 官方文档和 Codelabs 里找了一圈，没有找到任何叫"Turtle"的产品或项目。但结合 Dev.to 文章的上下文和 Google ADK 的文档结构，Turtle 最有可能是 ADK（Agent Development Kit）的示例项目名称，或者是一种命名约定的代表。

ADK 是 Google 在 2024 年末推出的开源 Agent 开发框架，支持 Python、TypeScript、Go、Java、Kotlin 五种语言。官方口号是"Build production agents, not prototypes"——意思很明确：不是给你写着玩的，是让你真正用到生产环境里的。

ADK 的核心设计哲学是什么？我从官方文档里提炼出三条：

1. 代码优先（Code-first）：不同于一些纯配置文件驱动的框架，ADK 鼓励你用代码定义 Agent 的行为。这意味着你可以把 Agent 逻辑放在版本控制系统里，可以做 Code Review，可以写测试。

2. 从简单到复杂，渐进式扩展：官方文档里有一个清晰的演进路径——从单 Agent 开始，逐步加入 Tool、Workflow、多 Agent 协作。没有硬性要求你一开始就设计一个复杂的系统。

3. 本地优先，但可以_scale to cloud：ADK 提供了本地开发工具（CLI 和 Web UI），同时支持一键部署到 Google Cloud（Cloud Run、Agent Runtime、GKE）。但如果你不想用 Google Cloud，自己架设也可以。

ADK 的核心概念

理解 ADK，需要先搞清楚几个基本概念：

Agent：ADK 中的核心执行单元。一个 Agent 由三个部分组成：LLM（底层的语言模型）、Instruction（定义它的行为）、Tools（它能调用的外部能力）。你可以把 Agent 理解为一个"能思考、能行动"的单元。

Runner：管理 Agent 执行流程的引擎。它负责接收用户输入、管理上下文、处理事件、调用后端服务。Runner 是 ADK 的"操作系统"，但不是代码，是框架提供的基础设施。

Session & State：Session 管理单次对话的上下文，包括历史 Events 和工作内存 State。你可以把它理解为"Agent 的短期记忆"。如果要跨 session 记住用户信息，ADK 提供了 Memory 的集成点。

Tools：给 Agent 超出了"对话"之外的能力。ADK 支持自定义函数（FunctionTool）、把其他 Agent 当工具用（AgentTool）、内置代码执行、搜索等。Tool 的设计是 ADK 扩展性的核心。

Artifacts：这是 ADK 2.0 引入的功能，允许 Agent 创建和持久化文件（二进制数据，如图片、PDF、生成的报告）。Artifact 存在于 session 或 user 级别，超出了对话生命周期的限制。

Callbacks：在 Agent 执行过程中的特定钩子注入自定义逻辑。Callbacks 可以用来做日志、监控、修改行为，而不需要改动核心 Agent 代码。

最小可运行的 ADK Agent

ADK 的官方文档给出了一个最简示例：

# agent.py
from google.adk import Agent

root_agent = Agent(
    name="my_first_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant. Greet the user warmly.",
)

# __init__.py
# 空文件，标记目录为 Python 包

# .env
GOOGLE_API_KEY=your_api_key_here
GOOGLE_CLOUD_PROJECT=your_project_id
GOOGLE_CLOUD_LOCATION=us-central1

安装和运行：

# 安装 ADK
pip install google-adk

# 运行（CLI 交互模式）
adk run path/to/my_agent

# 或者 Web UI 模式
adk web path/to/agents_dir

就这么多。你不需要写任何配置文件，不需要懂 Kubernetes，不需要配置复杂的 CI/CD。一个 Python 文件，一个 API key，就能跑起来。

ADK 2.0 的重要更新

ADK 在 2025 年初发布了 2.0 版本，引入了几个重大变化：

1. Workflow Runtime：基于图的执行引擎，用于组合确定性的执行流。支持路由、扇出/扇入、循环、重试、状态管理、动态节点、人在回路（human-in-the-loop）、嵌套 workflow。这是 ADK 和其他 Agent 框架的核心差异——它把"确定性代码"和"AI 推理"编织在一起，而不是把所有事情都交给 LLM 决定。

2. Task API：结构化的 Agent 间委托机制，支持多轮任务模式、单轮控制输出、混合委托模式、人在回路、Task Agent 作为 workflow 节点。Task API 的引入让 multi-agent 协作变得更加结构化和可预测。

3. Breaking Changes from 1.x：ADK 2.0 的 agent API、event model、session schema 都有变化。官方说 2.0 session 可以被 1.28+ 读取（额外字段会被忽略），但 1.x 的 session 无法被 2.0 读取。如果你在用旧版本，升级需要注意。

# ADK 2.0 的 workflow 示例
from google.adk import Agent, Workflow

generate_fruit_agent = Agent(
    name="generate_fruit_agent",
    instruction="Return the name of a random fruit. Return only the name.",
)

generate_benefit_agent = Agent(
    name="generate_benefit_agent",
    instruction="Tell me a health benefit about the specified fruit.",
)

root_agent = Workflow(
    name="root_agent",
    edges=[("START", generate_fruit_agent, generate_benefit_agent)],
)

这段代码定义了一个两阶段的 workflow：先由 generate_fruit_agent 生成水果名称，然后传递给 generate_benefit_agent 补充健康信息。edges 里的 ("START", A, B) 表示 START -> A -> B 的执行顺序。这是一个确定性的执行路径，不像纯 prompt 方式那样依赖 LLM 的"心情"。

Gemma 是什么？

说完 ADK，再来看 Gemma。

Gemma 是 Google DeepMind 在 2024 年 2 月推出的一系列开源语言模型。名字来自拉丁语"gemmatus"，意思是"装饰宝石"——和 Gemini 共享同一个词根，但定位完全不同。

Gemma 的核心设计目标是让强大的语言模型能在消费级硬件上运行。 Gemma 2B 可以跑在 MacBook Pro 上，Gemma 7B 可以跑在单张 RTX 3090 上，Gemma 27B 可以跑在双卡或者高端消费级 GPU 上。这和 Gemini"追求最强性能"的目标有本质区别——Gemma 追求的是效率和可及性。

Gemma 家族的发展脉络

Gemma 最初发布时包含三个规格：2B、7B、27B，覆盖不同体量的需求。到了 Gemma 4，已经是完全不同的量级。

根据 Google Developers Blog 的描述，Gemma 4 的定位是"state-of-the-art open models designed for on-device agentic workflows"——专为设备端 Agent 工作流设计的最先进开源模型。

Gemma 4 的关键改进包括：

1. Multi-step Planning：Gemma 4 内置了链式推理能力，能够把复杂任务分解成多个子步骤逐步完成。这对 Agent 场景至关重要——你不会希望 Agent 一次性生成一个超长的回复，而是希望它分步执行，每步都能观察结果、调整策略。

2. 140+ 语言支持：覆盖全球主流语言，方便构建多语言 Agent 应用。

3. Function Calling 内置支持：这是 Agent 能力的关键。Function Calling 允许模型生成结构化的工具调用，而不是只输出文本。例如，当用户说"帮我查一下北京的天气"，Agent 可以生成一个 get_weather(location="Beijing") 的调用，而不是只输出一句"北京今天天气晴朗，温度 22 度"。

但 Google 官方也坦承了 Gemma 的局限："Gemma's built-in function calling capabilities are limited"。这个限制主要来自于模型体量——7B 以下的小模型在复杂推理任务上的表现，不如 27B 以上的版本。所以如果你要做复杂的 multi-tool orchestration，可能需要用 Gemma 27B，或者直接选择 Gemini。

4. 设备端优化：通过 LiteRT-LM（Google 的设备端推理引擎）优化，Gemma 可以在手机、边缘设备上运行 Agent 工作流。这意味着你可以构建完全离线、数据不离本地的 Agent 应用——这对医疗、法律、金融等敏感行业非常有价值。

Gemma 的使用场景

Gemma 适合哪些场景？我总结了三个主要方向：

1. 本地推理和隐私保护：当你的数据不能离开本地，或者你有严格的延迟要求（不能走云端 API）时，Gemma 是最现实的选择。比如在医院的本地机器上跑一个诊断辅助 Agent，在工厂的边缘设备上跑一个质量检测 Agent。

2. 低成本实验：Gemma 是开源的，可以免费使用。当你想快速验证一个想法、或者做内部实验时，不需要花钱调用 API。用 transformers 或者 vLLM 加载到本地机器上就行。

3. 嵌入式和移动端：通过 LiteRT 优化，Gemma 可以跑在手机和嵌入式设备上。这是 Gemini 做不到的——后者需要云端 API 调用。

Gemma vs Gemini：不是替代，是互补

很多人会问：既然 Gemma 能力不如 Gemini，为什么还要关注它？

答案很简单：场景不同。Gemini 是 Google 最强的模型，适合高复杂度任务、大上下文、顶级推理能力。但 Gemini 需要云端 API，数据需要离开你的机器，成本也更高。

Gemma 的价值在于：免费、本地、可定制。

维度	Gemma	Gemini
体量	2B-27B 参数	更大（从 1.5B 到更大）
部署	本地/设备端	云端为主
成本	开源免费	需要 Google Cloud 配额
适用场景	低延迟、数据隐私、离线	高复杂度任务、需要大上下文
Function Calling	有限（尤其是小模型）	强大

如果你在做一个数据敏感的 Agent（比如医疗病历分析、法律合同审查），你不可能把病患数据传给 Google 的服务器。这种情况下，Gemma 的本地运行能力是刚需。

如果你在做一个需要极低延迟的交互（比如实时语音翻译、嵌入式设备控制），每增加一次网络往返都会破坏体验。本地模型是唯一选择。

但如果你在做复杂推理（比如多步骤的代码重构、深度研究助理），Gemma 2B/7B 的能力可能不够，你需要 Gemini 的规模。

Turtle + Gemma：本地跑 Agent 的最小路径

把 Turtle 和 Gemma 放在一起，实际上在说一件事：如何用 ADK + Gemma 在本地构建一个 AI Agent。

Google Cloud 的官方文档里专门有一篇「Run agents with Gemma 4 models on Cloud Run」，讲的就是这个组合。但如果你想完全不依赖云服务，在本地跑，流程大概是：

第一步：安装 ADK

pip install google-adk

第二步：准备 Gemma 模型

有两种方式：

方式 A：通过 vLLM 服务 Gemma 作为 OpenAI API 兼容 endpoint：

# 安装 vLLM
pip install vllm

# 启动 vLLM 服务 Gemma
python -m vllm.entrypoints.openai.api_server \
    --model google/gemma-4-27b \
    --host 0.0.0.0 \
    --port 8000

方式 B：通过 Hugging Face transformers 直接加载：

from transformers import AutoTokenizer, AutoModelForCausalLM

model_name = "google/gemma-4-27b"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    device_map="auto",  # 自动分配到可用 GPU
)

第三步：编写 Agent 代码

from google.adk import Agent

# 连接到本地 vLLM 服务（OpenAI API 兼容）
turtle_agent = Agent(
    name="turtle_explorer",
    model="openai/gemma-4-27b",  # vLLM 的模型名格式
    instruction="""You are Turtle, a curious exploration agent.
    When given a topic, break it down into research steps,
    use available tools to gather information, and provide
    a comprehensive summary with sources.

    Your approach:
    1. Identify the key aspects of the topic
    2. Break down the research into manageable steps
    3. Use available tools to gather information
    4. Synthesize findings into a coherent response""",
)

第四步：扩展 Tool 能力

光有对话能力不够，Agent 需要能"做事"。ADK 支持给 Agent 添加工具：

from google.adk import Agent
from google.adk.tools import google_search, code_execution

turtle_agent = Agent(
    name="turtle_researcher",
    model="openai/gemma-4-27b",
    instruction="""You are Turtle, a research-focused agent.
    You help users explore topics thoroughly by breaking down
    complex questions into manageable research steps.""",
    tools=[
        google_search,  # 内置搜索工具
        code_execution,  # 内置代码执行工具
    ],
)

第五步：运行和调试

# CLI 交互模式
adk run turtle_researcher

# Web UI 模式（推荐新手使用）
adk web turtle_researcher

Web UI 会启动一个本地服务器，打开浏览器就能看到 Agent 的运行界面，可以单步调试、查看状态、检查 tool 调用。

ADK 的 Graph Workflows：确定性执行的意义

ADK 2.0 引入的 Graph Workflows 值得单独说说，因为它代表了 Agent 框架设计的一个重要方向。

传统的 Agent 实现（比如 LangChain 的早期版本）主要依赖 LLM 的推理能力来决定下一步做什么。这种方式很灵活，但不可预测——同一个输入，可能今天走这条路径，明天走那条路径。在 demo 环境下这不是问题，但在生产环境里，你需要可重复的行为。

ADK 的 Graph Workflows 引入了确定性。你可以在 graph 里定义明确的执行路径，同时保留 AI 推理的适应性。官方文档的说法是："Weave deterministic code with adaptive AI reasoning"——把确定性代码和自适应 AI 推理编织在一起。

Graph 的结构

ADK 的 graph 由节点（Nodes）和边（Edges）组成。节点可以是：
- LLM Agent：做推理决策
- Workflow Agent：编排子 workflow
- Code：执行确定性代码
- Condition：条件分支

边定义了节点之间的数据流和执行顺序。

from google.adk import Agent, Workflow

# 研究 Agent：负责搜集信息
research_agent = Agent(
    name="research_agent",
    instruction="Search for relevant academic papers and articles about the given topic. Return a list of sources with brief descriptions.",
)

# 分析 Agent：负责理解和总结
analyze_agent = Agent(
    name="analyze_agent",
    instruction="Read through the research findings and provide a critical analysis. Identify key themes, contradictions, and gaps.",
)

# 写作 Agent：负责输出
write_agent = Agent(
    name="write_agent",
    instruction="Based on the research and analysis, write a clear, informative report. Structure it with an introduction, body, and conclusion.",
)

# 定义 workflow
research_pipeline = Workflow(
    name="research_pipeline",
    edges=[
        ("START", research_agent, analyze_agent),
        (analyze_agent, write_agent, "END"),
    ],
)

在这个例子里，执行顺序是固定的：START -> research_agent -> analyze_agent -> write_agent -> END。但每个 Agent 内部的行为仍然由 LLM 驱动——你会得到一致的流程，但 Agent 的具体输出会因输入而异。

什么时候用 Workflow？

ADK 官方建议在以下情况下考虑从单 Agent 扩展到 Workflow：

1. Instruction Following 性能下降：当你发现一个 Agent 无法可靠地完成所有指令，或者完成的质量/速度不稳定时。这通常发生在指令集过长或过复杂的情况下。

2. Context 超出限制：Agent 任务所需的数据量超过了模型的 context window。Workflow 可以把任务拆分，让每个 Agent 只处理一个子问题。

3. 代码模块化：当 Agent 代码变得难以管理时。Workflow 允许你把不同能力的代码拆分成独立的 Agent，单独开发和测试。

4. 混合确定性和非确定性任务：当你的应用需要 AI 推理和确定性代码交替执行时。Graph Workflow 可以自然地表达这种交替，而不需要在 prompt 里写一堆"如果...否则..."。

我的看法：这个趋势值不值得跟？

看完这些资料之后，我有一个比较强的感受：Google 正在把 Agent 开发平民化。

Turtle 作为示例项目，传达的信息是：不需要你是 AI 专家，也能跑起来一个 Agent。ADK 的设计哲学就是这样——先让你跑，再让你扩展。Python 3.11+ 就能跑，pip install 就能用，CLI 工具开箱即食。

Gemma 的定位则更明确：开源+本地化。Google 在说：你不用非得用我们的云服务，也能跑强大的 AI 应用。Gemma 2B 可以跑在笔记本上，Gemma 27B 可以跑在单卡 GPU 上，这个门槛比以前低了很多。

但也有需要注意的地方：

1. Gemma 的 Agent 能力有上限

Google 官方博客里坦承"Gemma's built-in function calling capabilities are limited"。如果你要做复杂的 multi-tool orchestration（一个 Agent 调用多个外部工具协同工作），Gemma 的小模型版本可能会遇到瓶颈。解决方案：用更大的模型（Gemma 27B），或者选择 Gemini。

2. ADK 的生态还在成熟中

ADK 2.0 刚发布不久，从 1.x 到 2.0 有 breaking changes。这意味着：
- 社区还在建设中，Stack Overflow 上的 ADK 答案可能已经过时
- 第三方工具和插件的兼容性需要验证
- 如果你正在用 1.x 版本，升级需要谨慎测试

3. "Turtle" 这个名字本身就是提示

Turtle 在英文里是"慢"的意思。Google 把示例命名为 Turtle，可能也在暗示：用这套工具构建 Agent，不要急，先把基础打牢。Turtle 的速度不是最快的，但它稳定、持久。

4. 本地 Agent 不是银弹

虽然 Gemma 可以本地运行，但本地 GPU 的算力有限。如果你的 Agent 需要处理大量并发请求，或者模型需要频繁微调，云端方案仍然更合适。本地优先，本地够用才选本地。

动手试试：本地跑一个最小 Agent

如果你想亲自体验一下，这是我能找到的最简路径：

前置条件：Python 3.11+，8GB RAM，一个 OpenAI API 兼容的模型 endpoint（可以是本地 vLLM、Gemma、或任何第三方模型）

# 1. 安装 ADK
pip install google-adk

# 2. 创建项目目录
mkdir my_turtle_agent && cd my_turtle_agent

# 3. 创建 agent.py
cat > agent.py << 'EOF'
from google.adk import Agent

turtle = Agent(
    name="turtle_agent",
    model="gemini-2.0-flash",  # 或其他可用模型
    instruction="""You are Turtle. You respond with short, helpful answers.
    When a user asks a question, provide a direct answer followed by
    a brief explanation. Keep responses concise but informative."""
)

if __name__ == "__main__":
    from google.adk.run import run_agent
    run_agent(turtle)
EOF

# 4. 运行（确保设置了 GOOGLE_API_KEY 环境变量）
export GOOGLE_API_KEY=your_key_here
adk run agent.py

# 5. 或者用 Web UI（更适合调试）
adk web agent.py

如果上面这个能跑起来，你可以尝试加入工具：

from google.adk import Agent
from google.adk.tools import google_search

turtle_with_search = Agent(
    name="turtle_researcher",
    model="gemini-2.0-flash",
    instruction="""You are Turtle, a research assistant. 
    Use the google_search tool to find up-to-date information
    when answering factual questions. Always cite your sources.""",
    tools=[google_search],
)

总结

Turtle + Gemma 这个组合，本质上是 Google 给你的一套低成本 Agent 开发入门方案：用 ADK 作为框架，用 Gemma 作为推理引擎，用 Turtle（作为示例名称）演示基本模式。

适合想入门 Agent 开发、但不想一开始就被云服务绑死的开发者。你可以在本地机器上跑通整个流程，理解 Agent 的基本概念，然后再决定要不要 scale up 到云端。

但要记住：Turtle 是起步，Gemma 是工具，ADK 是框架。真正让 Agent 有价值的，是你用它解决什么问题。工具会变，框架会更新，但能用技术解决真实需求的思路不会过时。

如果你对某个具体场景（比如客服机器人、知识库助手、代码辅助工具）有兴趣，可以继续深挖 ADK 的文档和 Codelabs。Google 的「Building AI Agents with ADK」系列是目前最系统的学习资源。

参考资料：Google Agent Development Kit 官方文档（https://google.github.io/adk-docs/）、Google Developers Blog「Beyond the Chatbot: Agentic AI with Gemma」、Google Developers Blog「Bring state-of-the-art agentic skills to the edge with Gemma 4」、Google Cloud「Run agents with Gemma 4 models on Cloud Run」、GitHub google/adk-python

📑 目录