Agentforce Testing API 开发者指南

Testing API 开发者指南

Testing API 允许你编程式构建测试，自动化评估过程并在短时间内评估大量请求。通过减少测试时间，快速激活可信赖的 Agent。

注意：Agent 测试仅在 Sandbox 中可用。运行测试消耗 Requests 和 Credits，并可能修改数据。

测试方法与工作流

方法	访问方式	定义格式	自定义评估
Testing Center	UI	CSV	否
Agentforce DX	CLI	YAML	是
Testing API	代码（Metadata+Connect API）	XML	是

工作流：创建测试（Metadata API / Agentforce DX）→ 部署测试 → 运行测试（Connect API / Agentforce DX CLI）→ 查看结果。

注意事项：最多 10 个 IN-PROGRESS 运行；AiEvaluationDefinition 最多 1,000 个测试用例；结果可能因测试服务持续改进而变化。

在 Metadata API 中构建测试

使用 AiEvaluationDefinition Metadata API 类型定义测试。每个测试用例包含输入（utterance + 可选 Context Variables + Conversation History）和一组期望（expectations）。

AiEvaluationDefinition 结构与输入

完整 XML 示例

<?xml version="1.0" encoding="UTF-8"?>
<AiEvaluationDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
  <description>My Sample Tests</description>
  <name>my_test_n1</name>
  <subjectName>Agentforce_for_Salesforce</subjectName>
  <subjectType>AGENT</subjectType>
  <subjectVersion>v1</subjectVersion>
  <testCase>
    <number>1</number>
    <inputs>
      <utterance>Summarize the Global Media account</utterance>
      <contextVariable>
        <variableName>EndUserLanguage</variableName>
        <variableValue>Spanish</variableValue>
      </contextVariable>
    </inputs>
    <expectation>
      <name>topic_sequence_match</name>
      <expectedValue>OOTBSingleRecordSummary</expectedValue>
    </expectation>
    <expectation>
      <name>action_sequence_match</name>
      <expectedValue>["IdentifyRecordByName"]</expectedValue>
    </expectation>
    <expectation>
      <name>conciseness</name>
    </expectation>
  </testCase>
</AiEvaluationDefinition>

输入类型

• utterance：必填。测试的用户发言
• Context Variables：创建更细致的测试（如 EndUserLanguage=Spanish）。默认不可变，仅会话开始时设置（EndUserLanguage 例外）
• Conversation History：多轮对话上下文。每条含 role（user/agent）、message、topic（agent 时必填）、index

标准期望与质量指标

期望名称	说明	需要 expectedValue
topic_sequence_match	子代理测试：Agent 是否用了预期子代理	是
action_sequence_match	动作测试：Agent 是否用了预期动作（JSON 数组格式）	是
bot_response_rating	结果测试：语义比较（核心意思相同即通过，即使措辞不同）	是
coherence	连贯性：响应是否易理解、无语法错误	否
completeness	完整度：响应是否包含所有必要信息	否
conciseness	简洁性：响应是否简洁而全面（越短越好）	否
output_latency_ms	延迟：从发请求到收响应的毫秒数	否
instruction_adherence	指令遵循度：评估生成的响应遵循子代理指令的程度。metricScore 为 HIGH/LOW/UNCERTAIN	否

自定义评估标准

测试 Agent 响应中的特定字符串或数值。扩展了标准期望之外的能力，例如确保延迟 < 10 秒或动作输入输出满足特定要求。

自定义评估类型与 JSONPath

两种类型：string_comparison（字符串比较）和 numeric_comparison（数值比较）。每个参数限 100 字符。

字符串比较运算符：equals（区分大小写）、contains、startswith、endswith

数值比较运算符：equals、greater_than_or_equal、greater_than、less_than、less_than_or_equal

JSONPath 表达式模式

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

# 获取动作输入
$.generatedData.invokedActions[*][?(@.function.name == 'MyAction')].function.input.query
# 获取动作输出
$.generatedData.invokedActions[*][?(@.function.name == 'MyAction')].function.output.result
# 获取 additionalContext 第一个元素
$.generatedData.invokedActions[*][?(@.function.name == 'MyAction')].function.output.additionalContext[0].value

通过 sf agent test run --verbose 查看生成的 JSON 数据来构建正确的 JSONPath。

创建自定义评分器

Custom Scorer 使用 AiAgentScorerDefinition Metadata API 类型，通过 Prompt Template + LLM 自动评估 Agent 行为。支持三种范围：Session（整个会话）、Interaction（单次交互）、Moment（交互中的特定时刻）。

评分器定义与部署

核心组件：Engine（PromptTemplate 引擎）→ 输出映射（outputEnumValue：Pass/Fail/NotApplicable）→ agentAssociation（关联 Agent + 采样率）→ specification（min/max/step/threshold）。版本号从 1 开始顺序递增，最多 100 个版本。

# 项目结构
my-scorer-project/
├── package.xml
├── genAiPromptTemplates/       # Prompt Template（如有）
│   └── my_template.genAiPromptTemplate
└── aiAgentScorerDefinitions/
    └── my_scorer.aiAgentScorerDefinition

# 部署
sf project deploy start --metadata-dir my-scorer-project

# 拉取已有评分器
sf project retrieve start --metadata AiAgentScorerDefinition:my_scorer

注意：package.xml 中 GenAiPromptTemplate 必须在 AiAgentScorerDefinition 之前。可添加新版本但不能删除已有版本。

在 Connect API 中运行测试

Connect API 有三个端点：Start Test（启动异步测试）、Get Test Status（轮询进度）、Get Test Results（获取详细报告）。

Connect API 设置与端点

创建 External Client App：需 4 个 OAuth Scope（chatter_api/api/web/refresh_token）、启用 Client Credentials Flow + JWT Token。获取 Consumer Key/Secret → 创建 Token → 调用 API。

# 启动测试
curl -X POST https://{INSTANCE}.my.salesforce.com/services/data/v63.0/einstein/ai-evaluations/runs/ \
  -H "Authorization: Bearer {TOKEN}" \
  -d '{"aiEvaluationDefinitionName":"{TEST_NAME}"}'
# 返回 {"runId":"4KBSM00000000Xt4AI","status":"NEW"}

# 检查状态
curl https://{INSTANCE}.my.salesforce.com/services/data/v63.0/einstein/ai-evaluations/runs/{runId} \
  -H "Authorization: Bearer {TOKEN}"

# 获取结果
curl https://{INSTANCE}.my.salesforce.com/services/data/v63.0/einstein/ai-evaluations/runs/{runId}/results \
  -H "Authorization: Bearer {TOKEN}"

# 或通过 Agentforce DX CLI 直接查看
sf api request rest services/data/v63.0/einstein/ai-evaluations/runs/{runId}/results

理解测试结果

每个测试用例结果包含：status（COMPLETED/ERROR）、inputs（测试输入）、generatedData（actionsSequence/outcome/topic）、testResults 数组。

每个 testResult 含：name（期望名称）、actualValue vs expectedValue、metricScore（PASS/FAILED/HIGH/LOW/UNCERTAIN）、metricExplainability（解释）。

结果使用：如果测试失败，查看 errorMessage 和 metricScore。使用 Agent Builder Preview 对话式调试，然后优化 Agent 指令、动作或子代理。将测试加入 CI/CD 确保持续质量。

Testing API 是生产级 Agent 质量保证的核心工具。建议将 AiEvaluationDefinition 元数据纳入版本控制，与 Agent Script 一同管理。