Skip to content

将现有智能体迁移到 ADK

本指南介绍如何使用 Agents CLI 和你的编码智能体将现有的智能体代码库迁移到 Agent Development Kit (ADK)。迁移到 ADK 可以让你在多种语言间标准化智能体架构，使用内置评估工具，并直接部署到 Google Cloud。

使用 Agents CLI 进行迁移

你可以使用 Agents CLI 来规划和执行迁移，而不必手动逐行重写状态对象、节点图和执行循环。

Agents CLI 会将 ADK 开发技能安装到编码智能体中，如 Antigravity、Claude Code、Cursor 和 Codex。当你在现有项目中打开编码智能体时，它可以：

  • 分析你当前的智能体结构、工具、状态和路由规则。
  • 将现有组件映射到原生 ADK 类和图工作流。
  • 提出带有权衡分析的架构方案。
  • 逐步转换工具、智能体定义和会话处理。
  • 生成评估数据集，以验证迁移前后的行为。

有关使用 Agents CLI 的更多信息，请参阅 Agents CLI 文档。

前提条件

在开始迁移之前，请确保已安装以下内容：

  • Python 3.11 或更高版本
  • uv 包管理器
  • 支持的编码智能体

将 Agents CLI 及其 ADK 技能安装到你的编码智能体中：

uvx google-agents-cli setup

验证安装：

agents-cli info

迁移工作流

按照以下流程将现有智能体迁移到 ADK：

  1. 在现有项目中打开编码智能体
  2. 头脑风暴迁移方案
  3. 将智能体模式映射到 ADK
  4. 带评估的代码转换
  5. 验证和评估

在现有项目中打开编码智能体

在现有智能体项目的根目录中打开终端或 IDE，并启动你的编码智能体。确认智能体已检测到 Agents CLI 安装的 ADK 技能。

头脑风暴迁移方案

请你的编码智能体检查当前代码库，并头脑风暴目标 ADK 架构。由于智能体已通过 Agents CLI 加载了 ADK 技能，它了解 ADK 状态管理、图工作流和编排模式。在编码智能体中使用类似以下的提示：

编码智能体提示
I want to migrate this existing agent codebase to Google Agent Development Kit (ADK).
Please inspect our current files, state schema, tools, and control flow.
Propose 2-3 target ADK architecture options with trade-offs, and recommend the cleanest approach.
Include an evaluation plan to verify behavior using agents-cli eval.

你的编码智能体会分析以下内容：

  • 执行流程： 单工具调用循环、确定性图工作流、动态路由器或多智能体团队。
  • 工具： 函数、参数签名、文档字符串和外部 API 调用。
  • 记忆和检索： 知识存储、向量搜索集成或对话记忆。
  • 状态： 跨轮次跟踪的变量、暂存区键和会话存储。
  • 目标类： 哪些 ADK 类（如 Agent 或 Workflow）最适合。
  • 评估策略： 如何将现有测试用例转换为评估数据集，以对迁移后的智能体进行基准测试。

审查提出的方案后，批准符合你需求的架构。

将智能体模式映射到 ADK

ADK 用声明式类和图工作流替代了自定义分发循环和状态处理器。在迁移过程中使用以下映射作为参考：

现有模式 ADK 等价物 描述
自定义工具 schema 或包装器 原生 Python 函数或 FunctionTool 带类型提示和文档字符串的普通 Python 函数。ADK 会自动推导工具声明。
自定义智能体循环或运行器 Agent 声明式智能体定义，指定模型、指令、工具和子智能体。
记忆和检索 BaseMemoryService 实现和检索工具 内置记忆服务（InMemoryMemoryService、VertexAiMemoryBankService、VertexAiRagMemoryService）以及用于会话和文档基础信息获取 (Grounding) 的检索工具。
状态字典或暂存区 通过 ToolContext 访问 session.state 可在工具、回调和智能体指令中访问的共享可变会话状态。
多智能体工作流和流水线 google.adk.workflow.Workflow 带有条件路由、循环和平行分支的显式图节点。
多智能体交接 Agent(sub_agents=[...]) 分层委托，协调者智能体委托给专门的子智能体。
远程智能体通信 A2A 协议 使用智能体对智能体标准通过 HTTP 进行智能体间通信。

带评估的代码转换

可靠的迁移是测试驱动的。你的编码智能体可以在生成新 ADK 代码的同时，设置评估数据集和测试套件，以验证迁移后的智能体产生的结果与原始实现一致。

  1. 设置评估测试用例： 让你的编码智能体将现有测试用例或记录的对话转换为 eval/ 下的评估用例。
  2. 移植工具和智能体逻辑： 用带类型的 Python 函数和 ADK Agent 或 Workflow 替换自定义分发循环和工具包装器。
# agent.py
from google.adk.agents import Agent
from google.adk.tools import ToolContext

def lookup_customer(customer_id: str) -> str:
    """检索客户的账户等级和状态。"""
    return "Tier: Premium, Status: Active"

def calculate_discount(amount: float, rate: float = 0.1) -> float:
    """计算交易的折扣总额。"""
    return amount * (1.0 - rate)

root_agent = Agent(
    name="customer_support_agent",
    model="gemini-flash-latest",
    instruction="Assist customers with account inquiries and discounts using your tools.",
    tools=[lookup_customer, calculate_discount],
)

验证和评估

运行评估套件，将迁移后的智能体与基线测试用例进行比较：

agents-cli eval run

你也可以直接测试查询或进行交互式测试：

# 测试单个提示
agents-cli run "Look up customer cust_101 and apply a 10% discount on $100."

# 启动交互式 Web UI
agents-cli playground

后续步骤