adk-evals

ADK 评测技能

什么是评测？

评测是针对 ADK Agent 的自动化对话测试。每项评测都定义一个场景——一系列用户消息或事件——并断言机器人应执行的操作：它说了什么、调用了哪些工具、状态如何变化、运行了哪些工作流，等等。

评测会针对正在运行的开发机器人（adk dev）执行，因此测试的是完整技术栈，而不是模拟对象。

何时使用此技能

开发者询问以下内容时，请使用此技能：

• 编写评测——文件格式、断言、轮次类型、设置
• 运行评测——CLI 命令、筛选、输出解读
• 测试特定原语——如何测试操作、工具、工作流、对话、状态
• 测试循环——编写 → 运行 → 检查跟踪记录 → 迭代
• CI 集成——退出代码、--format json 标志、标记策略
• 评测配置——idleTimeout、judgePassThreshold、judgeModel

或者，当你正在开发 ADK 机器人并需要编写相当于单元测试或端到端测试的测试时。

触发问题：

• “如何编写评测？”
• “如何测试我的工作流？”
• “如何断言某个工具是使用特定参数调用的？”
• “我的评测失败了，该如何调试？”
• “如何测试机器人保持静默？”
• “如何在 CI 中运行评测？”
• “如何在评测前预置状态？”
• “如何在评测中触发工作流？”

可用文档

文件	内容
references/eval-format.md	完整文件格式——所有字段、轮次类型、断言类别、匹配运算符、设置、结果、选项
references/testing-workflow.md	运行评测、解读输出、使用跟踪记录、编写 → 测试 → 迭代循环、CI 集成
references/test-patterns.md	针对操作、工具、工作流、对话和状态的各原语测试模式

如何回答

1. 编写评测 → 阅读 eval-format.md，了解结构和断言
2. 运行评测 → 阅读 testing-workflow.md，了解 CLI 命令和输出
3. 测试特定原语 → 阅读 test-patterns.md 中的相关部分
4. 调试失败 → 结合使用 testing-workflow.md（检查跟踪记录）和 eval-format.md（检查断言语法）

---

快速参考

评测文件结构

import { Eval } from '@botpress/evals'

export default new Eval({
  name: 'greeting',
  type: 'regression',
  tags: ['basic'],

  setup: {
    state: { bot: { welcomeSent: false } },
    workflow: { trigger: 'onboarding', input: { userId: 'test-1' } },
  },

  conversation: [
    {
      user: 'Hi!',
      assert: {
        response: [{ not_contains: 'error' }, { llm_judge: 'Response is friendly and offers to help' }],
        tools: [{ not_called: 'createTicket' }],
        state: [{ path: 'conversation.greeted', equals: true }],
      },
    },
  ],

  outcome: {
    state: [{ path: 'conversation.greeted', equals: true }],
  },

  options: {
    idleTimeout: 60000,
    judgePassThreshold: 4,
  },
})

轮次类型

轮次	使用场景
user: 'message'	标准用户消息
event: { payload }	推送自定义事件（以 chat:custom 的形式到达）
expectSilence: true	断言机器人不会响应

断言类别

类别	检查内容
response	机器人回复文本（contains、not_contains、matches、llm_judge）
tools	工具调用（called、not_called、call_order、params）
state	机器人／用户／对话状态（equals、changed）
workflow	工作流执行情况（entered、completed）
timing	响应时间（毫秒，lte、gte）

CLI 命令

adk evals                        # run all evals
adk evals <name>                 # run one eval
adk evals --tag <tag>            # filter by tag
adk evals --type regression      # filter by type
adk evals --verbose              # show all assertions
adk evals --format json          # JSON output for CI

adk evals runs                   # list recent runs
adk evals runs --latest          # most recent run
adk evals runs --latest -v       # with full details

---

关键模式

✅ 每个轮次都需要 user 或 event

// CORRECT
{ user: 'hello', expectSilence: true }
{ event: { payload: { kind: 'payment.failed' } }, expectSilence: true }

❌ 单独使用 expectSilence 不是有效的轮次

// WRONG — missing user or event
{
  expectSilence: true
}

---

✅ 断言工具参数，以验证是否正确提取

// CORRECT — verifies the LLM extracted the right values
{ called: 'createTicket', params: { priority: { equals: 'high' } } }

❌ 只断言工具是否被调用

// INCOMPLETE — doesn't verify params were correct
{
  called: 'createTicket'
}

---

✅ 使用 outcome 断言对话后的状态和工作流

// CORRECT — final state checked once after all turns
outcome: {
  state: [{ path: 'conversation.resolved', equals: true }],
  workflow: [{ name: 'ticketFlow', completed: true }],
}

---

✅ 预置状态，以便在不运行设置轮次的情况下测试条件行为

// CORRECT — start in a known state
setup: {
  state: {
    user: { plan: 'pro' },
    conversation: { phase: 'support' },
  },
}

❌ 使用对话轮次设置状态（速度慢且脆弱）

// WRONG — depends on the bot correctly processing setup turns
conversation: [
  { user: 'I am on the pro plan' }, // hoping bot sets user.plan
  { user: 'I need help with billing' }, // actual test turn
]

---

示例问题

编写评测：

• “编写一个评测，测试我的 createTicket 工具是否使用正确的优先级调用”
• “如何断言机器人在内部事件后保持静默？”
• “如何测试保留上下文的多轮对话？”

运行评测：

• “如何只运行回归评测？”
• “如何查看哪些断言失败以及失败原因？”
• “如何将评测集成到 GitHub Actions 中？”

调试：

• “我的评测显示工具未被调用，但我认为它已被调用——该如何检查？”
• “如何检查机器人在评测期间实际执行了什么？”

按基本项分类：

• “如何测试使用 step.sleep() 的工作流？”
• “如何测试状态是否从预置值发生了变化？”

---

回复格式

根据问题的复杂程度调整回答深度。

简单问题（“有哪些可用的断言？”、“如何运行评测？”）

直接回答——展示相关表格或 CLI 命令。对于信息类问题，不要生成完整的评测文件。

编写评测

1. 展示完整的 new Eval({}) 调用，并填写合理的字段值
2. 包含导入语句（import { Eval } from '@botpress/evals'）
3. 简要说明不直观的断言——对于含义明确的断言，无需说明
4. 建议用于运行评测的 CLI 命令：adk evals <name>

调试失败的评测

1. 请求提供或展示失败断言（expected / actual 差异）
2. 建议在 Dev Console 中打开追踪记录，查看机器人执行了什么
3. 判断问题出在评测断言还是机器人的行为上