跳转到主要内容
Session & Event

发送 Event

向会话发送用户消息,content 支持文本、图片、视频、文件四类内容块

POST
/api/v1/agentstudio/sessions/{session_id}/events
cURL
curl --request POST \
  --url 'https://dashscope.aliyuncs.com/api/v1/agentstudio/sessions/{session_id}/events' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": [
    {
      "role": "user",
      "type": "message",
      "content": [
        {
          "type": "text",
          "text": "总结这份报告,并对比图中的趋势"
        },
        {
          "type": "file",
          "file_id": "file_01HKDPQ3MNPQRSTVWXYZABCD",
          "filename": "report.pdf"
        },
        {
          "type": "image",
          "image_url": "https://example.com/trend.jpg"
        }
      ]
    }
  ]
}
'
{
  "data": [
    {
      "object": "message",
      "id": "msg_8f2a1c...",
      "created_at": "2025-10-24T08:15:30.123Z",
      "role": "user",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "text",
          "text": "..."
        }
      ]
    }
  ],
  "request_id": "req_01K8ZQX..."
}
向会话写入事件,触发智能体处理。input 为事件数组(长度 1–50),每个事件按 type 取下表之一:
typerole说明
messageuser发送用户消息,触发智能体进入 running;content 支持文本、图片、视频、文件四类内容块,详见 content 内容块
interruptuser中断当前轮,会话回到 idle;可选 session_thread_id 定向中断子线程
tool_approval_responseuser回应工具审批;规则见下文「工具审批」
function_call_outputtool回填自托管函数执行结果
tool_call_outputtool回填自托管平台内置工具的执行结果
interrupt 与普通 message 可在同请求混发(语义:先结束当前审批批次再开始聊天)。

content 内容块

图片与视频进入模型多模态视觉通道;文件由平台物化到会话沙箱文件系统,模型通过工具按需读取。
type载体字段说明
texttext纯文本
imageimage_urlfile_idimage_data + media_type图片,进入模型视觉通道;file_id 经平台解引用为临时 URL,仅本轮渲染,不持久化;image_data 为 base64 数据,须带 media_type(如 image/png
videovideo_urlfile_id视频,进入模型视觉通道;file_id 同上
filefile_id + filename文件/文档,物化到沙箱,模型按需读取;filename 为文件名,用于沙箱路径与清单展示

各事件字段

message

字段类型必填说明
rolestringuser
typestringmessage
contentarray内容块数组,支持 text/image/video/file,详见 content 内容块

interrupt

字段类型必填说明
rolestringuser
typestringinterrupt
session_thread_idstring多 agent 时定向中断子线程

tool_approval_response

字段类型必填说明
rolestringuser
typestringtool_approval_response
contentarray恰好一个 data 块,含 batch_idcall_idresultallow/deny),可选 deny_message
匹配、去重、混合输入等规则见下文「工具审批」。

function_call_output / tool_call_output

字段类型必填说明
rolestringtool
typestringfunction_call_outputtool_call_output
contentarray单个 data 块,含 call_idoutput(字符串)
is_errorboolean执行失败/被中断时为 true
session_thread_idstring路由到子 agent 线程

工具审批 tool_approval_response

回应工具审批请求。content 为单个 data 块,data 字段如下:
字段必填说明
batch_id对应 tool_approval_request 的批次 ID
call_id待裁决的工具调用 ID
resultallowdeny
deny_messagedeny 时作为工具输出回传给模型
匹配与去重
  • batch_id + call_id 共同标识一次审批(复合身份),均非空
  • 不能只按 call_id 匹配,也不得按 call_id 做会话级去重——不同批次可合法复用同一 call_id
  • 同一请求内多条 tool_approval_response 必须属于同一 batch_id
待审批期间的混合输入 两条分支,本次裁决均不生效(当前批次保留、pending_call_ids 不变):
输入组合结果错误码
tool_approval_response + 普通 message后续以 pending_tool_approval_unresolved 事件/终态反馈
tool_approval_response + interrupt控制消息冲突被拒invalid_tool_approval
两者都不是本次 POST 的同步 4xx,需经 SSE 事件流或 GET /events 观察。interrupt 与普通 message 可在同请求混发(语义:先结束当前审批批次再开始聊天)。 范围:工具审批仅支持主智能体,不支持子智能体。 content 校验 content 恰好一个 data 块。反例(均应被拒):
示例原因
content: []空数组
content: [{}]typedata
content: [{"type":"data"}]data
data: {"batch_id":"","call_id":"call_xxx","result":"allow"}batch_id
data: {"batch_id":"b","call_id":"","result":"allow"}call_id
合法示例:content: [{"type":"data","data":{"batch_id":"...","call_id":"...","result":"allow"}}],或 resultdeny 且带 deny_message

鉴权

string
header
必填

DashScope API Key

路径参数

string
必填

请求体

application/json
object[]
必填

事件数组(长度 1-50)。每个事件至少含 role 与 type

items: 1–50

响应

200-application/json
object[]

已受理事件的回显数组,与请求 input 顺序对齐;回显仅表示入队成功,不代表已被处理或裁决已生效

string

本次请求的唯一标识