自定义连接器返回HTTP 200但在Copilot Agent中出现ConnectorRequestFailure错误

自定义连接器「Connector-GWSample」在Copilot Studio的自定义连接器测试标签页中测试正常，返回HTTP 200状态码及符合预期的OData格式JSON响应，但在Copilot Agent主题中作为工具调用时，触发错误：

Error Message: The connector 'Connector-GWSample' returned an HTTP error with code 200. Error Code: ConnectorRequestFailure Conversation Id: cadd0bc7-a540-49ca-82eb-c708f7f02fd5 Time (UTC): 2025-07-21T12:18:55.787Z

已执行的排查操作：

• 添加了基于简化实际响应的「默认响应schema」
• 将响应Content-Type头设置为application/json
• 通过$top=5限制响应数据量并仅选择部分字段
• 验证响应为合法JSON格式
• 在主题中尝试直接调用/Connector-GWSample.Run() => $response并添加Trace($response)步骤

使用的响应样本Schema：

{
  "d": {
    "results": [
      {
        "BusinessPartnerID": "0100000000",
        "CompanyName": "SAP",
        "EmailAddress": "******@sap.com"
      }
    ]
  }
}

1. Schema与实际响应的字段类型不匹配 #

即使JSON结构一致，若schema中定义的字段类型和实际返回的类型存在差异（比如schema定义BusinessPartnerID为数字，但实际返回是字符串），Copilot Studio的工具调用校验逻辑会判定响应无效，触发ConnectorRequestFailure。

• 排查方式：逐字段对比实际响应的类型与schema定义，确保完全一致；可使用本地JSON Schema校验工具验证实际响应是否匹配你定义的schema。

2. OData响应的特殊结构处理问题 #

Copilot Studio对OData格式的响应可能有特定解析逻辑，尤其是嵌套的d.results结构：

• 确认自定义连接器是否正确识别OData类型：创建连接器时是否选择「OData」模板？如果是手动创建的REST连接器，需额外配置OData相关解析规则。
• 在连接器的响应schema中，明确标记d和results的层级结构为对象/数组类型，避免解析歧义。

3. 主题中工具调用的参数传递差异 #

测试页的请求参数可能和主题调用时的参数不一致：

• 检查主题中调用连接器时传递的参数（查询参数、请求头等）是否和测试页完全一致，尤其是$select、$top等OData参数的拼接是否正确。
• 确认动态参数（比如变量替换）是否导致实际请求参数不符合预期，比如变量为空或格式错误。

4. 工具响应大小超限 #

即使使用$top=5限制数据量，若单条记录的字段内容过大（比如超长文本），可能触发Copilot Studio内部的响应大小限制：

• 进一步精简响应字段，只保留最必要的内容测试，看是否能正常返回。
• 检查响应总字节数是否超过Copilot Studio的工具响应限额（当前官方限额通常为几MB）。

5. 权限或身份验证上下文差异 #

测试页的身份验证上下文可能和主题运行时的上下文不同：

• 确认测试用凭据和主题运行时使用的凭据权限范围一致，比如是否存在服务账号权限不足的情况。
• 检查连接器的身份验证配置是否正确传递到主题的工具调用中，比如OAuth令牌在主题运行时是否有效。

6. 响应头的额外字段干扰 #

除Content-Type外，响应中的特殊头字段可能导致解析异常：

• 检查API返回的响应头是否包含非标准字段，比如Transfer-Encoding、Content-Encoding（若启用压缩但Copilot Studio未正确处理）。
• 在连接器配置中添加「响应头白名单」，仅允许必要的头字段传递到Copilot Studio。

• 添加Trace($response)后，查看Copilot Studio测试面板-跟踪日志，确认是否能完整获取响应内容；若日志中无响应内容，说明响应在传递到主题时被拦截。
• 创建极简测试主题，仅包含连接器调用和Trace步骤，排除其他主题逻辑（分支判断、变量处理）的干扰。

内容的提问来源于stack exchange，提问作者Mamta Patil