与当前账号的用户安全智能体进行对话,通过 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代码示例。
调试
授权信息
请求语法
POST HTTP/1.1
请求参数
|
名称 |
类型 |
必填 |
描述 |
示例值 |
| Prompt |
string |
否 |
用户本轮输入的文本。发起新提问时传入非空字符串,并填写 SessionId 和新的 TalkId;提交或取消表单交互时传入空字符串,并通过 UserInputInfo 传递表单信息。 |
帮我梳理最近 24 小时的高危告警并给出处置建议 |
| Stream |
boolean |
否 |
是否以 SSE(Server-Sent Events)方式流式返回智能体的响应。默认值为 true,此时接口持续推送事件流。 |
|
| Memory |
boolean |
否 |
是否启用会话记忆。默认值为 true,此时智能体在生成回复时参考同一会话的历史上下文。 |
|
| ExecutionMode |
string |
否 |
本次对话的执行模式。会话在首轮对话时确定执行模式,之后的对话沿用该模式。 枚举值:
|
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 名区分消息用途。 控制事件
dispatch.resultDelivery 为结果投递登记信息:status=registered 表示本轮选择的投递目标已登记,status=not_requested 表示未请求额外投递;targetIds 为目标 ID 数组,未请求时为空数组。登记成功不表示结果已经发送到目标渠道。 注意字段大小写:session 和 done 使用 session_id;A2UI 消息使用 sessionId。taskId 是执行任务身份,talkId 是对话轮次身份,两者不能互换。 A2UI 消息字段
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: {"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"
错误码
访问错误中心查看更多错误码。
变更历史
更多信息,参考变更详情。