# 调试三方托管智能体 - DebugOpsThirdPartyAgent #### 功能介绍 该接口用于调试三方托管智能体或智能体运行时，向Agent发送测试请求，验证调用配置的正确性。调试成功后，配置自动保存至数据库并记录调试状态。三方智能体的身份信息（ID、名称）从可观测服务获取，调用参数（API地址、鉴权、请求参数、响应模式等）由评估服务管理并持久化存储。 适用场景： - 配置验证：在创建评估任务前，验证三方智能体或智能体运行时的调用配置是否正确。 - 连通性测试：测试Agent是否可正常访问和响应。 - 配置保存：调试成功后自动保存配置，后续创建评估任务时可直接引用。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-agentarts/agentarts_07_0003.html)。 #### 授权信息 账号根用户具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备如下身份策略权限，更多的权限说明请参见[权限和授权项](https://support.huaweicloud.com/api-agentarts/Permission.html)。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | agentarts::debugOpsThirdPartyAgent | Write | - | - | - | - | #### URI POST /v1/ops/third-party-agents/{agent_id}/debug 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | agent_id | 是 | String | **参数解释：** 合成任务的唯一标识符（ID），该参数用于在路径中指定特定的合成任务，以便执行查询、停止或删除等操作。获取方式：可通过创建合成任务接口返回的id获取，或通过查询合成任务列表接口获取。 **约束限制：** 不涉及。 **取值范围：** 1\~36个字符，通常采用标准UUID格式。 **默认取值：** 不涉及。 | #### 请求参数 表2请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | type | 是 | String | **参数解释：** 调试对象类型，用于区分三方托管智能体和智能体运行时。 **约束限制：** 必须为枚举值之一。 **取值范围：** - third_party_agent：三方托管智能体，需配置auth_config - agent_runtime：智能体运行时，平台内部调用无需auth_config **默认取值：** 不涉及。 | | description | 否 | String | **参数解释：** 智能体的描述信息。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | agent_name | 否 | String | **参数解释：** 三方智能体的名称。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | runtime_id | 否 | String | **参数解释：** 智能体运行时ID，type为agent_runtime时必填。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | api_config | 是 | [OpsThirdPartyAgentApiConfig] object | **参数解释：** 三方托管智能体的API访问配置。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | auth_config | 否 | [OpsThirdPartyAgentAuthConfig] object | **参数解释：** 三方托管智能体的鉴权配置。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | response_config | 是 | [OpsThirdPartyAgentResponseConfig] object | **参数解释：** 三方托管智能体的响应配置。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | timeout | 否 | Integer | **参数解释：** 单次调用超时时间（秒）。 **约束限制：** 整数类型，范围5到600。 **取值范围：** 5-600。 **默认取值：** 60。 | | variables | 否 | Map\ | **参数解释：** 自定义变量键值对，将替换API配置中的{{变量名}}占位符。例如API配置Body中使用{{input}}，则variables中传入input变量即可。 **约束限制：** 键和值均为字符串类型，最多支持20个变量。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表3OpsThirdPartyAgentApiConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | url | 否 | String | **参数解释：** 三方智能体的API访问地址。 **约束限制：** 仅支持HTTP/HTTPS协议。 **取值范围：** 由英文字母、数字、特殊字符(:/.-?\&=%_)组成的字符串，长度为1\~2048个字符。 **默认取值：** 不涉及。 | | headers | 否 | Array of [OpsThirdPartyAgentKeyValuePair] objects | **参数解释：** 请求Header参数列表。 **约束限制：** 最多支持10个Header。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | query_params | 否 | Array of [OpsThirdPartyAgentKeyValuePair] objects | **参数解释：** 请求Query参数列表。 **约束限制：** 最多支持10个Query参数。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | body | 否 | [OpsThirdPartyAgentRequestBodyConfig] object | **参数解释：** 三方智能体请求Body配置。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表4OpsThirdPartyAgentKeyValuePair | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 是 | String | **参数解释：** 参数名。 **约束限制：** 最大长度100字符。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | value | 否 | String | **参数解释：** 参数值，支持使用{{变量名}}占位符。 **约束限制：** 最大长度2000字符。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | description | 否 | String | **参数解释：** 参数描述，用于说明该参数的用途。 **约束限制：** 最大长度200字符。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表5OpsThirdPartyAgentRequestBodyConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | content | 否 | String | **参数解释：** 请求Body模板内容，支持使用{{变量名}}占位符，运行时会替换为实际值。 **约束限制：** 最大长度10000字符。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表6OpsThirdPartyAgentAuthConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | type | 是 | String | **参数解释：** 鉴权类型。 **约束限制：** 必须为枚举值之一。 **取值范围：** - API_KEY：API Key鉴权 - NONE：无需鉴权 **默认取值：** NONE。 | | api_key | 否 | String | **参数解释：** API Key值，当type为API_KEY时必填。 **约束限制：** 字符串类型，最大长度500。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | api_key_position | 否 | String | **参数解释：** API Key传递位置，当type为API_KEY时必填。 **约束限制：** 必须为枚举值之一。 **取值范围：** - HEADER：放在HTTP请求Header中 - QUERY：放在HTTP请求Query参数中 **默认取值：** HEADER。 | | api_key_name | 否 | String | **参数解释：** API Key参数名，当type为API_KEY时必填。 **约束限制：** 不涉及。 **取值范围：** 由英文字母、数字、点(.)、连字符(-)及下划线(_)组成的字符串，长度为1\~100个字符。 **默认取值：** 不涉及。 | 表7OpsThirdPartyAgentResponseConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | type | 是 | String | **参数解释：** 响应类型。 **约束限制：** 枚举值。 **取值范围：** STREAM（流式输出）、NON_STREAM（非流式输出）。 **默认取值：** NON_STREAM。 | | stream_config | 否 | [OpsThirdPartyAgentStreamConfig] object | **参数解释：** 流式响应配置，用于解析SSE流式输出。SSE的data字段为JSON字符串，需要通过匹配条件筛选目标数据，再从目标数据中提取Agent输出内容。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | non_stream_config | 否 | [OpsThirdPartyAgentNonStreamConfig] object | **参数解释：** 非流式响应配置，用于从响应体中提取Agent输出。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表8OpsThirdPartyAgentStreamConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | event_type | 否 | String | **参数解释：** 需要匹配的SSE事件类型，用于识别Agent输出事件。不填则匹配所有事件类型。 **约束限制：** 最大长度100字符。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | match_condition | 是 | [OpsThirdPartyAgentDataMatchCondition] object | **参数解释：** 数据匹配条件，当data JSON中指定字段的值等于期望值时，视为目标数据，从该数据中提取Agent输出。 **约束限制：** 不涉及。 | | output_key | 是 | String | **参数解释：** 目标数据中Agent输出内容的字段路径，支持多级路径（如aa.bb.cc）。仅当match_condition匹配成功时，从该条数据中提取output_key对应的值作为Agent输出。 **约束限制：** 最大长度200字符。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | end_condition | 否 | [OpsThirdPartyAgentDataMatchCondition] object | **参数解释：** 流结束匹配条件，当data JSON中指定字段的值等于期望值时，标识流式输出结束。 **约束限制：** 不涉及。 | | end_event_type | 否 | String | **参数解释：** 标识流式输出结束的SSE事件类型。不填则仅通过end_condition判断流结束。 **约束限制：** 最大长度100字符。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表9OpsThirdPartyAgentDataMatchCondition | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 是 | String | **参数解释：** data JSON字符串中用于匹配筛选的字段路径，支持多级路径（如aa.bb.cc）。 **约束限制：** 最大长度200字符。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | value | 是 | String | **参数解释：** key对应字段的期望值，当data中该字段值等于value时，视为匹配成功。 **约束限制：** 最大长度200字符。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表10OpsThirdPartyAgentNonStreamConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | output_key | 是 | String | **参数解释：** 响应体中Agent输出内容的字段路径，支持多级路径（如data.choices\[0\].message.content）。 **约束限制：** 最大长度200字符。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | #### 响应参数 **状态码：200** 表11响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | status_code | Integer | **参数解释：** HTTP响应状态码。 **取值范围：** 不涉及。 | | response_time | Integer | **参数解释：** 响应时间，单位毫秒。 **取值范围：** 不涉及。 | | output | String | **参数解释：** 提取后的Agent输出内容。 **取值范围：** 不涉及。 | | raw_response | String | **参数解释：** 原始响应内容。 **取值范围：** 不涉及。 | | error_message | String | **参数解释：** 错误信息，调用失败时返回。 **取值范围：** 不涉及。 | **状态码：400** 表12响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 系统定义的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对错误的详细描述，包含异常原因或解决建议。 **取值范围：** 字符长度2-512，任意文本内容。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权信息，用于客户端解析权限问题。 **取值范围：** Base64编码的字符串。 | | details | Array of [OpsErrorDetail] objects | **参数解释：** 错误详情列表，包含多个子错误的详细信息。 **取值范围：** 不涉及。 | | request_id | String | **参数解释：** 请求的唯一标识符，用于问题排查和链路追踪。 **取值范围：** 符合通用唯一识别码(UUID)标准的字符串。 | 表13OpsErrorDetail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 子错误的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对子错误的详细描述。 **取值范围：** 任意文本内容。 | **状态码：401** 表14响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 系统定义的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对错误的详细描述，包含异常原因或解决建议。 **取值范围：** 字符长度2-512，任意文本内容。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权信息，用于客户端解析权限问题。 **取值范围：** Base64编码的字符串。 | | details | Array of [OpsErrorDetail] objects | **参数解释：** 错误详情列表，包含多个子错误的详细信息。 **取值范围：** 不涉及。 | | request_id | String | **参数解释：** 请求的唯一标识符，用于问题排查和链路追踪。 **取值范围：** 符合通用唯一识别码(UUID)标准的字符串。 | 表15OpsErrorDetail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 子错误的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对子错误的详细描述。 **取值范围：** 任意文本内容。 | **状态码：403** 表16响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 系统定义的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对错误的详细描述，包含异常原因或解决建议。 **取值范围：** 字符长度2-512，任意文本内容。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权信息，用于客户端解析权限问题。 **取值范围：** Base64编码的字符串。 | | details | Array of [OpsErrorDetail] objects | **参数解释：** 错误详情列表，包含多个子错误的详细信息。 **取值范围：** 不涉及。 | | request_id | String | **参数解释：** 请求的唯一标识符，用于问题排查和链路追踪。 **取值范围：** 符合通用唯一识别码(UUID)标准的字符串。 | 表17OpsErrorDetail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 子错误的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对子错误的详细描述。 **取值范围：** 任意文本内容。 | **状态码：404** 表18响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 系统定义的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对错误的详细描述，包含异常原因或解决建议。 **取值范围：** 字符长度2-512，任意文本内容。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权信息，用于客户端解析权限问题。 **取值范围：** Base64编码的字符串。 | | details | Array of [OpsErrorDetail] objects | **参数解释：** 错误详情列表，包含多个子错误的详细信息。 **取值范围：** 不涉及。 | | request_id | String | **参数解释：** 请求的唯一标识符，用于问题排查和链路追踪。 **取值范围：** 符合通用唯一识别码(UUID)标准的字符串。 | 表19OpsErrorDetail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 子错误的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对子错误的详细描述。 **取值范围：** 任意文本内容。 | **状态码：429** 表20响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 系统定义的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对错误的详细描述，包含异常原因或解决建议。 **取值范围：** 字符长度2-512，任意文本内容。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权信息，用于客户端解析权限问题。 **取值范围：** Base64编码的字符串。 | | details | Array of [OpsErrorDetail] objects | **参数解释：** 错误详情列表，包含多个子错误的详细信息。 **取值范围：** 不涉及。 | | request_id | String | **参数解释：** 请求的唯一标识符，用于问题排查和链路追踪。 **取值范围：** 符合通用唯一识别码(UUID)标准的字符串。 | 表21OpsErrorDetail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 子错误的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对子错误的详细描述。 **取值范围：** 任意文本内容。 | **状态码：500** 表22响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 系统定义的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对错误的详细描述，包含异常原因或解决建议。 **取值范围：** 字符长度2-512，任意文本内容。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权信息，用于客户端解析权限问题。 **取值范围：** Base64编码的字符串。 | | details | Array of [OpsErrorDetail] objects | **参数解释：** 错误详情列表，包含多个子错误的详细信息。 **取值范围：** 不涉及。 | | request_id | String | **参数解释：** 请求的唯一标识符，用于问题排查和链路追踪。 **取值范围：** 符合通用唯一识别码(UUID)标准的字符串。 | 表23OpsErrorDetail | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 子错误的标准化错误代码。 **取值范围：** 业务异常编码字符串。 | | error_msg | String | **参数解释：** 对子错误的详细描述。 **取值范围：** 任意文本内容。 | #### 请求示例 向三方智能体发送测试请求，验证调用配置正确性。 ``` POST https://api.example.com/v1/ops/third-party-agents/550e8400-e29b-41d4-a716-446655440000/debug ``` #### 响应示例 **状态码：200** 无 **状态码：400** ``` { "error_code" : "AgentArts.10004001", "error_msg" : "file_suffix is required" } ``` **状态码：401** ``` { "error_code" : "AgentArts.100004010", "error_msg" : "unauthorized" } ``` **状态码：403** ``` { "error_code" : "AgentArts.100004030", "error_msg" : "forbidden" } ``` **状态码：404** ``` { "error_code" : "AgentArts.10004001", "error_msg" : "三方智能体不存在" } ``` **状态码：429** ``` { "error_code" : "AgentArts.100004290", "error_msg" : "请求过于频繁" } ``` **状态码：500** ``` { "error_code" : "AgentArts.03500001", "error_msg" : "internal error" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 调试成功 | | 400 | 请求参数错误 | | 401 | 认证失败 | | 403 | 鉴权失败 | | 404 | 三方智能体不存在 | | 429 | 请求过于频繁 | | 500 | 系统错误 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-agentarts/ErrorCode.html)。