You need to enable JavaScript to run this app.
导航
数据智能体
  • 文档首页
    • /数据智能体/开放与集成/智能分析Agent/OpenAPI/智能分析Agent Open API
智能分析Agent Open API
最近更新时间：2025.06.09 18:25:52首次发布时间：2025.04.28 19:57:38
我的收藏
有用
有用
无用
无用

概述

本文为您介绍的是智能分析Agent的Open API，您将了解到如何通过 API 让智能体使用自然语言查询数据。
注意：在您使用本文所述的 API 前，还需完成接入 JWT-Token 和申请 Token 的前置操作及提前配置好智能体，请先了解调用方式，详情可阅读调用方式。

接口

飞书智能体使用自然语言查询数据

请求说明

请求方式：POST
请求地址： https://{domain}/aeolus/llm/openApi/v2/chatbi/query

请求参数

参数

类型

是否必选

示例值

描述

question

string

是

10月20日有多少文章

问题

chatId

string

否

100000

如果是独立问题，可不传；如果是多轮对话需上传会话 ID，同一个会话ID视为统一会话，获取方式见说明

agentId

int

是

1000

智能体 ID，获取方式见说明

imageFormat

string

是

lark_fragment

指定返回的查询结果中图表的格式类型：

  • lark_fragment：飞书格式富文本
  • image_url：图片url地址
  • ark_image_key：飞书图片key
  • vchart_schema：vchart图表配置

注意

因环境可能会出现图片生成服务未 ready 的情况，为了防止出错，建议"imageFormat"字段传入固定值"lark_fragment"。

说明

APPID和AGENT_ID获取方式见智能体网页链接：
Image

请求示例

{
    "question": "10月20日有多少文章",    // 问题，必填
    "chatId": "100000",    // 会话ID，同一个chatId视为多轮对话，如果是独立问题，可不传
    "agentId": 1000,   // 智能体ID
    "imageFormat": "lark_fragment"  // 传入该值
}

返回参数

参数

类型

示例值
描述

charts

array

Image

返回的查询结果图表。通常会根据您的查询问题返回不同类型的图表，例如折线图、柱状图等，返回结果的第一个图表为推荐的图表，更便于做查询结果分析。

  • 以界面化的查询为例，图表结果类似：
    Image
  • 支持类型包括：
    • "column_parallel"：柱状图
    • "combination"：组合图
    • "line"：折线图
    • "pie"：饼图
    • "measure_card"：指标卡
    • "table" ：表格

dataSetUrl

string

https://数据集网址

智能体所配置数据集的链接

meta

array

Image

结果字段描述信息，可以理解为表头，其中 role 参数表明该查询结果字段角色，measure 为指标，dimension 为维度。

queryHistory

string

https://网址

sql查看地址

rows

array

[ // 查询数据结果
[
369251756
]
]

结果数据

sql

string

SELECT (count(*)) AS article_count FROM event_online WHERE (1702552137_日期) = ('2024-10-20') LIMIT 1000

查询sql

thought_process

string

模型的输出信息

模型的思考过程

返回示例

{
    "code": "llm/ok", // 状态码
    "data": {
        "charts": [ //图表类型
            {
                "chartType": "measure_card",    
                "image": "",
                "imageLarkKey": null,
                "larkFragment":"{\"tag\": \"column_set\", \"flex_mode\": \"stretch\", \"background_style\": \"grey\", \"horizontal_spacing\": \"default\", \"columns\": [{\"tag\": \"column\", \"width\": \"weighted\", \"weight\": 1, \"elements\": [{\"tag\": \"markdown\", \"text_align\": \"left\", \"content\": \"article_count(\文\章\数\量):\\n**369251756**\"}]}]}"
            },
            {
                "chartType": "table",
                "image": "",
                "imageLarkKey": null,
                "larkFragment":"{\"tag\": \"table\", \"page_size\": 6, \"row_height\": \"32px\", \"custom_tag\": \"chart_type_table\", \"header_style\": {\"bold\": true, \"background_style\": \"grey\", \"text_size\": \"normal\", \"row_height\": \"middle\", \"lines\": 2}, \"columns\": [{\"name\": \"173329985\", \"display_name\": \"article_count(\文\章\数\量)\", \"data_type\": \"text\"}], \"rows\": [{\"1733765\": \"36926\"}]}"
            }
        ],
        "dataSetUrl": "https://网址",// 数据集链接
        "meta": [// 查询结果字段列表
            {
                "dataType": "int", //字段类型
                "name": "article_count(文章数量)", //字段名称
                "role": "measure" //指标 或 维度
            }
        ],
        "queryHistory": "https://data.", //sql查看地址
        "rows": [ // 查询数据结果
            [
                369251756
            ]
        ],
        "sql": "  SELECT  (count(*)) AS article_count  FROM `event_online`     WHERE (`170252137_日期`) = ('2024-10-20')      LIMIT 1000   " //查询sql,
        "thought_process":"用户想了解今年的xx情况。根据数据集定义，我们需要筛选出今年的数据，并展示xx的相关指标。...."
    },
    "msg": {} //额外信息
}

PC智能体使用自然语言查询数据

请求说明

请求方式：POST
请求地址： https://{domain}/aeolus/llm/openApi/v2/ada/query

请求参数

参数

类型

是否必选

示例值

描述

question

string

是

10月20日有多少文章

问题

chatId

string

如果是独立问题，可不传

100000

会话 ID，同一个 chatId 视为多轮对话

agentId

int

是

1000

智能体 ID

questionSource

string

是

openapi

表明问题来源，固定值为openai

imageFormat

string

是

lark_fragment

指定返回的查询结果中图表的格式类型：

  • lark_fragment：飞书格式富文本
  • image_url：图片url地址
  • ark_image_key：飞书图片key
  • vchart_schema：vchart图表配置

注意

因环境可能会出现图片生成服务未 ready 的情况，为了防止出错，建议"imageFormat"字段传入固定值"lark_fragment"。

stream

bool

否

true

是否启用流式输出

  • true：表示启用流式输出，智能体将返回中间结果，系统将以实时、连续的方式输出查询结果。
  • false：表示不启用流式输出，智能体将以批量的方式输出最终查询结果。

请求示例

{
    "question": "昨天的原始调用量是多少",
    "agentId": 1,
    "questionSource":"openapi",
    "imageFormat": "lark_fragment",  // 传入该值
    "stream": true
}

返回参数

参数

类型

示例值

描述

sub_id

int

0

子查询ID，openapi不支持拆分查询，sub_id只有0

type

string

thought

block的类型

  • thought：智能体思考内容
  • code：智能体查询的sql代码
  • result：智能体输出的查询结果

content

string

的问题

当type字段为thought/code时，返回的正文内容

status

string

processing

当type字段为result时，输出当前状态

  • processing：处理中
  • success：代表执行成功，但不代表全部完成
  • completed：表示全部完成，并一次性返回查询结果

result

object

0

当type字段为result时，输出查询结果，reault的字段说明见下表

result 字段说明如下：

参数

类型

示例值
描述

charts

array

Image

返回的查询结果图表。通常会根据您的查询问题返回不同类型的图表，例如折线图、柱状图等，返回结果的第一个图表为推荐的图表，更便于做查询结果分析。

  • 以界面化的查询为例，图表结果类似：
    Image
  • 支持类型包括：
    • "column_parallel"：柱状图
    • "combination"：组合图
    • "line"：折线图
    • "pie"：饼图
    • "measure_card"：指标卡
    • "table" ：表格

dataSetUrl

string

https://数据集网址

数据集链接

meta

array

Image

结果字段描述信息，可以理解为表头，其中 role 参数表明该查询结果字段角色，measure 为指标，dimension 为维度。

queryHistory

string

https://

sql查看地址

rows

array

[ // 查询数据结果
[
369
]
]

结果数据

sql

string

SELECT (count(*)) AS article_count FROM Perfu.aeolus_event_online WHERE (1700052552137_日期) = ('2024-10-20') LIMIT 1000

查询sql

knowledge

string

"\n\n提示：\n1. 指标相互独立，不同不可相加\n"

用到的知识信息

sessioinId

int

53332234

会话id

sessioinUrl

string

https://会话的网址链接

会话url

recallFieldInfo

array

Image

召回的字段列表

返回示例

非流式返回示例

{
    "JSONIFY_PRETTYPRINT_REGULAR": false,
    "code": "llm/ok",
    "data": {
        "charts":  [ //图表类型
            {
                "chartType": "measure_card",    
                "image": "",
                "imageLarkKey": null,
                "larkFragment":"{\"tag\": \"column_set\", \"flex_mode\": \"stretch\", \"background_style\": \"grey\", \"horizontal_spacing\": \"default\", \"columns\": [{\"tag\": \"column\", \"width\": \"weighted\", \"weight\": 1, \"elements\": [{\"tag\": \"markdown\", \"text_align\": \"left\", \"content\": \"article_count(\文\章\数\量):\\n**369251756**\"}]}]}",
                "vchart_schema":"{}"
            },
            {
                "chartType": "table",
                "image": "",
                "imageLarkKey": null,
                "larkFragment":"{\"tag\": \"table\", \"page_size\": 6, \"row_height\": \"32px\", \"custom_tag\": \"chart_type_table\", \"header_style\": {\"bold\": true, \"background_style\": \"grey\", \"text_size\": \"normal\", \"row_height\": \"middle\", \"lines\": 2}, \"columns\": [{\"name\": \"1733299899765\", \"display_name\": \"article_count(\文\章\数\量)\", \"data_type\": \"text\"}], \"rows\": [{\"1733299899765\": \"369251756\"}]}",
                "vchart_schema":"{}"
            }
        ],
        "dataSetId": 3231942,
        "dataSetUrl": "",
        "knowledge": "\n\n提示：\n1. 指标相互独立，不同不可相加\n",
        "meta": null,
        "originalCode": "\n# 编写SQL查询\nsql = \"\"\"\nSELECT \n    SUM(`免费量`) AS 总免费量,\n    SUM(`原始量`) AS 总原始量,\n    SUM(`付费量`) AS 总付费量\nFROM 数据集\nWHERE YEAR(`日期`) = YEAR(CURRENT_DATE);\n\"\"\"\n\n# 执行SQL查询并获取结果\ndf = execute_sql(sql, max_rows=1000)\n\n# 输出结果\nanswer(df)\n\n    ",
        
        "queryHistory": "",
        "recallFieldInfo": [
            {
                "descr": null,
                "fieldName": "`客户`",
                "id": 17000641168,
                "mapType": 0,
                "type": "string"
            }
        ],
        "rows": [[100000]],
        "sessionId": 5652519,
        "sessionUrl": "https://网址",
        "sql": "\n# 编写SQL查询\nsql = \"\"\"\nSELECT \n    SUM(`免费量`) AS 总免费量,\n    SUM(`原始量`) AS 总原始量,\n    SUM(`付费量`) AS 总调用量\nFROM 数据集\nWHERE YEAR(`日期`) = YEAR(CURRENT_DATE);\n\"\"\"\n\n# 执行SQL查询并获取结果\ndf = execute_sql(sql, max_rows=1000)\n\n# 输出结果\nanswer(df)\n\n    ",
        "sqlList": [],
        "thought": {
            "columns": [],
            "dimensions": [],
            "filters": [],
            "metrics": [],
            "redactedCode": ""
        }
    },
    "msg": {}
}

流式返回示例

data: {"sub_id": 0, "type": "thought", "content": ""}
data: {"sub_id": 0, "type": "thought", "content": "用户"}
data: {"sub_id": 0, "type": "thought", "content": "的问题"}
data: {"sub_id": 0, "type": "thought", "content": "是"}
data: {"sub_id": 0, "type": "thought", "content": "询"}
data: {"sub_id": 0, "type": "thought", "content": "问"}

......

data: {"sub_id": 0, "type": "code", "content": ");"}
data: {"sub_id": 0, "type": "code", "content": "\n"}
data: {"sub_id": 0, "type": "code", "content": ""}
data: {"sub_id": 0, "type": "result", "status": "processing", "msg": "processing", "result": {}}
data: {"sub_id": 0, "type": "result", "status": "success", "msg": "success", "result": {"historyId": 1446196}}
data: {"sub_id": 0, "type": "result", "status": "completed", "result": {"data_set_id": null, "sql": "\n# \u7f16\u5199SQL\u67e5\u8be2\nsql = \"\"\"\nSELECT \n    SUM(`\u539f\u59cb\u8c03\u7528\u91cf`) AS `\u6628\u65e5\u539f\u59cb\u8c03\u7528\u91cf`\nFROM \n    \u6570\u636e\u96c6\nWHERE \n    `\u8c03\u7528\u65e5\u671f` = DATE_SUB(CURRENT_DATE, INTERVAL 1 DAY);\n\"\"\"\n\n# \u6267\u884cSQL\u67e5\u8be2\u5e76\u83b7\u53d6\u7ed3\u679c\ndf = execute_sql(sql, max_rows=1000)\n\n# \u8f93\u51fa\u7ed3\u679c\nanswer(df)\n\n    ", "thought": {"columns": ["\u6628\u65e5\u539f\u59cb\u8c03\u7528\u91cf"], "dimensions": [], "metrics": ["\u6628\u65e5\u539f\u59cb\u8c03\u7528\u91cf"], "filters": ["\u8c03\u7528\u65e5\u671f(\u7b49\u4e8e\u6628\u65e5)", "p_date(\u7b49\u4e8e2025-05-07)", "\u4e3b\u5ba2\u6237\u7b49\u7ea7(\u4e0d\u7b49\u4e8e'\u5185\u90e8\u5ba2\u6237'\u6216\u4e3a\u7a7a)", "\u8c03\u7528\u65e5\u671f(\u5927\u4e8e\u7b49\u4e8e2024-03-01)", "\u9650\u52361000\u6761"], "redacted_code": ""}, "thought_process": "\u7528\u6237\u7684\u95ee\u9898\u662f\u8be2\u95ee\u6628\u5929\u7684\u539f\u59cb\u8c03\u7528\u91cf\u3002\u6211\u4eec\u9700\u8981\u4ece\u6570\u636e\u96c6\u4e2d\u7b5b\u9009\u51fa\u8c03\u7528\u65e5\u671f\u4e3a\u6628\u5929\u7684\u6570\u636e\uff0c\u5e76\u5bf9\u5b57\u6bb5 `\u539f\u59cb\u8c03\u7528\u91cf` \u8fdb\u884c\u6c47\u603b\uff08SUM\uff09\u3002\u6628\u5929\u7684\u65e5\u671f\u53ef\u4ee5\u901a\u8fc7\u5f53\u524d\u65e5\u671f\u51cf\u53bb\u4e00\u5929\u6765\u8ba1\u7b97\u3002\n", "rows": [[1231866173336]], "meta": [{"name": "\u6628\u65e5\u539f\u59cb\u8c03\u7528\u91cf", "dataType": "float", "role": "measure"}], "charts": [{"chartType": "measure_card", "image": "https://tosv.byted.org/obj/davinci-render-output/da911f72-cad0-436d-afcb-dee07cf74e68"}, {"chartType": "table", "image": "https://tosv.byted.org/obj/davinci-render-output/82e1a6b1-1f06-4adb-bef4-a3e640c25333"}], "data_set_url": "", "query_history": "", "chart_html": "\n        <html>\n            <head>\n                <meta http-equiv=\"content-type\" content=\"text/html; charset=utf-8\" />\n            </head>\n        <body>\n            <div style='overflow:auto'>\n            \n                <div style='float:left;width:400px;padding:20'>\n                    <p style='text-align:center'>\n                    measure_card (\u9ed8\u8ba4)\n                    </p>\n                    <img src='https://tosv.byted.org/obj/davinci-render-output/da911f72-cad0-436d-afcb-dee07cf74e68' width='400px' />\n                </div>\n                \n\n                <div style='float:left;width:400px;padding:20'>\n                    <p style='text-align:center'>\n                    table\n                    </p>\n                    <img src='https://tosv.byted.org/obj/davinci-render-output/82e1a6b1-1f06-4adb-bef4-a3e640c25333' width='400px' />\n                </div>\n                \n            </div>\n        </body>\n        ", "prompts": [], "sql_list": [{"origin_sql": "\nSELECT \n    SUM(`\u539f\u59cb\u8c03\u7528\u91cf`) AS `\u6628\u65e5\u539f\u59cb\u8c03\u7528\u91cf`\nFROM \n    \u6570\u636e\u96c6\nWHERE \n    `\u8c03\u7528\u65e5\u671f` = DATE_SUB(CURRENT_DATE, INTERVAL 1 DAY);\n", "rewrite_sql": "  SELECT  (`1700060687188_\u539f\u59cb\u8c03\u7528\u91cf`) AS `\u6628\u65e5\u539f\u59cb\u8c03\u7528\u91cf`  FROM `\u706b\u5c71\u5f15\u64ce\u7ecf\u8425\u7ba1\u7406.\u884c\u4e1a\u8c46\u5305\u5927\u6a21\u578b\u8c03\u7528\u805a\u5408 for \u667a\u80fd\u4f53`     WHERE ( (`1700060687218_\u8c03\u7528\u65e5\u671f`) = ((date_sub(to_date(today()), INTERVAL 1 DAY))) ) AND (to_date(`1700060687175_p_date`) = '2025-05-07') AND (((`1700060687225_\u4e3b\u5ba2\u6237\u7b49\u7ea7`) != ('\u5185\u90e8\u5ba2\u6237')) or ((`1700060687225_\u4e3b\u5ba2\u6237\u7b49\u7ea7`) IS NULL)) AND ((`1700060687218_\u8c03\u7528\u65e5\u671f`) >= ('2024-03-01'))      LIMIT 1000   "}], "recall_field_info": {}, "original_code": "\n# \u7f16\u5199SQL\u67e5\u8be2\nsql = \"\"\"\nSELECT \n    SUM(`\u539f\u59cb\u8c03\u7528\u91cf`) AS `\u6628\u65e5\u539f\u59cb\u8c03\u7528\u91cf`\nFROM \n    \u6570\u636e\u96c6\nWHERE \n    `\u8c03\u7528\u65e5\u671f` = DATE_SUB(CURRENT_DATE, INTERVAL 1 DAY);\n\"\"\"\n\n# \u6267\u884cSQL\u67e5\u8be2\u5e76\u83b7\u53d6\u7ed3\u679c\ndf = execute_sql(sql, max_rows=1000)\n\n# \u8f93\u51fa\u7ed3\u679c\nanswer(df)\n\n    ", "knowledge": null}}