使用 ADK 架构开发 Agent 自动化评估脚本

发布日期：2025-08-09 14:57:17 浏览次数： 2137

作者：弓长先生的杂货铺

微信搜一搜，关注“弓长先生的杂货铺”

在之前的文章中，我分析了当前测试方法在 LLM 应用测试中的不足，并介绍了基于 DeepEval 框架的一种解决方案（文章链接放在文末）。

DeepEval 是一个功能强大的开源评估框架，但对开发者来说，上手仍有一定门槛。最近在学习 Google 的 ADK 框架时，我意外发现它内置的评估功能非常好用，上手门槛低、配置简单，真正实现了开箱即用。说直白点，已经达到了有手就能写 Agent 自动化评估脚本的程度。

这篇文章，我会带你基于 ADK 框架实现一个完整的 Agent 自动化评估脚本。

一、为什么要做 Agent 的自动化评估

在生成式大模型出现之前，我们习惯于用“预期结果 = 实际输出”这种确定性逻辑来写测试用例，执行测试脚本。

但当系统引入 LLM 之后，这套思路开始失效。因为模型输出具有非确定性，我们无法再用“pass/fail”的硬性断言来做判定，而需要引入更为灵活的指标体系，从输出质量、工具使用路径等多个维度进行评估。

Google 在 ADK 文档中有一段总结非常到位：

In traditional software development, unit tests and integration tests provide confidence that code functions as expected and remains stable through changes. These tests provide a clear "pass/fail" signal, guiding further development. However, LLM agents introduce a level of variability that makes traditional testing approaches insufficient.

Due to the probabilistic nature of models, deterministic "pass/fail" assertions are often unsuitable for evaluating agent performance. Instead, we need qualitative evaluations of both the final output and the agent's trajectory - the sequence of steps taken to reach the solution. This involves assessing the quality of the agent's decisions, its reasoning process, and the final result.

https://google.github.io/adk-docs/evaluate/

二、评估什么

对一个 Agent 而言，执行过程主要包含两个核心环节：

1. 工具筛选与调用过程

2. 最终返回结果

对应到 ADK 框架中，这两个环节也正是它评估的重点：

Evaluating Trajectory and Tool Use：评估工具调用路径是否正确，执行顺序是否合理。
Evaluating Final Response：评估最终输出是否满足用户意图。

一般来说：

工具调用轨迹需要完全匹配（默认通过分数为 1.0，即 100%）；

最终输出允许有一定偏差（默认通过分数为 0.8，即 80%）。

三、怎么评估

在 ADK 中，评估脚本的开发主要包括两部分：编写验证JSON文件和编写调用代码。

1. 编写验证JSON文件

验证文件是一个JSON格式的文件，这是评估的“输入数据”，用来描述一次完整的交互过程，包括：

1）User Content：用户发出的原始问题。

例如：

          "user_content": {            "parts": [              {                "text": "显示orders表结构"              }            ],            "role": "user"          }

2）Expected Intermediate Tool Use Trajectory：期望的工具调用路径（包含选择了哪些工具、调用顺序等）。

例如：

      "expected_tool_use": [        {"name": "transfer_to_agent", "args": {"agent_name": "table_info"}},        {"name": "get_table_info", "args": {"table_name": "orders"}}      ],

          "intermediate_data": {            "tool_uses": [              {                "name": "transfer_to_agent",                "args": {                  "agent_name": "table_info"                }              },              {                "name": "get_table_info",                "args": {                  "table_name": "orders"                }              }            ],            "intermediate_responses": []          }

3）Expected Intermediate Agent Responses：各阶段 Agent（主/子）的中间响应。

例如：

          "intermediate_data": {            ...            "intermediate_responses": [] # Any intermediate sub-agent responses.          }

4）Final Response：最终输出结果。

例如：

          "final_response": {            "parts": [              {                "text": "## 表结构：orders\n\n**基本信息：**\n- 表名：orders\n- 记录数：900 行\n- 列数：19 列\n\n**字段详情：**\n| 字段名                  | 数据类型           | 说明                           |\n|-------------------------|--------------------|--------------------------------|\n| id                      | INTEGER            | 订单唯一标识                   |\n| coupon_code             | varchar(255)       | 使用的优惠券代码               |\n| create_time             | timestamp          | 订单创建时间                   |\n| logistics_company       | varchar(255)       | 物流公司名称                   |\n| note                    | varchar(255)       | 订单备注                       |\n| pay_time                | timestamp          | 支付时间                       |\n| payment_method          | varchar(255)       | 支付方式                       |\n| payment_transaction_id  | varchar(255)       | 支付交易ID                     |\n| product_id              | bigint             | 关联的产品ID                   |\n| quantity                | INTEGER            | 商品数量                       |\n| receiver_address        | varchar(255)       | 收货地址                       |\n| receiver_name           | varchar(255)       | 收货人姓名                     |\n| receiver_phone          | varchar(255)       | 收货人电话                     |\n| specification           | varchar(255)       | 商品规格                       |\n| status                  | varchar(255)       | 订单状态                       |\n| total_amount            | numeric(38,2)      | 订单总金额                     |\n| tracking_number         | varchar(255)       | 物流跟踪号                     |\n| update_time             | timestamp          | 订单更新时间                   |\n| user_id                 | bigint             | 关联的用户ID                   |\n\n**设计特点：**\n1. **主键**：`id` 字段作为订单的唯一标识。\n2. **时间字段**：`create_time` 和 `update_time` 分别记录订单的创建和更新时间。\n3. **关联字段**：`product_id` 和 `user_id` 可能与其他表（如 `products` 和 `users`）关联。\n4. **状态管理**：`status` 字段用于跟踪订单状态。\n5. **金额字段**：`total_amount` 使用 `numeric(38,2)` 类型，适合存储精确的金额数据。\n\n**建议后续操作：**\n- 查看样本数据：使用 `sample_data_agent`。\n- 执行查询：使用 `query_execution_agent`."              }            ],            "role": "model"          }

完整样例：

以我在前文中实现的 Agent 为例，用户输入“显示 orders 表结构”时，系统内部触发了如下三步Agent 和 LLM 之间的交互：

第 1 次：LLM 识别意图，决定调用 transfer_to_agent，将请求路由到子 Agent；
第 2 次：子 Agent 执行 Tool，触发 get_table_info；
第 3 次：生成最终的自然语言回复，返回给用户。

整个过程如下图所示，都可以被完整写入验证 JSON 中。

完整验证 JSON 文件table_schema_analysis.test.json如下：

{  "eval_set_id": "table-schema-analysis-sqlite",  "name": "Table Schema Analysis SQLite",  "description": "测试表结构探索和schema分析能力",  "eval_cases": [    {      "eval_id": "table-schema-orders-structure",      "query": "显示orders表结构",      "expected_tool_use": [        {"name": "transfer_to_agent", "args": {"agent_name": "table_info"}},        {"name": "get_table_info", "args": {"table_name": "orders"}}      ],      "conversation": [        {          "invocation_id": "inv-schema-1",          "user_content": {            "parts": [              {                "text": "显示orders表结构"              }            ],            "role": "user"          },          "final_response": {            "parts": [              {                "text": "## 表结构：orders\n\n**基本信息：**\n- 表名：orders\n- 记录数：900 行\n- 列数：19 列\n\n**字段详情：**\n| 字段名                  | 数据类型           | 说明                           |\n|-------------------------|--------------------|--------------------------------|\n| id                      | INTEGER            | 订单唯一标识                   |\n| coupon_code             | varchar(255)       | 使用的优惠券代码               |\n| create_time             | timestamp          | 订单创建时间                   |\n| logistics_company       | varchar(255)       | 物流公司名称                   |\n| note                    | varchar(255)       | 订单备注                       |\n| pay_time                | timestamp          | 支付时间                       |\n| payment_method          | varchar(255)       | 支付方式                       |\n| payment_transaction_id  | varchar(255)       | 支付交易ID                     |\n| product_id              | bigint             | 关联的产品ID                   |\n| quantity                | INTEGER            | 商品数量                       |\n| receiver_address        | varchar(255)       | 收货地址                       |\n| receiver_name           | varchar(255)       | 收货人姓名                     |\n| receiver_phone          | varchar(255)       | 收货人电话                     |\n| specification           | varchar(255)       | 商品规格                       |\n| status                  | varchar(255)       | 订单状态                       |\n| total_amount            | numeric(38,2)      | 订单总金额                     |\n| tracking_number         | varchar(255)       | 物流跟踪号                     |\n| update_time             | timestamp          | 订单更新时间                   |\n| user_id                 | bigint             | 关联的用户ID                   |\n\n**设计特点：**\n1. **主键**：`id` 字段作为订单的唯一标识。\n2. **时间字段**：`create_time` 和 `update_time` 分别记录订单的创建和更新时间。\n3. **关联字段**：`product_id` 和 `user_id` 可能与其他表（如 `products` 和 `users`）关联。\n4. **状态管理**：`status` 字段用于跟踪订单状态。\n5. **金额字段**：`total_amount` 使用 `numeric(38,2)` 类型，适合存储精确的金额数据。\n\n**建议后续操作：**\n- 查看样本数据：使用 `sample_data_agent`。\n- 执行查询：使用 `query_execution_agent`."              }            ],            "role": "model"          },          "intermediate_data": {            "tool_uses": [              {                "name": "transfer_to_agent",                "args": {                  "agent_name": "table_info"                }              },              {                "name": "get_table_info",                "args": {                  "table_name": "orders"                }              }            ],            "intermediate_responses": []          }        }      ]    }  ]}

2. 编写调用代码。

评估脚本本身非常精简，核心代码仅 2 行：

@pytest.mark.asyncioasync def test_table_schema_analysis():    """Test table structure exploration and schema analysis capabilities."""    await AgentEvaluator.evaluate(        "sqlite_agent",        str(pathlib.Path(__file__).parent / "data/table_schema_analysis.test.json"),        num_runs=1    )

第 6 行：指定验证 JSON 文件路径；

第 7 行：指定运行次数。

至此，我们已经完成了所有的代码编写工作，就这么简单。

四、怎么运行

ADK 提供三种运行方式，按需选择即可：

1. 使用 ADK 自带命令行工具：

adk eval \    sqlite_agent \    eval/data/data_analysis.test.json

2. 通过 pytest 集成：

pytest eval/test_eval.py::test_table_schema_analysis

3. 直接用 Python 脚本调用：

python -m pytest eval/test_eval.py::test_table_schema_analysis -v

五、怎么快速编写验证 JSON 文件

你可能会担心验证文件信息量太大，需要抓包、手动拼装，成本较高。其实 ADK 提供了非常友好的辅助方式，步骤如下：

1. 运行 ADK 的 Web UI

adk web

访问http://127.0.0.1:8000/dev-ui/

2. 输入问题进行一次完整对话

使用 Web UI 的交互框，模拟用户真实输入。

3. 查看交互日志

在 Event中可以看到每一轮请求和响应。点击“下载”，可将整个对话保存为 JSON 文件。

可以手动提取关键字段，也可以借助 AI 辅助编码工具，根据这份 JSON 自动生成验证脚本模板。

4. 直接用 Web UI 自带的 Eval 功能

Web UI甚至提供了评估功能。你可以在 Eval 菜单中新建一个评估任务，选定某次对话 session，即可对 Agent 行为进行评估。

六、总结

相比 DeepEval，ADK 在 Agent 评估方面提供了更贴合 LLM 工作机制的原生支持，从而帮助我们更快速地开发 Agent 自动化评估脚本，进一步降低了开发成本。

附上关于DeepEval的文章：

应用系统集成大模型后如何进行测试？

使用deepeval对集成大模型的应用系统进行自动化测试

使用deepeval测试大模型生成内容的完整样例代码

53AI，企业落地大模型首选服务商

产品：场景落地咨询+大模型应用平台+行业解决方案

承诺：免费POC验证，效果达标后再合作。零风险落地应用大模型，已交付160+中大型企业