Skip to main content

Send Event

Send a user message to a session; content supports text, image, video, and file blocks

POST
/api/v1/agentstudio/sessions/{session_id}/events
cURL
curl --request POST \
  --url 'https://{workspace_id}.{region}.maas.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..."
}
Write events to a session to trigger agent processing. input is an array of events (length 1–50); each event takes one of the following by type:
typeroleDescription
messageuserSend a user message and trigger the agent into running; content supports four content block types — text, image, video, and file. See Content blocks
interruptuserInterrupt the current turn; the session returns to idle; optionally specify session_thread_id to interrupt a sub-thread
tool_approval_responseuserRespond to tool approval; see the Tool approval section below for the rules
function_call_outputtoolReturn the execution result of a self-hosted function
tool_call_outputtoolReturn the execution result of a self-hosted platform built-in tool
interrupt and a plain message may be mixed in the same request (semantics: end the current approval batch first, then start chatting).

Content blocks

Images and videos enter the model's multimodal visual channel; files are materialized by the platform into the session sandbox filesystem, and the model reads them on demand via tools.
typeCarrier fieldDescription
texttextPlain text
imageimage_url, file_idImage; enters the model's visual channel; file_id is dereferenced by the platform into a temporary URL, rendered only for this turn and not persisted
videovideo_url or file_idVideo; enters the model's visual channel; same for file_id
filefile_id + filenameFile/document; materialized into the sandbox and read on demand by the model; filename is the file name, used for the sandbox path and manifest display

Fields per event type

message

FieldTypeRequiredDescription
rolestringYesuser
typestringYesmessage
contentarrayYesContent block array; supports text/image/video/file. See Content blocks

interrupt

FieldTypeRequiredDescription
rolestringYesuser
typestringYesinterrupt
session_thread_idstringNoTarget a sub-thread for interruption when multiple agents are involved

tool_approval_response

FieldTypeRequiredDescription
rolestringYesuser
typestringYestool_approval_response
contentarrayYesExactly one data block, containing batch_id, call_id, and result (allow/deny); optionally deny_message
For matching, dedup, and mixed-input rules, see the Tool approval section below.

function_call_output / tool_call_output

FieldTypeRequiredDescription
rolestringYestool
typestringYesfunction_call_output or tool_call_output
contentarrayYesA single data block containing call_id and output (string)
is_errorbooleanNotrue when execution failed or was interrupted
session_thread_idstringNoRoute to a sub-agent thread

Tool approval tool_approval_response

Responds to a tool approval request. content is a single data block with the following data fields:
FieldRequiredDescription
batch_idYesBatch ID of the corresponding tool_approval_request
call_idYesID of the tool call awaiting a decision
resultYesallow or deny
deny_messageNoReturned to the model as tool output only when deny
Matching and dedup
  • batch_id + call_id jointly identify one approval (composite identity); both must be non-empty
  • Matching by call_id alone is not allowed, nor is session-level dedup by call_id — different batches may legitimately reuse the same call_id
  • Multiple tool_approval_response entries in the same request must belong to the same batch_id
Mixed input while approval is pending Two branches; neither takes effect for the current decision (the current batch is retained and pending_call_ids is unchanged):
Input combinationResultError code
tool_approval_response + plain messageFed back later via a pending_tool_approval_unresolved event / terminal state—
tool_approval_response + interruptRejected due to control-message conflictinvalid_tool_approval
Neither is a synchronous 4xx of this POST; observe via the SSE event stream or GET /events. interrupt and a plain message may be mixed in the same request (semantics: end the current approval batch first, then start chatting). Scope: Tool approval is supported only for the main agent, not for sub-agents. content validation content must be exactly one data block. Counter-examples (all should be rejected):
ExampleReason
content: []Empty array
content: [{}]Missing type and data
content: [{"type":"data"}]Missing data
data: {"batch_id":"","call_id":"call_xxx","result":"allow"}Empty batch_id
data: {"batch_id":"b","call_id":"","result":"allow"}Empty call_id
Valid example: content: [{"type":"data","data":{"batch_id":"...","call_id":"...","result":"allow"}}], or result set to deny with deny_message.

Authorizations

string
header
required

DashScope API Key

Path Parameters

string
required

Body

application/json
object[]
required

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

items: 1–50

Response

200-application/json
object[]

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

string

本次请求的唯一标识