# 查询trace聚合拓扑信息 - ShowOpsTraceAggregated #### 功能介绍 查询调用链的聚合拓扑信息，将相同类型的Span聚合为节点，基于父子关系生成边 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-agentarts/agentarts_07_0003.html)。 #### 授权信息 当前API调用无需身份策略权限。 #### URI GET /v1/ops/observation/traces/{trace_id}/aggregated 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | trace_id | 是 | String | **参数解释**： 调用链ID，可通过查询调用链列表接口（ListOpsTrace）获取。 **约束限制**： 长度限制为1\~64个字符。 **取值范围**： 不涉及。 **默认取值**： 不涉及。 | 表2Query参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | resource_type | 否 | String | **参数解释**： 资源类型，指定查询的资源对象类型，用于前置校验是否支持聚合拓扑查询。 **约束限制**： 不涉及。 **取值范围**： - agent：单智能体； - multiagents：多智能体； - workflow：工作流。 **默认取值**： 不涉及。 | #### 请求参数 无 #### 响应参数 **状态码：200** 表3响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | trace_id | String | **参数解释**： 调用链ID。 **取值范围**： 不涉及。 | | root_node_ids | Array of strings | **参数解释**： 根节点ID列表，单智能体场景包含一个元素，多智能体场景可包含多个入口节点。列表中的每个元素为根节点的Span ID字符串。 **取值范围**： 不涉及。 | | nodes | Array of [AggregatedTopologyNode] objects | **参数解释**： 聚合节点列表。列表中的每个元素为一个聚合拓扑节点对象（AggregatedTopologyNode），包含节点ID、名称、类型、调用次数、耗时统计、错误数等信息。 **取值范围**： 不涉及。 | | edges | Array of [AggregatedTopologyEdge] objects | **参数解释**： 聚合边列表。列表中的每个元素为一条聚合边对象（AggregatedTopologyEdge），表示节点间的调用关系，包含源节点ID、目标节点ID、调用次数、耗时统计等信息。 **取值范围**： 不涉及。 | | summary | [AggregatedTopologySummary] object | **参数解释**： 调用链汇总信息对象（AggregatedTopologySummary），包含总Span数、Agent Span数、总耗时、开始时间、结束时间等统计信息。 **取值范围**： 不涉及。 | 表4AggregatedTopologyNode | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释**： 节点唯一ID。 **取值范围**： 不涉及。 | | name | String | **参数解释**： 节点名称。 **取值范围**： 不涉及。 | | type | String | **参数解释**： 节点类型。 **取值范围**： - Agent：智能体； - Step：步骤； - LLM：大模型； - Tool：工具； - Memory：记忆。 | | call_count | Long | **参数解释**： 调用次数。 **取值范围**： 不涉及。 | | sum_duration_ms | Long | **参数解释**： 总耗时，单位为毫秒。 **取值范围**： 不涉及。 | | avg_duration_ms | Double | **参数解释**： 平均耗时，单位为毫秒。 **取值范围**： 不涉及。 | | max_duration_ms | Long | **参数解释**： 最大耗时，单位为毫秒。 **取值范围**： 不涉及。 | | min_duration_ms | Long | **参数解释**： 最小耗时，单位为毫秒。 **取值范围**： 不涉及。 | | error_count | Long | **参数解释**： 错误次数。 **取值范围**： 不涉及。 | | tokens_total | Long | **参数解释**： Token总消耗，仅LLM类型有值。 **取值范围**： 不涉及。 | | status | String | **参数解释**： 状态。 **取值范围**： - SUCCESS：成功； - PARTIAL_ERROR：部分错误； - ALL_ERROR：全部错误。 | | span_ids | Array of strings | **参数解释**： 聚合节点包含的原始Span ID列表。列表中的每个元素为一个原始Span的ID字符串。 **取值范围**： 不涉及。 | | details | Array of [AggregatedTopologyDetailItem] objects | **参数解释**： 按原始spanType分组的明细信息列表。列表中的每个元素为一个明细项对象（AggregatedTopologyDetailItem），包含该类型下所有Span的聚合统计信息，如Span ID、类型、名称、调用次数等。 **取值范围**： 不涉及。 | 表5AggregatedTopologyDetailItem | 参数 | 参数类型 | 描述 | |:---|:---|:---| | span_id | String | **参数解释**： 原始Span的ID。 **取值范围**： 不涉及。 | | span_type | String | **参数解释**： 原始Span的类型。 **取值范围**： - AGENT：智能体； - STEP：步骤； - LLM：大模型； - PLUGIN：工具插件； - TOOL：工具； - API：API调用； - RETRIEVER：检索器； - MEMORY：记忆。 | | span_name | String | **参数解释**： 原始Span的名称。 **取值范围**： 不涉及。 | | call_count | Long | **参数解释**： 调用次数。 **取值范围**： 不涉及。 | | sum_duration_ms | Long | **参数解释**： 总耗时，单位为毫秒。 **取值范围**： 不涉及。 | | tokens_total | Long | **参数解释**： Token总消耗，仅LLM类型有值。 **取值范围**： 不涉及。 | | error_count | Long | **参数解释**： 错误次数。 **取值范围**： 不涉及。 | 表6AggregatedTopologyEdge | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释**： 边唯一ID。 **取值范围**： 不涉及。 | | source | String | **参数解释**： 源节点ID。 **取值范围**： 不涉及。 | | target | String | **参数解释**： 目标节点ID。 **取值范围**： 不涉及。 | | call_count | Long | **参数解释**： 调用次数。 **取值范围**： 不涉及。 | | sum_duration_ms | Long | **参数解释**： 总耗时，单位为毫秒。 **取值范围**： 不涉及。 | | avg_duration_ms | Double | **参数解释**： 平均耗时，单位为毫秒。 **取值范围**： 不涉及。 | | tokens_total | Long | **参数解释**： Token总消耗，仅当目标节点为LLM类型时有值。 **取值范围**： 不涉及。 | | error_count | Long | **参数解释**： 错误次数。 **取值范围**： 不涉及。 | 表7AggregatedTopologySummary | 参数 | 参数类型 | 描述 | |:---|:---|:---| | total_spans | Long | **参数解释**： 总Span数。 **取值范围**： 不涉及。 | | agent_spans | Long | **参数解释**： Agent相关Span数。 **取值范围**： 不涉及。 | | sum_duration_ms | Long | **参数解释**： 总耗时，单位为毫秒。 **取值范围**： 不涉及。 | | start_time | Long | **参数解释**： Trace开始时间，Unix时间戳，单位为ms。 **取值范围**： 不涉及。 | | end_time | Long | **参数解释**： Trace结束时间，Unix时间戳，单位为ms。 **取值范围**： 不涉及。 | **状态码：400** 表8响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**： 错误码。 **取值范围**： 不涉及。 | | error_msg | String | **参数解释**： 错误信息。 **取值范围**： 不涉及。 | **状态码：403** 表9响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**： 错误码。 **取值范围**： 不涉及。 | | error_msg | String | **参数解释**： 错误信息。 **取值范围**： 不涉及。 | | encoded_authorization_message | String | **参数解释**： 编码后的授权信息，用于客户端解析权限问题。 **取值范围**： 不涉及。 | | details | Array of [OpsObserverCommonError] objects | **参数解释**： 依赖的下游服务错误信息列表。 **取值范围**： 不涉及。 | 表10OpsObserverCommonError | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**： 错误码。 **取值范围**： 不涉及。 | | error_msg | String | **参数解释**： 错误信息。 **取值范围**： 不涉及。 | **状态码：429** 表11响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**： 错误码。 **取值范围**： 不涉及。 | | error_msg | String | **参数解释**： 错误信息。 **取值范围**： 不涉及。 | **状态码：500** 表12响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**： 错误码。 **取值范围**： 不涉及。 | | error_msg | String | **参数解释**： 错误信息。 **取值范围**： 不涉及。 | #### 请求示例 无 #### 响应示例 **状态码：200** ``` { "trace_id" : "83a9f0c5c8b7592026c2dd25f8b5bf62", "root_node_ids" : [ "62112c000c290e0a" ], "nodes" : [ { "id" : "agent", "type" : "Agent", "call_count" : 1, "sum_duration_ms" : 314268, "avg_duration_ms" : 314268.0, "max_duration_ms" : 314268, "min_duration_ms" : 314268, "error_count" : 0, "status" : "SUCCESS", "span_ids" : [ "62112c000c290e0a" ], "details" : [ { "span_id" : "62112c000c290e0a", "span_type" : "AGENT", "span_name" : "invoke_agent workflow", "call_count" : 1, "sum_duration_ms" : 314268 } ] } ], "edges" : [ { "id" : "edge_1", "source" : "agent", "target" : "llm", "call_count" : 2, "sum_duration_ms" : 292576, "avg_duration_ms" : 146288.0, "tokens_total" : 58252, "error_count" : 0 } ], "summary" : { "total_spans" : 9, "agent_spans" : 1, "sum_duration_ms" : 314268, "start_time" : 1792380795827, "end_time" : 1792381110095 } } ``` **状态码：400** ``` { "error_code" : "AgentArts.05001003", "error_msg" : "请求参数不正确" } ``` **状态码：403** ``` { "error_code" : "AgentArts.05004003", "error_msg" : "权限不足，拒绝访问", "encoded_authorization_message" : "eyJIcnJvciI6ICJVbmF1dGhvcm16ZWQifQ==", "details" : [ { "error_code" : "AgentArts.05001003", "error_msg" : "请求参数不正确" } ] } ``` **状态码：429** ``` { "error_code" : "AgentArts.05008004", "error_msg" : "请求过多，触发流控" } ``` **状态码：500** ``` { "error_code" : "AgentArts.05005000", "error_msg" : "内部服务器错误" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | **参数解释**： 响应码，用于标识接口调用结果。 **取值范围**： 200表示成功，其他值表示失败，具体参见错误码文档。 | | 400 | **参数解释**： 响应码，用于标识接口调用结果。 **取值范围**： 400表示请求参数不正确。 | | 403 | **参数解释**： 响应码，用于标识接口调用结果。 **取值范围**： 403表示权限不足，拒绝访问。 | | 429 | **参数解释**： 响应码，用于标识接口调用结果。 **取值范围**： 429表示请求过多，触发流控。 | | 500 | **参数解释**： 响应码，用于标识接口调用结果。 **取值范围**： 500表示内部服务器错误。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-agentarts/ErrorCode.html)。