测试与评估

在将受众更改为 EVERYONE 之前，针对预期答案和失败情况测试代理。

从受限设置开始

在建立测试基线时，保持推出、转接和跟进处于禁用状态。在添加测试接收者之前限制受众。 API 参考： GET 获取设置 · PUT 替换设置

curl --request PUT \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/settings" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "rollout": {"enabled": false},
    "handoff": {"enabled": false},
    "followup": {"enabled": false},
    "ai_audience": "ALLOWLISTED_ONLY"
  }'

GET 获取设置返回一个数组，即使只有一个设置对象存在。PUT 替换设置返回更新后的设置对象。YCloud 在调用 Meta 之前会省略空字段，因此未提供的设置保持不变。

字段	测试基线
`rollout.enabled`	保持 `false` 直到代理准备好进行实时 WhatsApp 测试。
`handoff.enabled`	在基线响应测试期间保持 `false`。在测试转接场景时单独启用它。
`followup.enabled`	在基线响应测试期间保持 `false`。在测试跟进场景时单独启用它。
`ai_audience`	使用 `ALLOWLISTED_ONLY` 直到受限验收测试通过。

更新后读回有效设置。在测试转接或跟进时，一次更改一种行为，然后在转移到另一个场景之前恢复受限基线。

添加测试接收者

将 ai_audience 设置为 ALLOWLISTED_ONLY，然后将每个测试人员添加为 E.164 电话号码。存储返回的允许列表条目 id，以便稍后可以删除该条目。 API 参考： GET 列出允许列表 · POST 创建允许列表条目 · DELETE 删除允许列表条目

curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/allowListEntries" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"consumer_phone_number":"+14155550123"}'

使用 GET 列出允许列表查看当前的测试受众。使用 DELETE 删除允许列表条目通过返回的条目 ID 删除测试人员。

不要使用带有 +86 国家/地区呼叫代码的最终用户号码。Meta Business Agent 目前不回复来自 +86 最终用户的消息，即使该号码格式为有效的 E.164 并已添加到允许列表中。

运行单轮测试

API 参考： POST 测试代理

curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/tests" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"user_msg":"What is your return policy?"}'

成功的响应可以包含：

{
  "message_id": "MESSAGE_ID",
  "agent_response": "Unused items can be returned within 30 days.",
  "conversation_id": "CONVERSATION_ID",
  "timestamp": 1787630155,
  "quick_replies": [],
  "product_variant_ids": []
}

响应字段	含义
`message_id`	生成的响应的消息标识符。
`agent_response`	生成的响应文本。当存在 `no_response_reason` 时，它可以为空。
`conversation_id`	后续测试轮次的上下文标识符。
`timestamp`	Unix 时间戳（秒）。
`handoff_reason`	代理决定应由人工接管的原因（如果存在）。
`no_response_reason`	代理未产生响应的原因（如果存在）。
`quick_replies`	建议的快速回复标签（如果存在）。
`product_variant_ids`	响应引用的产品变体（如果存在）。

当前的 REST 响应不包括 estimated_token_usage。

保留多轮测试的上下文

将返回的 conversation_id 与下一条客户消息一起发送。 API 参考： POST 测试代理

curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/tests" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_msg": "What information do you need from me?",
    "conversation_id": "CONVERSATION_ID"
  }'

对于不得继承先前上下文的场景，请使用新对话。

测试知识、技能、连接器和工具

覆盖配置的资源，而不是仅测试理想路径问题。 API 参考： POST 运行连接器工具 · GET 列出连接器日志

提出由业务信息、常见问题解答、网站和文件回答的问题。
检查缺失的事实、矛盾的来源、过时的内容和不支持的请求。
验证每项技能何时应该运行，何时不应该运行。
使用有效、无效和不完整的输入来测试每个连接器工具。
确认机密值永远不会出现在响应或日志中。
包括应触发人工转接或不产生响应的情况。

如果连接器调用失败，请在更改技能之前检查连接器的日志并验证凭据、证书状态、参数绑定和工具请求定义。在允许代理在对话中选择它之前，通过 /connectors/{connectorId}/tools/{toolId}/runs 使用代表性的 input 直接运行每个配置的工具：

curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/connectors/CONNECTOR_ID/tools/TOOL_ID/runs" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"input":"Look up order ORD-1001"}'

通过 WhatsApp 与允许列表中的接收者进行测试

从每个允许列表中的测试电话号码验证相同的场景。这确认了测试端点无法完全重现的实时渠道行为。

在抢先体验期间，当受众为 ALLOWLISTED_ONLY 时，测试端点可能会返回空响应或 ELIGIBILITY_CHECK_FAILED。检查 no_response_reason、资格、推出、受众和允许列表设置。如果 API 测试需要 EVERYONE，请仅在受控环境中使用它，并在测试后立即恢复受限设置。

运行评估

评估 API 提供以下资源：

方法	路径	目的
`GET`	列出评估案例	列出可用的评估案例。
`POST`	提交评估运行	开始评估运行。
`GET`	获取评估运行状态	轮询运行进度和结果。
`GET`	获取评估详情	检索详细的评估结果。
`GET`	获取评估摘要	检索评估摘要。

列出可用的用例，使用所需的 eval_case_ids 值提交运行，保留返回的 job_id，并轮询作业端点。

curl "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/evalCases" \
  --header "X-API-Key: $YCLOUD_API_KEY"

curl --request POST \
  "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/evalRuns" \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"eval_case_ids":"EVAL_CASE_IDS"}'

curl "https://api.ycloud.com/v2/metaBusinessAgents/$PHONE_NUMBER_ID/evalRuns/JOB_ID" \
  --header "X-API-Key: $YCLOUD_API_KEY"

状态字段以字符串形式返回，目前不受已记录的枚举约束。当响应提供已完成的结果或错误时停止轮询，而不是假设未记录的状态名称。评估用例描述了 scenario、categories、max_turns 和 success_criteria。详细结果包括分数、轮次标签、原因、记录和时间戳。摘要汇总了分数、亮点和失败类别。

上线检查清单

必需的业务事实正确且不矛盾。
多轮对话保留了预期的上下文。
缺失信息会产生安全的响应，而不是捏造的答案。
连接器工具在具有代表性的输入下能够安全地成功和失败。
交接场景表现符合预期。
评估失败已得到审查，并已修复或明确接受。
回滚负责人知道如何禁用发布。

下一步：安全发布

首先为白名单收件人启用代理，然后扩展到所有受众。

开始使用

指南

接口

Webhooks

从受限设置开始

添加测试接收者

运行单轮测试

保留多轮测试的上下文

测试知识、技能、连接器和工具

通过 WhatsApp 与允许列表中的接收者进行测试

运行评估

上线检查清单

下一步：安全发布

​从受限设置开始

​添加测试接收者

​运行单轮测试

​保留多轮测试的上下文

​测试知识、技能、连接器和工具

​通过 WhatsApp 与允许列表中的接收者进行测试

​运行评估

​上线检查清单

下一步：安全发布

从受限设置开始

添加测试接收者

运行单轮测试

保留多轮测试的上下文

测试知识、技能、连接器和工具

通过 WhatsApp 与允许列表中的接收者进行测试

运行评估

上线检查清单