Stream agent execution in real-time

curl --request POST \
  --url https://api.orq.ai/v2/agents/{key}/stream-task \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "<string>"
      }
    ],
    "messageId": "<string>"
  },
  "task_id": "<string>",
  "variables": {},
  "contact": {
    "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "display_name": "Jane Doe",
    "email": "[email protected]",
    "metadata": [
      {
        "department": "Engineering",
        "role": "Senior Developer"
      }
    ],
    "logo_url": "https://example.com/avatars/jane-doe.jpg",
    "tags": [
      "hr",
      "engineering"
    ]
  },
  "thread": {
    "id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "tags": [
      "customer-support",
      "priority-high"
    ]
  },
  "memory": {
    "entity_id": "<string>"
  },
  "metadata": {},
  "stream_timeout_seconds": 1800.5
}
'

{
  "data": {
    "type": "agents.execution_started",
    "timestamp": "<string>",
    "data": {
      "agent_task_id": "<string>",
      "workspace_id": "<string>",
      "trace_id": "<string>"
    }
  }
}

Agents

Stream agent execution in real-time

Executes an agent and streams the interaction in real-time using Server-Sent Events (SSE). Provides live updates as the agent processes the request, including message chunks, tool calls, and execution status. Perfect for building responsive chat interfaces and monitoring agent progress. The stream continues until the agent completes its task, encounters an error, or reaches the configured timeout (default 30 minutes, configurable 1-3600 seconds).

POST

agents

{key}

stream-task

Stream agent execution in real-time

curl --request POST \
  --url https://api.orq.ai/v2/agents/{key}/stream-task \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "<string>"
      }
    ],
    "messageId": "<string>"
  },
  "task_id": "<string>",
  "variables": {},
  "contact": {
    "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "display_name": "Jane Doe",
    "email": "[email protected]",
    "metadata": [
      {
        "department": "Engineering",
        "role": "Senior Developer"
      }
    ],
    "logo_url": "https://example.com/avatars/jane-doe.jpg",
    "tags": [
      "hr",
      "engineering"
    ]
  },
  "thread": {
    "id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "tags": [
      "customer-support",
      "priority-high"
    ]
  },
  "memory": {
    "entity_id": "<string>"
  },
  "metadata": {},
  "stream_timeout_seconds": 1800.5
}
'

{
  "data": {
    "type": "agents.execution_started",
    "timestamp": "<string>",
    "data": {
      "agent_task_id": "<string>",
      "workspace_id": "<string>",
      "trace_id": "<string>"
    }
  }
}

Authorizations

Authorization

string

header

required

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

Path Parameters

key

string

required

The key or ID of the agent to invoke

Body

application/json

message

A2A Message · object

required

The A2A message to send to the agent (user input or tool results)

Show child attributes

message.role

required

Message role (user or tool for continuing executions)

Available options:

user

message.parts

(Text Part · object | File Part · object | Tool Result Part · object)[]

required

A2A message parts (text, file, or tool_result only)

Message part that can be provided by users. Use "text" for regular messages, "file" for attachments, or "tool_result" when responding to tool call requests.

Text Part
File Part
Tool Result Part

Show child attributes

message.parts.kind

enum<string>

required

Available options:

text

message.parts.text

string

required

message.messageId

string

Optional A2A message ID in ULID format

task_id

string

Optional task ID to continue an existing agent execution. When provided, the agent will continue the conversation from the existing task state. The task must be in an inactive state to continue.

variables

object

Optional variables for template replacement in system prompt, instructions, and messages

Show child attributes

variables.{key}

any

contact

object

Information about the contact making the request. If the contact does not exist, it will be created automatically.

Show child attributes

contact.id

string

required

Unique identifier for the contact

Example:

"contact_01ARZ3NDEKTSV4RRFFQ69G5FAV"

contact.display_name

string

Display name of the contact

Example:

"Jane Doe"

contact.email

string<email>

Email address of the contact

Example:

"[email protected]"

contact.metadata

object[]

A hash of key/value pairs containing any other data about the contact

Show child attributes

contact.metadata.{key}

any

Example:

[
  {
    "department": "Engineering",
    "role": "Senior Developer"
  }
]

contact.logo_url

string

URL to the contact's avatar or logo

Example:

"https://example.com/avatars/jane-doe.jpg"

contact.tags

string[]

A list of tags associated with the contact

Example:

["hr", "engineering"]

thread

object

Thread information to group related requests

Show child attributes

thread.id

string

required

Unique thread identifier to group related invocations.

Example:

"thread_01ARZ3NDEKTSV4RRFFQ69G5FAV"

thread.tags

string[]

Optional tags to differentiate or categorize threads

Example:

["customer-support", "priority-high"]

memory

object

Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions.

Show child attributes

memory.entity_id

string

required

An entity ID used to link memory stores to a specific user, session, or conversation. This ID is used to isolate and retrieve memories specific to the entity across agent executions.

metadata

object

Optional metadata for the agent invocation as key-value pairs that will be included in traces

Show child attributes

metadata.{key}

any

stream_timeout_seconds

number

Stream timeout in seconds (1-3600). Default: 1800 (30 minutes)

Required range: 1 <= x <= 3600

Response

Server-Sent Event stream successfully established. Returns real-time events including agent messages, tool calls, status updates, and completion signals. The stream ends with a [DONE] sentinel value.

data

Agent Execution Started Event · object

required

Initial event emitted when an agent stream begins. Contains the task ID for tracking, workspace context, and trace ID for observability.

Show child attributes

data.type

enum<string>

required

Available options:

agents.execution_started

data.timestamp

string

required

ISO timestamp of the event

data.data

object

required

Show child attributes

data.data.agent_task_id

string

required

Agent execution task ID (ULID)

data.data.workspace_id

string

required

Workspace ID

data.data.trace_id

string

required

Trace ID for the workflow run

Run agent with streaming response

Create response

⌘I

Platform APIs

Gateway APIs

Stream agent execution in real-time

Authorizations

Path Parameters

Body

Response