ORorq-ai
Agents

Run agent with streaming response

Changed on

Run an agent with streaming via SSE, combining inline configuration with real-time updates including messages, tool executions, and status.

post/v2/agents/stream-run

Request

  • Base URL
    https://my.orq.ai
  • URL
    https://my.orq.ai/v2/agents/stream-run
  • Auth
    HTTP bearer

Request body

keystring required

A unique identifier for the agent. This key must be unique within the same workspace and cannot be reused. When executing the agent, this key determines if the agent already exists. If the agent version differs, a new version is created at the end of the execution, except for the task. All agent parameters are evaluated to decide if a new version is needed.

task_idstring

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.

rolestring required

Specifies the agent's function and area of expertise.

instructionsstring required

Provides context and purpose for the agent. Combined with the system prompt template to generate the agent's instructions.

variablesobject

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

pathstring required

Entity storage path.

With workspace-level API keys, use the format project/folder/subfolder/.... The first element must be the display name of an existing project, followed by nested folders (auto-created as needed). Example: Default Project/agents.

With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: agents. For backward compatibility, a leading project name is ignored when it matches the scoped project.

descriptionstring

A brief summary of the agent's purpose.

system_promptstring nullable

A custom system prompt template for the agent. If omitted, the default template is used.

memory_storesstring[]

Array of memory store identifiers that are accessible to the agent. Accepts both memory store IDs and keys.

metadataobject

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

engine'text' | 'jinja' | 'mustache'

Template engine for variable interpolation. Text uses {{variable}} syntax, Jinja supports loops/conditionals/filters, Mustache uses {{#section}} syntax.

stream_timeout_secondsnumber

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

Example request

{
  "model": "openai/gpt-5.6-sol",
  "fallback_models": [
    {
      "parameters": {
        "fallbacks": [
          {
            "model": "openai/gpt-5.4-mini"
          }
        ],
        "cache": {
          "ttl": 3600
        },
        "load_balancer": {
          "type": "weight_based",
          "models": [
            {
              "model": "openai/gpt-4o",
              "weight": 0.7
            },
            {
              "model": "anthropic/claude-3-5-sonnet",
              "weight": 0.3
            }
          ]
        },
        "timeout": {
          "call_timeout": 30000
        }
      },
      "retry": {
        "count": 3,
        "on_codes": [
          429,
          500,
          502,
          503,
          504
        ]
      }
    }
  ],
  "message": {
    "parts": [
      {
        "file": {
          "uri": "https://example.com/report.pdf"
        }
      }
    ]
  },
  "identity": {
    "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "display_name": "Jane Doe",
    "email": "jane.doe@example.com",
    "metadata": [
      {
        "department": "Engineering",
        "role": "Senior Developer"
      }
    ],
    "logo_url": "https://example.com/avatars/jane-doe.jpg",
    "tags": [
      "hr",
      "engineering"
    ]
  },
  "contact": {
    "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "display_name": "Jane Doe",
    "email": "jane.doe@example.com",
    "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"
    ]
  },
  "path": "Default Project",
  "knowledge_bases": [
    {
      "knowledge_id": "customer-knowledge-base"
    }
  ]
}

Response

Server-Sent Event stream successfully established. Delivers real-time agent execution events including message fragments, tool invocations, intermediate results, and completion status. Stream terminates with [DONE] sentinel upon completion.

Changes

  • 928a71e92252Revision changes
    • info

      added the new optional request property //////

    • info

      added the new optional request property //////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      the request property default value changed from 01M640RMGCY3N3304T2PWR9FVK to 01M644XDS42AWPCYXXM9PDHNSG

    • info

      added between_tools discriminator mapping keys to the //// request property

    • info

      added between_tools discriminator mapping keys to the /// request property

    • info

      added to the //// request property oneOf list

    • info

      added to the /// request property oneOf list

  • 33d63277cd4eRevision changes
    • breaking

      removed from the //// request property oneOf list

    • breaking

      removed from the /// request property oneOf list

    • warning

      removed the request property //////

    • warning

      removed the request property //////

    • warning

      removed the request property /////

    • warning

      removed the request property /////

    • info

      the request property default value changed from 01M63PG4XY36278SX406RPEA27 to 01M640RMGCY3N3304T2PWR9FVK

    • info

      removed between_tools discriminator mapping keys from the //// request property

    • info

      removed between_tools discriminator mapping keys from the /// request property