Skip to main content

Send an event

Send a user message, cancel the current turn, or return a function call result to a session.

Endpoint

POST /agents/sessions/{session_id}/events Returns 202 Accepted with an empty body. The response may include an x-request-id header. A 202 means the input was durably accepted and delivery was scheduled. It does not mean the model has consumed the input or the turn has completed. Use SSE, the turn terminal status, and item history to determine the result.

Path parameters

session_id string (required)Session ID, for example sess_xxx

Request body

events array<object> (required)Event array. An empty array [] is an empty batch and produces no inputChoose one of the following event structures based on type.

Event types

type string (required)Fixed to agent.session.input.message.input array<object> (required)Array of user messages. Must not be empty.
role string (required)Message role, fixed to user.content array (required)Content part array. Must not be empty.
type string (required)Content part type: input_text or input_image.text string (conditional)Text content.image_url string (conditional)Image URL.
{
  "type": "agent.session.input.message",
  "input": [{
    "role": "user",
    "content": [{"type": "input_text", "text": "Add more details."}]
  }]
}
type string (required)Fixed to agent.session.input.cancel. Only type is accepted; turn_id and other fields are rejected.
{"type": "agent.session.input.cancel"}
type string (required)Fixed to agent.session.input.tool_result.turn_id string (required)Public turn ID from required_actions.call_id string (required)Function call ID.success boolean (required)Whether the call succeeded.output string or array / null (conditional)Function output; a string, or an array of input_text / input_image.error string / null (conditional)Failure message.
{
  "type": "agent.session.input.tool_result",
  "turn_id": "turn_xxx",
  "call_id": "call_xxx",
  "success": true,
  "output": "Shipped"
}
The input field for message is an array, not the string shorthand used when creating a session. cancel cancels only the current turn. Fields from other branches and unknown fields are rejected.

Request example

curl -X POST "$BASE_URL/agents/sessions/sess_xxx/events" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: agents=v1" \
  -d '{
    "events": [{
      "type": "agent.session.input.message",
      "input": [{
        "role": "user",
        "content": [{"type": "input_text", "text": "Add more details."}]
      }]
    }]
  }'

Function calling

After the model initiates a function call, the session's required_actions contains a pending item:
{
  "type": "function_call",
  "turn_id": "turn_xxx",
  "call_id": "call_xxx",
  "name": "lookup_order",
  "arguments": {"order_id": "A123"}
}
After the application executes the function, return the result:
{
  "events": [{
    "type": "agent.session.input.tool_result",
    "turn_id": "turn_xxx",
    "call_id": "call_xxx",
    "success": true,
    "output": "Shipped"
  }]
}
arguments is already parsed into an object; do not parse it again as a JSON string. After a client restart, retrieve the session and read required_actions before continuing.

Idempotency

You can send an Idempotency-Key header:
  • The key must be 1–256 characters. An empty or oversized key returns 400.
  • Retrying with the same session, key, and content reuses the acceptance result and does not deliver the input again.
  • The same key with different content returns 409 conflict_error.
  • A batch containing only cancel is the current-cancel exception: retrying with the same key still applies to the current turn at that time.
  • Without the header, the API does not provide request-level automatic deduplication.
  • A batch containing only messages is merged into one user input in array order. A mixed batch is processed item by item; a semantic failure in a later item does not roll back items already accepted.

Response example

HTTP/1.1 202 Accepted
x-request-id: <request-id>
202 Accepted with no response body. Acceptance does not mean the model has consumed the tool result or the turn has completed.

Error codes

HTTP statusError type / codeSolution
400invalid_request_error / invalid_request_errorFix the request structure and event content; use a non-empty Idempotency-Key of 1-256 characters
404not_found_error / not_found_errorUse a session ID that exists and has not been deleted in the current workspace
409conflict_error / conflict_errorConfirm the current resource state; reuse the same request content for the same Idempotency-Key
503server_error / agents_api_upstream_unavailableRetry later. If it keeps failing, submit a ticket with x-request-id