Agentforce Testing API 开发者指南 | Salesforce CRM 中文站

测试方法和流程

要上线一个可信可靠的 Agent，必须进行充分测试。Agentforce Builder 适合测试单个对话，但测试大量语句耗时长。Testing API 可以程序化批量测试，自动化评估过程并在短时间内评估大量请求。

三种测试方式对比

方式	接入方式	格式	自定义评估
Testing Center	UI	CSV	❌
Agentforce DX	CLI	YAML	✅
Testing API	Metadata + Connect API	XML	✅

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_match	Agent 是否使用了预期的子代理？需要 expectedValue
action_sequence_match	Agent 是否使用了预期的动作？值使用 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（<）、less_than_or_equal（<=）

JSONPath 表达式模式

$.generatedData.invokedActions[*][?(@.function.name == '{ACTION_NAME}')].{DYNAMIC_DATA}

常用目标路径：

动作输入：.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>.aiAgentScorerDefinition
package.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 / UNCERTAIN
metricExplainability —— 指标说明

3. 测试失败时的处理

使用 Agent Builder 预览面板进行对话式调试，追踪问题所在，根据需要调整指令、动作或子代理，然后重新运行测试。

核心要点：bot_response_rating 使用语义比较 —— 评估"要点"而非精确文本匹配。即使措辞不同，只要核心含义正确即可通过。这对处理措辞变化具有鲁棒性，同时仍能捕获根本性错误。

程序化测试是大规模部署可信、可靠 Agent 的关键。通过 Metadata API 构建测试、Connect API 运行评估、自定义评分器验证业务逻辑，形成一个完整的自动化质量保障体系。