ChatUserSecAgent - 与用户安全智能体流式对话

更新时间:
复制 MD 格式

与当前账号的用户安全智能体进行对话,通过 SSE 事件流接收处理过程与结果。

接口说明

本接口用于控制台向用户安全智能体发送对话请求,并以 SSE 事件流接收处理过程、表单和结果。

会话与轮次:

  • 新会话:调用方生成 SessionId 和 TalkId,填写非空 Prompt。

  • 同一会话追问:复用 SessionId,为每次新的提问生成新的 TalkId。

  • 提交或取消表单:Prompt 传空字符串,UserInputInfo 传入 JSON 对象字符串,包含 sessionId、talkId、formId、formValues 和 formAction;顶层 SessionId、TalkId 与表单内部身份保持一致。

  • Questions 表单通过 submit 提交答案、cancel 取消;PolicyApproval 表单通过 approve 批准、deny 拒绝或 cancel 取消。

参数编码:

  • UserInputInfo 和 ExtraParams 按 JSON 对象字符串传入。

  • Attachments 按 JSON 数组字符串传入;控制台先上传附件,再使用上传返回的 OSS 对象标识。

  • 控制台前端通过 ExtraParams 中的 execution_mode 和 target 传递执行模式和目标。

响应处理: 设置 Stream=true 后,持续读取 SSE 帧并解析 data 中的 JSON。控制消息通过 type 字段区分;A2UI 消息通过 a2ui 字段承载界面指令。dispatch 表示执行分派确认,不表示文本增量;调用方按接收顺序处理 A2UI 消息,收到 type=done 表示本次流结束。网络断开本身不代表任务成功。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

当前API暂无授权信息透出。

请求语法

POST  HTTP/1.1

请求参数

名称

类型

必填

描述

示例值

Prompt

string

否

用户本轮输入的文本。发起新提问时传入非空字符串,并填写 SessionId 和新的 TalkId;提交或取消表单交互时传入空字符串,并通过 UserInputInfo 传递表单信息。

帮我梳理最近 24 小时的高危告警并给出处置建议

Stream

boolean

否

是否以 SSE(Server-Sent Events)方式流式返回智能体的响应。默认值为 true,此时接口持续推送事件流。

Memory

boolean

否

是否启用会话记忆。默认值为 true,此时智能体在生成回复时参考同一会话的历史上下文。

ExecutionMode

string

否

本次对话的执行模式。会话在首轮对话时确定执行模式,之后的对话沿用该模式。

枚举值:

  • single :

    单智能体执行,由单个安全智能体独立完成本次对话任务。

  • role :

    角色执行,由指定的安全角色承接本次对话任务。

  • team :

    团队协同执行,由多个安全智能体分工协作完成本次对话任务。

single

Target

string

否

本次对话的执行目标,与 ExecutionMode 配合使用,用于指定承接本次对话的执行对象。

sec-ops-team-01

Channel

string

否

发起本次对话的接入渠道标识,用于区分不同调用入口。

console

AttachmentStagingId

string

否

本次对话引用的附件暂存 ID,用于关联已提前暂存的附件内容。

stg-6f1d9c8b7a2e4530

Attachments

string

否

本次对话携带的附件列表,OpenAPI 参数值为 JSON 数组字符串。控制台先完成附件上传,再将上传返回的 OSS 对象标识作为数组元素传入;前端附件对象中的 path 保存该标识。请使用本次上传得到的真实对象标识,勿传入调用方计算机的本地文件路径。最多支持 10 个附件。

["oss/input.txt","oss/raw.txt"]

UserInputInfo

string

否

表单交互信息,取值为 JSON 对象字符串。提交时 Prompt 为空;sessionId、talkId 分别为表单所属会话和轮次 ID,formId 为返回的 Form.schema.formId,formAction 为交互动作。Questions 表单使用 submit 或 cancel;PolicyApproval 表单使用 approve、deny 或 cancel。提交问题答案时,formValues 为以 questionId 为键的对象:选择答案使用 {"kind":"selected","optionIds":["选项 ID"]},自定义答案使用 {"kind":"custom","text":"回答内容"}。取消或审批操作可传空对象。控制台请求同时传入与嵌套值一致的顶层 SessionId 和 TalkId。普通新提问不传此参数;不使用 componentId、componentValues、dismissed 等旧版字段。

{"sessionId":"session_example","talkId":"talk_example","formId":"interaction_example","formValues":{"q1":{"kind":"selected","optionIds":["q1_o1"]}},"formAction":"submit"}

ExtraParams

string

否

本次对话的扩展参数,取值为 JSON 对象字符串。控制台前端通过 execution_mode 和 target 传递执行模式与目标,例如 {"execution_mode":"team","target":"team:auto"}。project_id 用于指定项目,result_delivery_target_ids 为本轮结果投递目标 ID 数组。会话后续轮次应保持已确定的执行模式和目标,不应通过该参数切换到冲突的目标。

{"execution_mode":"team","target":"team:auto"}

Agent

string

否

智能体标识。当前控制台前端默认不传入此参数。

sec-ops-agent

Model

string

否

模型标识。当前控制台前端默认不传入此参数。

qwen-max

Skill

string

否

技能标识。当前控制台前端默认不传入此参数。

alert-analysis

TalkId

string

否

对话轮次 ID。控制台每次发起新的普通提问时生成并传入新值;同一会话的后续追问也使用新的 TalkId。提交或取消表单时复用该表单所属的 TalkId,并与 UserInputInfo.talkId 保持一致。

9b1e7d2c4a6f8e30

SessionId

string

否

连续对话的会话 ID。控制台发起新会话时生成并传入,后续追问复用同一 SessionId。提交或取消表单时使用该表单所属的会话 ID,并与 UserInputInfo.sessionId 保持一致。

5f2c1b9a8d3e4c7f

TimeZone

string

否

调用方所在的 IANA 时区名称,例如 Asia/Shanghai。控制台在发起新提问时传入浏览器时区,用于模型理解相对日期和时间;不改变服务端 UTC 时间戳的存储方式。

Asia/Shanghai

ResponseLanguage

string

否

本轮执行中用户可见模型内容使用的语言。使用具体有效的 BCP-47 语言标识,例如 zh-CN、en-US 或 ja-JP,不能传入空字符串或 auto。控制台在发起新提问时传入当前界面对应的具体语言。

zh-CN

返回参数

名称

类型

描述

示例值

string

当 Stream=true 时,响应为 text/event-stream 事件流。每个 SSE 数据帧的 data 是一个 JSON 对象的序列化字符串。控制台逐帧解析 data:通过 type 识别控制事件,通过 a2ui 识别界面更新消息;不要仅依靠 event 名区分消息用途。

控制事件

type主要字段含义与处理规则
sessionsession_id:会话 ID确认本次普通聊天写入已绑定会话。校验其与请求 SessionId 一致;不代表任务已经完成。
dispatchtaskId:任务 ID;target:执行目标;delta:兼容字段;resultDelivery:结果投递登记回执表示执行分派确认。delta 可为空字符串,不应将该事件当作模型文本增量。
errorerror:错误原文;code:可选错误分类;requestId:服务端诊断关联 ID;clientRequestId:可选调用方关联 ID展示错误并保留诊断信息。code 和 clientRequestId 不保证出现;HTTP 200 并不排除流中出现 error。
interaction_resulttaskId:任务 ID;talkId:表单所属轮次 ID表单交互处理的回执,不代表整轮任务完成;表单最终状态仍以随后返回的 A2UI 更新为准。
donesession_id:会话 ID本次事件流结束。校验会话归属后停止读取并释放流,不再等待网络连接物理关闭;不能仅凭 done 判断业务成功。

dispatch.resultDelivery 为结果投递登记信息:status=registered 表示本轮选择的投递目标已登记,status=not_requested 表示未请求额外投递;targetIds 为目标 ID 数组,未请求时为空数组。登记成功不表示结果已经发送到目标渠道。

注意字段大小写:session 和 done 使用 session_id;A2UI 消息使用 sessionId。taskId 是执行任务身份,talkId 是对话轮次身份,两者不能互换。

A2UI 消息字段

字段类型说明
sessionIdstring消息所属连续会话 ID。
talkIdstring消息所属对话轮次 ID,用于定位该轮界面。
taskIdstring,可为空关联的执行任务 ID;任务分派前允许为空。
eventIdstring当前消息标识,用于事件追踪和诊断。
seqinteger当前 Talk 内的事件序号。多个界面更新可共享同一 seq;按到达顺序全部处理,不得仅因 seq 相同而丢弃消息。
a2uiobjectA2UI 界面指令,包含版本及创建界面、声明组件或更新数据模型的命令。

a2ui 中的 surfaceId 应与外层 talkId 一致。createSurface 创建该轮界面;updateComponents 声明完整组件结构;updateDataModel 更新组件绑定的数据。updateDataModel.isDelta=true 时,仅对已初始化的字符串执行追加;省略或为 false 时按完整值替换。正文、过程、表单和结果应依据组件声明及数据绑定渲染。

顺序与结束判断

普通聊天写入被接纳后先返回 session,随后返回分派和界面更新。准入前拒绝请求时可以直接返回 error、done,而没有 session。执行过程中也可能出现 error,因此不要把 session、dispatch 或 HTTP 200 当作业务成功。

收到所属会话的 done 后结束本次读取。任务结果应结合错误消息和 A2UI 终态内容判断;在收到 done 前遇到 EOF、断网或代理中断,应按流未完整结束处理。表单回执 interaction_result 同样不能替代 A2UI 状态或 done。

响应示例展示一条完整的拒绝事件流。以下是正常执行中的 A2UI 终态更新片段,仅用于说明字段形状,省略了此前创建界面、组件声明和其他数据更新,不可作为完整可渲染事件流:

event: message
data: {"sessionId":"session_example","talkId":"talk_example","taskId":"task_example","eventId":"evt_example","seq":7,"a2ui":{"version":"v0.9","updateDataModel":{"surfaceId":"talk_example","path":"/surface/isDone","value":true}}}

event: message
data: {"type":"done","session_id":"session_example"}

event: message data: {"type":"error","code":"task_busy","error":"当前会话存在尚未结束的任务,请等待任务结束后再发起新的提问。","requestId":"request_example"} event: message data: {"type":"done","session_id":"session_example"}

示例

正常返回示例

JSON格式

"event: message\ndata: {\"type\":\"error\",\"code\":\"task_busy\",\"error\":\"当前会话存在尚未结束的任务,请等待任务结束后再发起新的提问。\",\"requestId\":\"request_example\"}\n\nevent: message\ndata: {\"type\":\"done\",\"session_id\":\"session_example\"}\n\n"

错误码

访问错误中心查看更多错误码。

变更历史

更多信息,参考变更详情。