Create Agent Run

Execute an agent with a message and optional media files. Supports both streaming and non-streaming responses.

Features:

• Text message input with optional session management
• Multi-media support: images (PNG, JPEG, WebP), audio (WAV, MP3), video (MP4, WebM, etc.)
• Document processing: PDF, CSV, DOCX, TXT, JSON
• Real-time streaming responses with Server-Sent Events (SSE)
• User and session context preservation

Streaming Response: When stream=true, returns SSE events with event and data fields.

POST /agents/{agent_id}/runs

Create Agent Run

cURL

curl --request POST \
  --url https://api.example.com/agents/{agent_id}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'message=<string>' \
  --form stream=true \
  --form 'session_id=<string>' \
  --form 'user_id=<string>' \
  --form 'files=<string>' \
  --form 'version=<string>' \
  --form background=false \
  --form files.0.items='@example-file'

400

{
  "detail": "Bad request",
  "error_code": "BAD_REQUEST"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

agent_id · string · required

Body

multipart/form-data

message · string · required

stream · boolean · default: true

session_id · string | null

user_id · string | null

files · file[] | null

version · string | null

background · boolean · default: false

Response

200

application/json

Agent run executed successfully