流式对话（SSE）

更新时间：2026-10-23

接口描述

向指定 Agent 发起流式对话，通过 Server-Sent Events（SSE）实时接收 Agent 的思考过程、工具调用、最终回答等事件。

响应格式：Content-Type: text/event-stream
首个事件固定为 session_id，用于标识当前会话；
推荐传入“创建 Agent”接口返回的 session_id；传入已有 session_id 时继续该会话的多轮对话。

请求结构

Plain Text

1POST /v2/workspaces/{workspaceId}/dataagent/agents/{agentId}/stream

路径参数

参数名	类型	是否必填	说明
`workspaceId`	string	是	工作空间 ID
`agentId`	string	是	Agent ID

请求 Body

参数名	类型	是否必填	说明
`query`	string	是	用户问题
`session_id`	string	否	会话 ID；建议使用“创建 Agent”接口返回值，格式如 `session_1735000000000_a3f2b9`
`timeout_sec`	int	否	超时秒数，默认 `120`，最大 `300`
`mode`	string	否	分析模式：`auto`（默认）/ `analysis` / `ide`
`model_override`	string	是	覆盖 Agent 默认模型，仅对本次对话生效
`temperature_override`	float	否	覆盖 Agent 默认温度，仅对本次对话生效
`reasoning_effort`	string	否	推理强度覆盖：`off` / `low` / `medium` / `high`
`selected_ontology`	string[]	否	本次对话额外指定的本体类型列表
`selected_functions`	string[]	否	本次对话额外指定的 Logic Function 列表
`selected_datasearches`	string[]	否	本次对话额外指定的 DataSearch 列表
`selected_skills`	SelectedSkillRef[]	否	本次对话允许 Agent 使用的 Skill 发布版本列表
`invoked_skills`	SelectedSkillRef[]	否	本次对话由用户显式调用的 Skill 发布版本列表
`tools_runtime`	object[]	否	工具运行时配置
`config`	object	否	Agent 运行配置
`notepad_content`	string	否	对话上下文便签内容

SelectedSkillRef 结构

字段	类型	是否必填	说明
`skillId`	string	是	Skill ID
`releaseId`	string	是	当前可执行的发布版本 ID，应取自“查询可执行 Skill 列表”接口

请求示例

                Bash
                
            

                curl -X POST \
  'https://{host}/databuilder/api/databuilder/v2/workspaces/workspace_9862_0763f283d58a/dataagent/agents/default/stream' \
  -H 'Content-Type: application/json' \
  -H 'X-App-Id: dataagent-service' \
  -H 'Authorization: <签名串>' \
  -d '{
    "query": "最近30天各省份订单量排行",
    "session_id": "session_1735000000000_a3f2b9",
    "timeout_sec": 120,
    "mode": "auto",
    "reasoning_effort": "medium",
    "selected_ontology": ["User", "Order"],
    "selected_functions": ["query_order_summary"],
    "selected_datasearches": ["search_order_detail"],
    "selected_skills": [
      {
        "skillId": "skill_abc123",
        "releaseId": "release_def456"
      }
    ]
  }'
            

响应示例

成功（HTTP 200）

响应头：

Plain Text

1Content-Type: text/event-stream
2Cache-Control: no-cache
3Connection: keep-alive
4X-Accel-Buffering: no

SSE 事件流格式：每条事件以 data: {json}\n\n 分隔，首条为 event: session_id。

事件类型说明

`type` 值	触发时机	关键字段
(首条) `event: session_id`	连接建立后立即推送	`data` 为 session_id 字符串
`content`	LLM 生成文本时实时推送	`content`（string）：增量文本片段
`reasoning`	LLM 推理 token（thinking 模式）	`content`（string）：推理文本片段
`step`	Agent 完成一次工具调用	见 StepTrace 结构
`step_update`	工具调用观测值更新	`step.step_id`、`step.observation`、`step.observation_tokens`、`step.duration_ms`
`interrupt`	HITL 人工干预触发	见 InterruptState 结构
`final`	Agent 本轮对话结束	`final`（Markdown 字符串）、`turn_usage`、`lineage_graph`
`error`	Agent 执行出错	`step.raw`（错误描述字符串）
`stream_complete`	SSE 流正常结束	`status: "success"`

StepTrace 结构

字段	类型	说明
`step_id`	string	步骤 ID，如 `step_1`
`tool_call_id`	string	LLM 工具调用 ID
`thought`	string	LLM 推理过程描述
`tool_name`	string	调用的工具名称
`tool_input`	string	工具入参（JSON 字符串）
`observation`	string	工具执行结果（JSON 字符串）
`input_tokens`	int	本步骤输入 token 数
`output_tokens`	int	本步骤输出 token 数
`duration_ms`	int	本步骤总耗时（毫秒）
`llm_duration_ms`	int	LLM 调用耗时（毫秒）
`tool_duration_ms`	int	工具调用耗时（毫秒）

InterruptState 结构

字段	类型	说明
`interrupt_id`	string	中断事件 ID
`type`	string	中断类型：`before_tool` / `after_tool` / `before_final`
`tool_name`	string	触发中断的工具名称
`tool_input`	string	工具入参（JSON 字符串）
`thought`	string	LLM 触发中断前的思考内容
`prompt`	string	提示用户的说明文字
`allow_modify`	bool	是否允许修改工具入参
`question`	string	仅 `type=before_final` 时，ClarifyQuestion 问题内容
`options`	object[]	澄清选项列表，每项含 `label` 和 `description`
`allow_custom_input`	bool	澄清时是否允许用户自由输入
`expires_at`	string	中断过期时间（ISO 8601），超时后自动继续

turn_usage 结构

字段	类型	说明
`total_input_tokens`	int	本轮总输入 token 数（含 system prompt + history）
`total_output_tokens`	int	本轮总输出 token 数
`tool_input_tokens`	int	工具调用输入 token 数
`observation_tokens`	int	工具执行结果 token 数
`thought_tokens`	int	推理 token 数
`llm_duration_ms`	int	LLM 累计调用耗时（毫秒）
`tool_duration_ms`	int	工具累计调用耗时（毫秒）
`elapsed_ms`	int	本轮对话总耗时（毫秒）
`step_count`	int	工具调用步骤总数

lineage_graph 结构

字段	类型	说明
`session_id`	string	会话 ID
`nodes`	object[]	数据血缘节点，含 `id`、`type`（datasource/operation/result）、`label`、`turn_id`
`edges`	object[]	节点连接关系，每项含 `from`、`to`
`outline`	object[]	分析摘要大纲，每项含 `type`、`text`、`node_id`

SSE 事件流示例

Plain Text

1event: session_id
2data: session_1735000000000_a3f2b9
3
4data: {"type":"content","content":"正在分析"}
5
6data: {"type":"step","step":{"step_id":"step_1","tool_call_id":"call_abc123","thought":"需要按省份统计订单量","tool_name":"OntologyAggregation","tool_input":"{\"object_type\":\"Order\",\"group_by\":\"province\",\"metric\":\"count\"}","observation":"{\"result\":[{\"province\":\"广东\",\"count\":15432},...]}","input_tokens":3200,"output_tokens":85,"duration_ms":1543,"llm_duration_ms":980,"tool_duration_ms":563}}
7
8data: {"type":"final","final":"## 最近30天各省份订单量排行\n\n| 排名 | 省份 | 订单量 |\n|---|---|---|\n| 1 | 广东 | 15,432 |...","turn_usage":{"total_input_tokens":12450,"total_output_tokens":892,"elapsed_ms":8756,"step_count":3},"lineage_graph":{"session_id":"session_1735000000000_a3f2b9","nodes":[...],"edges":[...]}}
9
10data: {"type":"stream_complete","status":"success"}

错误码

HTTP 状态码	错误码	说明
400	`BadRequest`	query 为空或请求参数不合法
400	`DataAgentResourceNotBound`	工作空间资源未绑定
404	`NotFound`	Agent 不存在
500	`InternalServerError`	流式推送不支持或服务内部错误

注意：SSE 连接建立后（响应头已 flush），运行时错误以 {"type":"error","step":{"raw":"..."}} 事件推送，HTTP 状态码仍为 200。

评价此篇文章

有帮助没帮助

更新 Agent

非流式对话

百度智能云

百度胜算

百度胜算

流式对话（SSE）

接口描述

请求结构

路径参数

请求 Body

SelectedSkillRef 结构

请求示例

响应示例

事件类型说明

StepTrace 结构

InterruptState 结构

turn_usage 结构

lineage_graph 结构

SSE 事件流示例

错误码