理解返回结果

responses

整体结构

轮询返回的

responses

一次典型分析会产生如下消息序列：

notify → message(知识检索) → message(执行过程) → metric → code → echarts_plus → summary → finish

并非所有类型每次都会出现，这取决于问题的复杂程度和 Agent 选择的分析路径。

消息类型速查

字段读取规则

每条消息的业务字段可能出现在不同层级。读取时按以下优先级：

1. response.字段名 （顶层） 2. response.modelRes.data.字段名 3. JSON.parse(response.rawRes).data.字段名

建议实现一个统一函数：

def read_field(response, field_name): """按优先级从 response 中读取指定字段""" # 优先级 1：顶层 if response.get(field_name): return response[field_name] # 优先级 2：modelRes.data model_data = response.get("modelRes", {}).get("data", {}) if model_data.get(field_name): return model_data[field_name] # 优先级 3：rawRes raw_res = response.get("rawRes") if raw_res and isinstance(raw_res, str): try: parsed = json.loads(raw_res) if parsed.get("data", {}).get(field_name): return parsed["data"][field_name] except json.JSONDecodeError: pass return None

各类型详解与展示建议

summary — 分析总结

这是最重要的消息，包含了最终的数据洞察和结论。

关键字段：

• summaryData

  summaryData
  — 总结文本（Markdown 格式）
• 如果

  summaryData

  summaryData
  为空，回退到

  message

  message

展示建议：直接渲染为 Markdown，支持表格和加粗等格式。

实际输出示例：

**北京二手房过去6年各区总成交金额 (2015-2021):** - **知识检索结果**：已查阅知识库，确认数据集中"销售额"对应成交价格 - **指标计算情况**：使用"总成交金额"指标完成计算 **各区成交金额排名（单位：亿元）：** | 排名 | 区域 | 总成交金额(亿元) | |------|------|-----------------| | 1 | 朝阳 | 10349.27 | | 2 | 海淀 | 5850.22 | | 3 | 丰台 | 3411.86 | ...

metric — 指标计算结果

当 Agent 通过指标引擎进行计算时产生。

关键字段：

• message

  message
  — 指标名称描述

• metricDsl

  metricDsl
  — 语义层 DSL（JSON）

• physicalMetricDsl

  physicalMetricDsl
  — 物理层 DSL（JSON）

展示建议：展示指标名称；如面向开发者，可折叠展示 DSL 详情。

实际输出示例：

message: Metric: 过去6年各区总成交金额 metricDsl: { "metricId": { "metricType": "SQL_SIMPLE", "id": 631 }, "name": "过去6年各区总成交金额", "params": [ { "name": "dims", "values": [{ "left": "region" }] }, { "name": "filters", "values": [{ "exprItems": [...] }] } ], "metricDefinition": { "mainTable": "ns10.public.v_gpt_ns10_datagpt_buildin_beijing_house_transaction", "calculationLogic": "SUM(`transaction_price`)" } }

echarts_plus — 图表数据

Agent 生成的可视化图表配置。

关键字段：

• message

  message
  — 图表标题

• chartType

  chartType
  — 图表类型（如 ECHARTS）

• columns

  columns
  — 列定义

• calculateSql

  calculateSql
  — 用于获取图表数据的 SQL

展示建议：用

calculateSql

chartType

实际输出示例：

message: 北京二手房过去6年各区总成交金额 (2015-2021) chartType: ECHARTS columns: 区域 (STRING), 总成交金额(万元) (LONG) calculateSql: SELECT region AS 区域, SUM(transaction_price) AS 总成交金额 FROM ns10.public.v_gpt_ns10_datagpt_buildin_beijing_house_transaction WHERE transaction_date >= '2015.01.01' AND transaction_date <= '2021.01.09' GROUP BY region ORDER BY 总成交金额 DESC

code — 代码块

Agent 生成的代码，通常是 SQL。

关键字段：

• codeType

  codeType
  — 代码语言（如

  sql

  sql
  ）

• code

  code
  — 代码内容

实际输出示例：

codeType: sql code: SELECT region AS 区域, SUM(transaction_price) AS 总成交金额 FROM ns10.public.v_gpt_ns10_datagpt_buildin_beijing_house_transaction WHERE transaction_date >= '2015.01.01' AND transaction_date <= '2021.01.09' GROUP BY region ORDER BY 总成交金额 DESC

message — 普通消息

这是一个"万能"类型，可能包含多种内容。需要根据内容进一步判断。

包含知识详情

当消息中存在

knowledgeData.detailItems

Knowledge details:

Viewed knowledge details:

展示建议：提取知识条目展示，帮助用户了解 Agent 引用了哪些业务规则。

实际输出示例：

source: get_knowledge_detail items: - id=51, keys=北京二手房10年交易数据, value={"desc": "如果问题中没有明确指明时间，就使用昨天"}, type=TEXT - id=52, keys=北京二手房10年交易数据2, value={"desc":"回答中必须有时间范围"}, type=TEXT

包含执行过程

包含

Executing metric calculation:

展示建议：面向开发者的调试界面可展示；面向业务用户建议隐藏。

notify — 进度通知

如"Thinking next step"、"Searching knowledge base"等。

展示建议：可用于显示加载动画中的状态文案，也可完全忽略。

error — 错误

分析过程中出现异常。

展示建议：向用户展示错误信息，建议重试或调整问题。

推荐的展示优先级

如果你只需要向最终用户展示核心结果，推荐按以下顺序筛选和展示：

1. summary — 作为主要展示内容
2. echarts_plus — 配合图表渲染
3. code — SQL 查看（可折叠）
4. metric — 指标详情（可折叠）
5. message（知识类） — 引用知识（可折叠）

其他类型可不展示给最终用户。

实际完整输出样例

以下是一次真实问答（"北京二手房过去6年销售额，按区看"）的关键返回消息：

[response#61] 类型=knowledge 知识检索：已查阅 2 条业务规则 - 规则1：如果问题中没有明确指明时间，就使用昨天 - 规则2：回答中必须有时间范围 [response#93] 类型=执行日志 正在执行指标计算：过去6年各区总成交金额（指标 ID: 631） [response#95] 类型=metric 指标结果：过去6年各区总成交金额 包含 metricDsl 和 physicalMetricDsl [response#99] 类型=code SQL: SELECT region AS 区域, SUM(transaction_price) AS 总成交金额 FROM ... GROUP BY region [response#101] 类型=summary 完整分析总结，包含各区排名表格和核心发现 [response#103] 类型=finish 分析结束

下一步

• 回到 API 概览 查看接口列表
• 查看 SafeQuestionPoll 的完整参数定义