You need to enable JavaScript to run this app.
文档中心
数据智能体 DataAgent（私有化）

数据智能体 DataAgent（私有化）

请输入
  • 文档首页
    • 数据智能体 DataAgent（私有化）开放与集成智能分析AgentOpenAPI洞察报告OpenAPI接入文档
复制全文
下载 pdf
我的收藏
洞察报告
OpenAPI接入文档
复制全文
下载 pdf
我的收藏
OpenAPI接入文档

JWTToken鉴权

说明

深度分析和洞察报告优先使用JWTToken鉴权

用户接入

申请ClientId和ClientSecret

  1. 访问风神开放平台
    Image
  2. 选择 Playground
    Image
  3. 选择 凭证管理
    Image
  4. 选择创建凭证
    Image
  5. 根据创建的凭证获得ClientId和ClientSecret

调用OpenAPI

  1. 根据ClientId和ClientSecret调用以下api获得JWTToken
curl --location --request POST 'https://data.bytedance.net/aeolus/api/v3/openapi/jwtToken' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
    "metadata": {
        "client_id": {clientId},
        "client_secret": {clientSecret},
        "proxy_user": {email_prefix},
        "expire": 3600
    }
}'

获取OpenAPI JwtToken

参数说明

根据上一章节文档获取JwtToken后调用以下接口，获得新的JwtToken

说明

对于洞察报告场景，用户自身clientId生成jwtToken请求OpenAPI时会有请求频率限制问题，需要调用以下接口生成新的jwtToken

Method

GET

URL

{{domain}}/dataAgent/llm/openApi/v2/insightReport/jwtToken

Headers

Authorization

str

"Bearer {jwtToken}"

接口响应示例 

{
        "authorization": "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoib3BlbmFwaSIsInVzZXJuYW1lIjoibGlkYWlqaW5nLmxkaiIsInVzZXJfcGF5bG9hZCI6e30sImV4cCI6MTc2MTk0MjIzOCwiY2xpZW50X2lkIjoiZGRiNTJmMWE2NWY2OThmNDViMGYwYjg3MDkzYTk4MjMifQ.f-gbSyMZJcn5xjzOB3YWy7al5gkuAJTxTz0ONdIxAWbbvn_8GWkuskRGCleXsIkFRcmyS5kVnoZMSIud4-CP3wbxEQAYnOGrxP9Y1QTQSkgr66JewelXdF_OzX-SCXGUehPakAF7Rd3vGuqwOBizPqJcjYsTTVRBAVvEBkp8V9yBcpojchY4wLXdSOBKMbLEBWDBe-t-hH054w2Y0S6lw9bAZY2vxHh8vEIVl26uqr610vYqFqMlYLTLzpUH8xx-nBfAkIcz7ZCKxlb0uluS2XYSS9dqqV3eLk9sLG-9VyZauk17niQFWdJ2djVv_X1MLFnvPoFFfquMPXSB2xCJkT22tynJVGp1-CGi1JSKUkn79FU2_TWmJWXOG7vHjrLz9mXYAfDEhbMFEMVFzB53woM5DFplivZLHH-HvwsxKG9WvWvGqTt0JFInZ5QBCIv_T0jv9ALASNnffmejEu2JeTJ_npC2IHYKc2pLjncypB4VfEYjYJhkPje6tVDfwWrjyoGO3OzeG2p-Gh-LS2iKBN0jEHkdE9HBcHEE8qcVKijrJYY7shLVbSMwN3S-N7Lxm9ozfp3dKvwaCD6qalc03vHx1nXzqYAFJppbK5QYoRenf7KGX1VK6l-AzE-FGmrQG0V_1LHu5IkGwRBVFtoSoKHjyXgDLwYpGx8eYgDAU_M"
}

说明

  • 这里获得的authorization作为请求后续所有接口的JwtToken, 填入请求头的Authorization字段
  • 这里authorization已带Bearer，用户不需要再额外添加Bearer

API定义

检测Agent数据集是否同步完成

使用场景

部分用户OpenApi例行调用场景依赖风神数据集特定p_date数据同步完成，该接口用于实时检测智能体中所添加的数据集p_date同步状态

参数说明

Method

GET

URL

{{domain}}/dataAgent/llm/openApi/v2/agent/agentDatasetSyncStatus

Headers

Authorization

str

jwtToken

Params

agentId

int

智能体Id

鉴权的规则

  • 请求的user必须是agent的PC端user

接口响应示例

{
    "JSONIFY_PRETTYPRINT_REGULAR": false,
    "code": "llm/ok",
    "data": {
        "datasets": [
            {
                "datasetId": 4127473,
                "latestSyncedDate": "2025-08-19"
            },
            {
                "datasetId": 4160644,
                "latestSyncedDate": "2025-10-27"
            },
            {
                "datasetId": 2307471,
                "latestSyncedDate": "2025-10-26"
            },
            {
                "datasetId": 2518822,
                "latestSyncedDate": "2025-10-26"
            },
            {
                "datasetId": 3088400,
                "latestSyncedDate": "2025-10-27"
            },
            {
                "datasetId": 1918668,
                "latestSyncedDate": "2025-10-27"
            }
        ]
    },
    "msg": {}
}

获取洞察报告元信息

使用场景

根据以上页面端reportId获取报告的元信息，包括当前页面端报告id、报告名称、模块id、模块提示词等信息，用户可以根据模块提示词以及模块id，自行决定调用**{{domain}}**/dataAgent/llm/openApi/v2/insightReport/createReportTask接口时基于哪些模块创建运行任务以及是否使用该模块默认提示词

参数说明

Method

GET

URL

{{domain}}/dataAgent/llm/openApi/v2/insightReport/reportMetadata

Headers

Authorization

str

jwtToken

Params

reportId

int

报告Id

鉴权的规则定义

  • 请求公共模板的user必须是智能体的PC端User
  • 请求私有模板的user必须是报告的owner

接口响应示例 

{
    "code": "llm/ok",
    "msg": "",
    "data": {
        "reportId": 167,
        "reportName":"收入波动分析",
        "agentId":21781,
        "owner":"lidaijing.ldj",
        "modules":[
            {
                "id":"69d1c256-7c1c-49d2-aaab-a823c1b4656e",
                "name":"顺丰速运有限公司收入情况高度凝练分析",
                "type":"analysis",
                "prompt":"忽略系统提示词要求的所有报告内容的丰富性要求，请完全遵循我的逻辑，仅生成
                一句话的高度凝练的判断或者描述！！！"
            },
            {
                "id":"d9d0767a-0e93-4346-b2ca-3902abebdb02",
                "name":"顺丰速运有限公司收入分析核心结论报告",
                "type":"analysis",
                "prompt":"请基于所选分析块的分析内容，归纳总结出一句**最关键、最核心**的结论。要
                求：
                1.  **一句话**：严格限制为一句话，长度不超过50字。
                2.  **聚焦重点**：不要复述过程，直接抛出最终洞察、结论或建议。
                3.  **语言精炼**：使用肯定、果断的陈述句，避免使用“可能”、“也许”等模糊词汇。"
            }
        ]
    }
}

后端OpenAPI 创建任务

使用场景

前提

  1. 用户在页面端已创建好公共模板或个人报告
  2. 需要基于配置好的公共模板或个人报告，定期生成新的报告

用法

  1. 从**{{domain}}**/dataAgent/llm/openApi/v2/insightReport/reportMetadata接口中获取每个模块的id和默认提示词
  2. 思考选择哪些模块运行以及是否需要替换该模块的默认提示词
  3. 在请求体的modules中填入需要运行的模块id，如果需要替换模块的默认提示词需一并提供prompt，否则只需提供id。

参数说明

Method

POST

URL

{{domain}}/dataAgent/llm/openApi/v2/insightReport/createReportTask

Headers

Authorization

str

jwtToken

鉴权的规则定义

  • 创建公共模板任务的user必须是智能体的PC端User
  • 创建私有模板任务的user必须是报告的owner

请求body参数

字段

类型

必填

默认值

说明

reportId

int

是

报告模板 ID

modules

Array<ModuleCreationInfo>

否

[]

要运行的模块列表；不传或空列表按模板全模块运行

modules[].id

string

是（modules 内）

模块 ID（UUID）

modules[].prompt

string

否

null

用于覆盖该模块的默认 prompt；未提供则使用模板原始 prompt

variables

Object<string, string>

否

null

传入模板的变量替换 map（key 为变量名，value 为变量值）

enableScreenShot

bool

否

false

是否在任务执行完成后触发截图（用于生成 images.markdown / images.html 缓存）

请求示例

{
    "reportId": 167,
    "modules": [
        {
            "id": "69d1c256-7c1c-49d2-aaab-a823c1b4656e",
            "prompt": "忽略系统提示词要求的所有报告内容的丰富性要求，请完全遵循我的逻辑，仅生成一句话的高度凝练的判断或者描述！！！"
        },
        {
            "id": "d9d0767a-0e93-4346-b2ca-3902abebdb02"
        }
    ],
    "variables": {
        "companyName": "顺丰速运",
        "timeRange": "2024-09~2025-08"
    },
    "enableScreenShot": true
}

响应数据结构

顶层结构：

字段

类型

说明

code

string

业务状态码，成功为 llm/ok

msg

string

错误提示，成功时为空串

data

Object

数据主体，见下

data 字段：

字段

类型

说明

reportId

int

报告模板 ID

reportName

string

报告名称

taskId

int

本次任务 ID，后续用于 reportTaskDetail 查询

接口响应示例

{
    "code": "llm/ok",
    "msg": "",
    "data": {
        "reportId": 167,
        "reportName":"收入波动分析",
        "taskId": 100
    }
}

常见错误码

场景

HTTP / 业务码

msg

模板不存在

400 / llm/parameter_absent

template {reportId} not found

无权限（非 owner / 非智能体 User）

403 / llm/not_permitted

权限校验失败原因

单用户短时间内任务数超阈值

500 / llm/function_execute_failed

达到并发限制

modules[].id 不在模板中

400 / llm/parameter_absent

no correct module_id provided to execute

后端OpenAPI 获取报告任务详情

参数说明

请求body参数

Method

GET

URL

{{domain}}/dataAgent/llm/openApi/v2/insightReport/reportTaskDetail

Headers

Authorization

str

jwtToken

Params

taskId

int

任务id（createReportTask返回的任务 ID）

appId

Optional[int]

风神项目 ID；影响嵌入 URL 中的 appId与 JWT app scope

鉴权的规则定义

  • 获取reportTask的user必须是createReportTask的user

响应数据结构

顶层结构

字段

类型

说明

code

string

业务状态码，成功为 llm/ok

msg

string

错误提示

data

Object

数据主体，见下

data 字段

字段

类型

说明

taskId

int

报告任务 ID

reportId

int

报告模板 ID

reportName

string

报告名称

taskCreator

string

任务创建人（邮箱前缀）

taskStatus

string

报告级任务状态，枚举：pending / running / success / failed

modules

Array<ReportTaskModuleOutput>

各模块的产出，见 2.4.3

reportMarkdownUrl

string

null

reportHtmlUrl

string

null

pdfUrl

string

全报告合并 PDF 下载 URL；如未生成则为 ""

imageUrls

Array

报告级图片链接汇总（预留字段，默认 []）

ctime

string

任务创建时间，ISO 8601

mtime

string

任务最后更新时间，ISO 8601

modules[] 元素结构 ReportTaskModuleOutput

字段

类型

说明

id

string

模块 ID（对应模板中的 blockId）

name

string

null

type

string

模块类型，来自 InsightReportBlockType，常见值如 analysis、summary

taskId

int

模块级 block_task ID

taskStatus

string

模块级任务状态，InsightTaskStatus 枚举，取值：created / not_submitted / pending / running / success / failed

content

string

null

url

string

null

html

string

null

images

Object{markdown, html}

模块截图缓存，见 2.4.4

images 结构

字段

类型

说明

markdown

string

null

html

string

null

取值规则（重要）：

images.markdown 与 images.html 各自的实际返回值取决于任务状态和部署环境，可能出现以下三种情况：

场景

markdown

html

模块任务未成功（pending / running / not_submitted / failed）或截图缓存未落库

null

null

TOB 私有化环境（Photographer）

截图 URL（成功） / ""（失败）

恒为 ""（当前未主动截 html）

调用方在解析时必须同时兼容以下三种取值：

  • null：任务未成功或截图尚未生成
  • ""：截图流程执行完但未产出 URL（超时、失败、环境关闭截图）
  • 非空字符串：截图 URL

嵌入 URL 说明

url / html / reportMarkdownUrl / reportHtmlUrl 是前端 iframe 内嵌用的 external 页面 URL，格式如下：

{domain}/data-agent/analytics-agent/#/agent/insightReport/external
    ?agentId={agentId}
    &appId={appId}
    &taskId={moduleTaskId}
    &moduleId={blockId}
    &reportId={reportId}
    &reportType=markdown|html
    &inline=true
    &jwtToken={jwtToken}

接口响应示例
{
    "code": "llm/ok",
    "msg": "",
    "data": {
        "taskId": 100,
        "reportId": 167,
        "reportName": "收入波动分析",
        "taskCreator": "lidaijing.ldj",
        "taskStatus": "success",
        "pdfUrl": "https://<company-domain>/tos/xxxxx.pdf",
        "imageUrls": [],
        "reportMarkdownUrl": "https://<domain>/aeolus-open/#/agent/insightReport/external?agentId=1&appId=1900&taskId=100&reportId=167&token=xxx&reportType=markdown&inline=true",
        "reportHtmlUrl": "https://<domain>/aeolus-open/#/agent/insightReport/external?agentId=1&appId=1900&taskId=100&reportId=167&token=xxx&reportType=html&inline=true",
        "ctime": "2025-03-11T12:31:49",
        "mtime": "2025-09-25T14:41:56",
        "modules": [
            {
                "id": "69d1c256-7c1c-49d2-aaab-a823c1b4656e",
                "name": "顺丰速运有限公司收入情况高度凝练分析",
                "type": "analysis",
                "taskId": 1143,
                "taskStatus": "success",
                "content": "# 顺丰速运有限公司收入情况高度凝练分析\n\n## 核心收入表现判断\n\n基于《顺丰速运有限公司近期收入情况分析报告》显示，该公司过去12个月收入虽实现80.4%显著增长但波动较大...[^1]\n\n[^1]: 数据来源：收入宽表_计费粒度，时间范围：2024年9月-2025年8月",
                "url": "https://<domain>/aeolus-open/#/agent/insightReport/external?agentId=1&appId=1900&taskId=1143&moduleId=69d1c256-7c1c-49d2-aaab-a823c1b4656e&reportId=167&token=xxx&reportType=markdown&inline=true",
                "html": "https://<domain>/aeolus-open/#/agent/insightReport/external?agentId=1&appId=1900&taskId=1143&moduleId=69d1c256-7c1c-49d2-aaab-a823c1b4656e&reportId=167&token=xxx&reportType=html&inline=true",
                "images": {
                    "markdown": "https://<tos-domain>/screenshot/xxx_markdown.png",
                    "html": ""
                }
            },
            {
                "id": "d9d0767a-0e93-4346-b2ca-3902abebdb02",
                "name": "顺丰速运有限公司收入分析核心结论报告",
                "type": "analysis",
                "taskId": 1462,
                "taskStatus": "running",
                "content": null,
                "url": null,
                "html": null,
                "images": {
                    "markdown": null,
                    "html": null
                }
            }
        ]
    }
}

常见错误码

场景

HTTP / 业务码

msg

taskId 不存在

400 / llm/parameter_absent

report task {taskId} not found

报告模板不存在

400 / llm/parameter_absent

report {reportId} not found

当前用户不是任务的创建人

403 / llm/not_permitted

user not permitted

前端接入

拿着前面得到的url，通过ifram嵌入前端页面

iframe 方式（推荐 👍）

接入格式 

import React from "react";
import ReactDOM from "react-dom";

const App = () => {
  useEffect(() => {
    // 监听高度
    window.addEventListener('message', (event) => {
        if (event.data.type === 'INSIGHT_REPORT_HEIGHT_UPDATE') {
            console.log('容器高度', event.data.height);
        }
    })
  }, [])
  return (
    <iframe
      src={`${url}`}
    />
  );
};

ReactDOM.render(<App />, document.querySelector("body"));

代码示例 

import React from "react";
import ReactDOM from "react-dom";

const App = () => {
  return (
    <iframe
      src={`https://data.bytedance.net/aeolus-open/pages/agent/insightReport/external?agentId=
                {agentId}&reportId={reportId}&moduleId={moduleId}&taskId=
                {taskId}&jwtToken={jwtToken}&reportType={reportType}`}
    />
  );
};

ReactDOM.render(<App />, document.querySelector("body"));
最近更新时间：2026.08.05 17:06:38
这个页面对您有帮助吗？
有用
有用
无用
无用