测试方法和流程
要上线一个可信可靠的 Agent，必须进行充分测试。Agentforce Builder 适合测试单个对话，但测试大量语句耗时长。Testing API 可以程序化批量测试，自动化评估过程并在短时间内评估大量请求。
三种测试方式对比
方式接入方式格式自定义评估
Testing CenterUICSV❌
Agentforce DXCLIYAML✅
Testing APIMetadata + Connect APIXML✅
Testing API 工作流
创建测试 —— 使用 Metadata API 构建
AiEvaluationDefinition元数据，或使用 Agentforce DX 的agent generate test-spec生成 YAML 再转换为元数据部署测试 —— 使用
sf project deploy start或agent test create部署到 Sandbox运行测试 —— 使用 Connect API 的 REST 端点或
agent test run执行测试并获取结果
重要约束：测试仅在 Sandbox 中可用；消耗 Einstein Requests 积分；最多 10 个并发 IN-PROGRESS 运行；每个 AiEvaluationDefinition 最多 1,000 个测试用例；由于测试服务的持续改进，重新运行的结果可能有所变化。
使用 Metadata API 构建测试
使用 AiEvaluationDefinition 元数据类型程序化定义测试。每个定义包含一组测试用例，具有输入（语句、上下文变量、对话历史）和预期结果。
AiEvaluationDefinition 结构
字段说明name测试定义的唯一 API 名称subjectName被测试 Agent 的 API 名称subjectType"AGENT"subjectVersion测试版本（如 v1）testCase[]测试用例数组，每个包含 number / inputs / expectation[]
测试用例输入
utterance（语句） —— 发送给 Agent 的文本：
<utterance>Summarize the Global Media account</utterance>contextVariable（上下文变量） —— 模拟生产环境上下文，如设置 EndUserLanguage 为 Spanish。大多数上下文变量在会话启动后不可变
conversationHistory（对话历史） —— 启用多轮对话测试。每个条目指定 role（user/agent）、message、index。Agent 消息必须包含 topic（使用的子代理）
标准预期结果（Standard Expectations）
预期类型验证内容
topic_sequence_matchAgent 是否使用了预期的子代理？需要 expectedValue
action_sequence_matchAgent 是否使用了预期的动作？值使用 JSON 数组格式。使用 [] 表示预期无动作
bot_response_rating语义比较 —— 评估核心含义而非精确文本匹配。即使措辞不同，只要核心含义匹配即可通过
质量指标（Quality Metrics）
指标说明评分
coherence响应是否易于理解、语法正确？PASS/FAILED
completeness响应是否包含所有必要信息？PASS/FAILED
conciseness响应是否简洁但全面？PASS/FAILED
output_latency_milliseconds响应时间（毫秒）—
instruction_adherence响应遵循子代理指令的程度HIGH/LOW/UNCERTAIN
自定义评估标准
使用 JSONPath 表达式对 Agent 响应中的特定字符串或数值进行精确验证。两种类型：string_comparison（文本）和 numeric_comparison（数值）。
字符串比较运算符
equals（直接匹配，区分大小写）、contains、startswith、endswith
数值比较运算符
equals、greater_than_or_equal（>=）、greater_than（>）、less_than（常用目标路径：
动作输入：
.function.input.query动作输出：
.function.output.result嵌套输出：
.function.output.additionalContext[0].value
注意：每个参数字段限 100 字符。设置
isReference=true表示 value 是 JSONPath 表达式。先用--verbose运行测试查看 Generated Data JSON，再构建 JSONPath。
创建自定义评分器（Custom Scorers）
使用 AiAgentScorerDefinition 定义针对业务需求的评估逻辑。评分器利用提示模板引擎通过 LLM 自动评估 Agent 行为，并将输出映射为通过/失败/不适用。
核心字段
inputScope —— Session（整个会话）/ Interaction（单轮）/ Moment（单个动作）
dataType —— Text 或 Number
scorerVersion —— 版本配置（从 1 开始，最多 100 个版本），包含 versionNumber、status、agentAssociation（isActive/samplingRate）、engine（PromptTemplate 类型 + 引用）、outputEnumValue（Pass/Fail/NotApplicable 映射）
specification —— min/max/step/threshold（可选，>= threshold 为通过）
部署要点
项目结构：
aiAgentScorerDefinitions/<name>.aiAgentScorerDefinitionpackage.xml 中 GenAiPromptTemplate 必须排在 AiAgentScorerDefinition 之前（Metadata API 按顺序部署）
可以添加新版本但不能删除已有版本；可以更新版本状态和 agentAssociation
使用 Connect API 运行测试
Connect API 提供三个 REST 端点：启动测试（异步执行）、获取测试状态（轮询进度）、获取测试结果（详细报告）。
设置 External Client App（ECA）
需要的 OAuth 范围：chatter_api、api、web、refresh_token/offline_access。启用 Client Credentials Flow 和 JWT-based access tokens。
三个 Connect API 端点
`# 1. 启动测试（异步）
POST /services/data/v63.0/einstein/ai-evaluations/runs
Body: {"aiEvaluationDefinitionName": "{TEST_NAME}"}
Response: {"runId": "4KBSM00000000Xt4AI", "status": "NEW"}
2. 获取测试状态（轮询）
GET /services/data/v63.0/einstein/ai-evaluations/runs/{runId}
Response: {"status": "COMPLETED", "startTime": "...", "endTime": "..."}
3. 获取测试结果
GET /services/data/v63.0/einstein/ai-evaluations/runs/{runId}/results`
```
CLI 替代方案：sf agent test run --api-name MyTest 或 sf api request rest <endpoint>。
理解测试结果
每个测试用例的结果包含三个核心部分：
1. generatedData —— Agent 的实际行为
actionsSequence—— 调用了哪些动作outcome—— Agent 的响应文本topic—— 使用了哪个子代理
2. testResults[] —— 每个预期的评估结果
name—— 测试类型（topic_sequence_match / action_sequence_match / bot_response_rating / coherence / ...）actualValue/expectedValue—— 实际值和预期值metricScore—— PASS / FAILED / HIGH / LOW / UNCERTAINmetricExplainability—— 指标说明
3. 测试失败时的处理
使用 Agent Builder 预览面板进行对话式调试，追踪问题所在，根据需要调整指令、动作或子代理，然后重新运行测试。
核心要点：
bot_response_rating使用语义比较 —— 评估"要点"而非精确文本匹配。即使措辞不同，只要核心含义正确即可通过。这对处理措辞变化具有鲁棒性，同时仍能捕获根本性错误。
程序化测试是大规模部署可信、可靠 Agent 的关键。通过 Metadata API 构建测试、Connect API 运行评估、自定义评分器验证业务逻辑，形成一个完整的自动化质量保障体系。
文章来源：https://www.salesforcecrm.cn/article/agentforce/agentforce-testing-api-guide.html
