curl --request POST \
--url https://api.orq.ai/v2/agents/stream-run \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"key": "<string>",
"model": "<string>",
"role": "<string>",
"instructions": "<string>",
"message": {
"role": "user",
"parts": [
{
"kind": "text",
"text": "<string>"
}
],
"messageId": "<string>"
},
"path": "Default",
"settings": {
"tools": [],
"tool_approval_required": "none",
"max_iterations": 100,
"max_execution_time": 300,
"evaluators": [
{
"id": "<string>",
"execute_on": "input",
"sample_rate": 50
}
],
"guardrails": [
{
"id": "<string>",
"execute_on": "input",
"sample_rate": 50
}
]
},
"task_id": "<string>",
"fallback_models": [
"<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>"
},
"description": "<string>",
"system_prompt": "<string>",
"memory_stores": [],
"knowledge_bases": [],
"team_of_agents": [],
"metadata": {},
"stream_timeout_seconds": 1800.5
}
'{
"data": {
"type": "agents.execution_started",
"timestamp": "<string>",
"data": {
"agent_task_id": "<string>",
"workspace_id": "<string>",
"trace_id": "<string>"
}
}
}Run agent with streaming response
Dynamically configures and executes an agent while streaming the interaction in real-time via Server-Sent Events (SSE). Intelligently manages agent versioning by reusing existing agents with matching configurations or creating new versions when configurations differ. Combines the flexibility of inline configuration with real-time streaming, making it ideal for dynamic agent interactions with live feedback. The stream provides continuous updates including message chunks, tool executions, and status changes until completion or timeout.
curl --request POST \
--url https://api.orq.ai/v2/agents/stream-run \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"key": "<string>",
"model": "<string>",
"role": "<string>",
"instructions": "<string>",
"message": {
"role": "user",
"parts": [
{
"kind": "text",
"text": "<string>"
}
],
"messageId": "<string>"
},
"path": "Default",
"settings": {
"tools": [],
"tool_approval_required": "none",
"max_iterations": 100,
"max_execution_time": 300,
"evaluators": [
{
"id": "<string>",
"execute_on": "input",
"sample_rate": 50
}
],
"guardrails": [
{
"id": "<string>",
"execute_on": "input",
"sample_rate": 50
}
]
},
"task_id": "<string>",
"fallback_models": [
"<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>"
},
"description": "<string>",
"system_prompt": "<string>",
"memory_stores": [],
"knowledge_bases": [],
"team_of_agents": [],
"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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
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.
1Model configuration for this execution. Can override the agent manifest defaults if the agent already exists.
Specifies the agent's function and area of expertise.
1Provides context and purpose for the agent. Combined with the system prompt template to generate the agent's instructions.
1The A2A format message containing the task for the agent to perform.
Show child attributes
Show child attributes
Message role (user or tool for continuing executions)
user 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.
Optional A2A message ID in ULID format
Entity storage path in the format: project/folder/subfolder/...
The first element identifies the project, followed by nested folders (auto-created as needed).
With project-based API keys, the first element is treated as a folder name, as the project is predetermined by the API key.
"Default"
Show child attributes
Show child attributes
Tools available to the agent
Tool configuration for agent run operations. Built-in tools only require a type and requires_approval, while custom tools (HTTP, Code, Function, MCP) support full inline definitions for on-the-fly creation.
- Google search tool
- Web scraper tool
- Call sub agent tool
- Retrieve agents tool
- Query memory store tool
- Write memory store tool
- Retrieve memory stores tool
- Delete memory document tool
- Retrieve knowledge bases tool
- Query knowledge base tool
- Current date tool
- HTTP Tool (Run)
- Code Tool (Run)
- Function Tool (Run)
- MCP Tool (Run)
If all, the agent will require approval for all tools. If respect_tool, the agent will require approval for tools that have the requires_approval flag set to true. If none, the agent will not require approval for any tools.
all, respect_tool, none Maximum iterations(llm calls) before the agent will stop executing.
x > 1Maximum time (in seconds) for the agent thinking process. This does not include the time for tool calls and sub agent calls. It will be loosely enforced, the in progress LLM calls will not be terminated and the last assistant message will be returned.
x > 2Configuration for an evaluator applied to the agent
Show child attributes
Show child attributes
Unique key or identifier of the evaluator
Determines whether the evaluator runs on the agent input (user message) or output (agent response).
input, output The percentage of executions to evaluate with this evaluator (1-100). For example, a value of 50 means the evaluator will run on approximately half of the executions.
1 <= x <= 100Configuration for a guardrail applied to the agent
Show child attributes
Show child attributes
Unique key or identifier of the evaluator
Determines whether the evaluator runs on the agent input (user message) or output (agent response).
input, output The percentage of executions to evaluate with this evaluator (1-100). For example, a value of 50 means the evaluator will run on approximately half of the executions.
1 <= x <= 100Optional 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.
Optional array of fallback models used when the primary model fails. Fallbacks are attempted in order. All models must support tool calling.
Fallback model for automatic failover when primary model request fails. Supports optional parameter overrides. Can be a simple model ID string or a configuration object with model-specific parameters. Fallbacks are tried in order.
Information about the contact making the request. If the contact does not exist, it will be created automatically.
Show child attributes
Show child attributes
Unique identifier for the contact
"contact_01ARZ3NDEKTSV4RRFFQ69G5FAV"
Display name of the contact
"Jane Doe"
Email address of the contact
URL to the contact's avatar or logo
"https://example.com/avatars/jane-doe.jpg"
A list of tags associated with the contact
["hr", "engineering"]
Thread information to group related requests
Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions.
Show child attributes
Show child attributes
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.
A brief summary of the agent's purpose.
1A custom system prompt template for the agent. If omitted, the default template is used.
1Array of memory store identifiers that are accessible to the agent. Accepts both memory store IDs and keys.
The agents that are accessible to this orchestrator. The main agent can hand off to these agents to perform tasks.
Stream timeout in seconds (1-3600). Default: 1800 (30 minutes)
1 <= x <= 3600Response
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.
Initial event emitted when an agent stream begins. Contains the task ID for tracking, workspace context, and trace ID for observability.
- Agent Execution Started Event
- Agent Started Event
- Agent Thought Event
- Agent Inactive Event
- Agent Errored Event
- Action Review Requested Event
- Action Reviewed Event
- Execution Review Required Event
- Execution Reviewed Event
- Execution Named Event
- Agent Handed Off Event
- Agent Message Created Event
- Tool Execution Started Event
- Tool Execution Finished Event
- Tool Execution Failed Event
- Timeout Event
- Error Event
Show child attributes
Show child attributes
agents.execution_started ISO timestamp of the event
Was this page helpful?