使用 ADK 架构开发 Agent 自动化评估脚本 - 链载Ai

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

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

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

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":[]#Anyintermediatesub-agentresponses.}

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 之间的交互：

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

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

{"eval_set_id":"table-schema-analysis-sqlite","name":"TableSchemaAnalysisSQLite","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.asyncioasyncdeftest_table_schema_analysis():"""Testtablestructureexplorationandschemaanalysiscapabilities."""awaitAgentEvaluator.evaluate("sqlite_agent",str(pathlib.Path(__file__).parent/"data/table_schema_analysis.test.json"),num_runs=1)

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

第 7 行：指定运行次数。

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

四、怎么运行

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

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

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

2. 通过 pytest 集成：

pytesteval/test_eval.py::test_table_schema_analysis

3. 直接用 Python 脚本调用：

python-mpytesteval/test_eval.py::test_table_schema_analysis-v

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

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

1. 运行 ADK 的 Web UI

adkweb

访问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测试大模型生成内容的完整样例代码