发送会话事件
本接口用于向会话(Session)发送事件,驱动智能体运行,包括发送用户消息、中断运行、确认或拒绝工具调用、回填自定义工具结果。
系统先校验整个事件列表,任一事件不合法时返回 400,所有事件都不会生效;校验通过后按顺序逐条处理,任一条失败即停止,后续事件不再处理。发送 user.interrupt 时,系统等待运行停止(最多 10 秒)后返回。
返回结果为每条事件的回显,智能体的回复通过订阅会话事件流或获取会话事件历史接口获取。
权限说明
使用 API Key 鉴权调用 API 流程,具体调用流程,请查看认证鉴权。
请求参数
会话标识。
会话不存在时返回 404;会话不属于当前账号时返回 403。
事件列表,不能为空,否则返回 400。
显示子属性
隐藏子属性
显示子属性
隐藏子属性
事件类型。
可选值:user.message(发送用户消息)、user.interrupt(中断运行)、user.tool_confirmation(确认或拒绝工具调用)、user.custom_tool_result(回填自定义工具结果)。
system.message、user.tool_result、user.define_outcome 不支持,传入时返回 400。
会话正在等待工具确认(requires_action)时发送 user.message 返回 400。
内容块列表。
type 为 user.message 时必填且不能为空,否则返回 400;type 为 user.custom_tool_result 时为工具执行结果,不传按空数组处理,原样转给智能体。
显示子属性
隐藏子属性
显示子属性
隐藏子属性
内容块类型。
可选值:text(纯文本)、image(图片)、document(文档)、file(直接引用上传文件,适用于非图片、非 PDF 的文件)。
其他类型(如 tool_use)返回 400。
文本内容。
type 为 text 时必填。
内容来源。
type 为 image、document 时必填。
显示子属性
隐藏子属性
来源类型。
可选值:base64(内联数据)、file(引用上传文件,系统会先把文件挂载到会话)、text(纯文本,仅 document 可用)。
url 不支持,传入时返回 400。
MIME 类型。
image 只支持 image/png、image/jpeg、image/gif、image/webp;document 使用 base64 或 file 时只支持 application/pdf,其他取值返回 400。
不传时按文件扩展名判断。
内容数据。
type 为 base64 时为 Base64 编码数据,不能为空;type 为 text 时为纯文本。
文件标识,只能包含字母、数字、下划线和短横线。
type 为 file 时必填。
文档标题,可选。
type 为 document 且 source.type 为 text 时,系统把内容拼成「title 换行 data」。
文件标识。
type 为 file 时必填。
只中断指定线程;不传时中断整个会话,包括主线程和所有未归档的子线程。
仅 type 为 user.interrupt 时使用;线程不存在或已结束时返回 400。
待确认的 agent.tool_use 或 agent.mcp_tool_use 事件标识。
type 为 user.tool_confirmation 时必填;工具调用不存在或已确认过时返回 400。
确认结果。
可选值:allow(允许执行)、deny(拒绝),其他取值返回 400。
type 为 user.tool_confirmation 时必填。
拒绝原因,会告知智能体。
仅 type 为 user.tool_confirmation 且 result 为 deny 时使用。
对应 agent.custom_tool_use 事件的标识。
type 为 user.custom_tool_result 时必填;工具调用不存在时返回 404,该调用不是自定义工具或等待已失效时返回 400。
重复提交同一标识时返回首次提交的回显,不重复生效。
工具是否执行失败,不传或传 null 时按 false 处理。
仅 type 为 user.custom_tool_result 时使用。
POST /api/dma/v1/sessions/{session_id}/events HTTP/1.1
Host: api.dumate.cn
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
示例代码
curl --location --request POST "https://api.dumate.cn/api/dma/v1/sessions/ses_gffe5e3caaadc6ffe126cMcNQZsyuhP/events" \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"events": [
{
"type": "user.message",
"content": [
{
"type": "text",
"text": "读一下这个文件,回复文件第一行"
},
{
"type": "file",
"file_id": "node_g001a1c3534dc1001mUC0tecbzGoZuN"
}
]
}
]
}'
返回响应
事件回显列表,每条请求事件对应一条或多条回显。
显示子属性
隐藏子属性
显示子属性
隐藏子属性
事件标识,sevt_ 前缀。
user.message 的标识与事件流、事件历史中同一条消息的标识一致。
事件类型,同请求参数。
原样回显的请求内容。
仅 user.message 和 user.custom_tool_result 返回。
显示子属性
隐藏子属性
内容块,结构同请求参数。
显示子属性
隐藏子属性
处理时间,RFC 3339 格式,UTC。
user.message 回显时尚未处理,为 null。
{
"data": [
{
"content": [
{
"type": "text",
"text": "读一下这个文件,回复文件第一行"
},
{
"type": "file",
"file_id": "node_g001a1c3534dc1001mUC0tecbzGoZuN"
}
],
"id": "sevt_msg_g001a1c356cb9c001egSwADPkMC6ZRu",
"processed_at": null,
"type": "user.message"
}
]
}
评价此篇文章
