Agentforce DX Agent 测试指南 | Salesforce CRM 中文站

注意：本节介绍的是传统 Agent 测试流程，即使用传统 Agentforce Testing Center 的专业代码等价方式。新的 Agent 测试流程（Agentforce Studio 中的新 Testing Center Beta）的文档即将发布。

专业代码 Agent 测试流程

测试 Agent 就是向它发送问题、陈述或命令（Utterances，话语），然后验证 Agent 的响应行为是否符合预期。使用 Agentforce DX 测试 Agent 是在开发组织中使用 Agentforce Testing Center UI 的专业代码等价方式。与任何软件开发一样，测试 Agent 是一个迭代过程。

完整的测试生命周期

1. 生成测试 Spec：使用 agent generate test-spec CLI 命令，创建描述一个或多个测试用例的本地 YAML 文件。

2. 自定义测试 Spec YAML：添加更多测试项，如设置上下文变量、引入内置质量指标、添加自定义评估标准和对话历史。

3. 创建 Agent 测试：使用 agent test create 命令将测试部署到组织，自动将关联的元数据同步回 DX 项目。

4. 运行测试并查看结果：通过 CLI 或 VS Code Testing Panel 运行，支持异步/同步模式，多种输出格式（Human-Readable、JSON、TAP、JUnit）。

5. 分析与迭代：全部通过则完成；如有失败，使用 Agent Preview 对话式调试，使用 Apex Replay Debugger 调试 Apex 类，根据结果调整指令、动作或子代理。

6. 加入 CI/CD：将测试纳入持续集成系统，确保 Agent 持续正确运行。

自定义 Agent 测试 Spec

上下文变量（Context Variables）

Service Agent 可以连接到消息渠道，使用 MessagingSession 标准对象中的上下文变量来个性化对话。在测试用例中通过 contextVariables 添加测试值：

testCases:
  - utterance: Are there any resort experiences that match my interests today?
    contextVariables:
      - name: EndUserLanguage
        value: Spanish

API 名称可在 Agent Builder UI 的 Context 标签页中找到，对应 MessagingSession 对象的字段。

质量指标（Metrics）

generate 命令自动为每个测试用例添加四项内置指标：

指标	描述	评估方向
Coherence（连贯性）	响应是否易于理解、语法正确？	越高越好
Completeness（完整性）	响应是否包含所有必要信息？	越高越好
Conciseness（简洁性）	响应是否简洁但全面？	越高越好
Latency（延迟）	从请求到响应的毫秒数	—

结果显示通过/失败及其 Value/Threshold 分数，例如：✅ COHERENCE (4/0.6) / ❌ COMPLETENESS (1/0.6)。可以删除不需要的指标。

自定义评估（Custom Evaluations）

使用 JSONPath 表达式测试 Agent 响应中的特定字符串或数值：

customEvaluations:
  - label: Check for correct date
    name: string_comparison
    parameters:
      - name: operator / value: equals
      - name: actual / value: $.generatedData.invokedActions[*][?(@.function.name == 'Check_Weather')].function.input.dateToCheck
      - name: expected / value: "2025-09-12"

构建 JSONPath 表达式的步骤：

先不带自定义评估运行测试，使用 --verbose 标志
在输出中找到 Generated Data 部分，查看调用的动作 JSON
针对特定数据点构建 JSONPath 表达式

对话历史（Conversation History）

用于多轮对话测试，为话语添加上下文：

conversationHistory:
  - role: user / message: I purchased an item last week but it hasn't arrived yet.
  - role: agent / message: What is your order ID? / topic: Ask_for_Order_ID
  - role: user / message: It's 123456.

注意：Agent 消息需要指定生成该响应的子代理（topic）。

从 Spec 文件创建 Agent 测试

在对测试 Spec 文件满意后，将其部署到开发组织。前提条件：Agent 必须已发布到组织。

预览测试（不更新组织）

sf agent test create --preview --target-org <org>

生成预览元数据 XML 文件：{Test_Api_name}-preview-{timestamp}.xml。检查无误后执行实际创建。

创建测试（更新组织）

sf agent test create --target-org <org>

执行阶段：创建本地元数据 → 部署到组织 → 同步到 DX 项目。DX 项目获得 AiEvaluationDefinition 元数据文件。

查看已部署的测试：sf org open --path /lightning/setup/TestingCenter/home --target-org <org>

使用 Agentforce DX 运行 Agent 测试

CLI 命令

# 运行测试
sf agent test run --api-name Resort_Manager_Test --target-org my-dev-org

# 列出可用测试
sf agent test list --target-org my-dev-org

# 异步模式（默认）—— 获取 Job ID 后恢复查看
sf agent test resume --job-id 4KBed00fakeahmPGAQ

# 同步模式
sf agent test run --api-name Resort_Manager_Test --wait 20

# 指定输出格式
sf agent test run --api-name Resort_Manager_Test --wait 20 --result-format JSON --output-dir json-files

# 查看已完成测试结果
sf agent test results --job-id <job-id>

支持四种输出格式：Human-Readable（默认）、JSON、TAP（Test Anything Protocol）、JUnit。

VS Code Testing Panel

点击 Activity Bar 中的烧杯图标 → 展开 Agent Tests 部分
列出测试及其编号的测试用例，点击箭头运行
Output 面板显示运行结果，点击测试用例查看详细信息
前提条件：需要 DX 项目中有 AiEvaluationDefinition 元数据（通过 sf project retrieve start --metadata AiEvaluationDefinition 同步）

理解 CLI Agent 测试结果

测试结果（Human-Readable 输出）包含四个部分：

1. 总体状态

测试通过/失败摘要，运行的测试用例数量，成功/失败计数。

2. 测试用例详情（每个 Utterance）

测试类型	验证内容
Subagent Test	Agent 是否使用了预期的子代理？失败时 Actual 列显示实际使用的子代理
Action Test	Agent 是否使用了预期的动作？失败时显示实际调用的动作
Outcome Test	自然语言评估 —— 即使实际文本与预期不同，只要核心含义（"要点/gist"）一致，测试即可通过。仅在含义显著不同时才失败

3. 质量指标

仅包含 YAML Spec 中定义的指标：Coherence、Completeness、Conciseness 分数/阈值，以及延迟毫秒数。

4. 总体摘要

测试持续时间、Subagent/Action/Outcome 测试的总百分比通过率。

核心要点：Outcome 测试使用自然语言评估 —— 不要求精确文本匹配。测试判断核心含义是否匹配，因此对措辞变化具有鲁棒性，同时仍能捕获根本性的错误响应。

Agent 测试是一个迭代过程 —— 使用测试结果和 Agent Preview 持续优化 Agent 的指令、动作和子代理。将测试加入 CI/CD 以实现持续的质量保障。