Orq.ai Documentation - AI Gateway & LLM Collaboration Platform

Execute agents already configured. For building and configuring agents, see Build Agents.

Run Agents

For Python and Node.js client libraries, see Orq SDKs.

Send a message to an agent using the Responses API:

curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "agent/my-agent",
  "input": "Help me plan a microservices architecture for our e-commerce platform."
}'

The call waits for the agent to finish and returns a completed response object:

{
  "id": "resp_01K6D8QESESZ6SAXQPJPFQXPFT",
  "object": "response",
  "model": "agent/my-agent",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Here's a microservices architecture..." }]
    }
  ],
  "usage": {
    "input_tokens": 120,
    "output_tokens": 340,
    "total_tokens": 460
  },
  "created_at": 1727694875
}

Pass stream: true to receive the response as a stream of server-sent events instead of waiting for the full result. Use the returned id to continue the conversation.

See the full Create Response API reference.

Pass Variables

Pass variables in the variables field of the execution request:

curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent/my-agent",
    "input": "I need help with my account.",
    "variables": {
      "user_name": "John Smith",
      "user_role": "admin",
      "company_name": "Acme Corp"
    }
  }'

To define which variables the agent uses and configure templating, see Build Agents: Variables and Templates.

Attach Files

Attach files in the content array of an input message item:

Images: Via URL (image_url). For base64-encoded images, also set mime_type (e.g. image/jpeg).
PDFs: Data URI only (file_data). Pass the file as data:application/pdf;base64,<base64-data>. URL links are not supported for PDFs.

Verify the chosen model supports the file types in use. Vision models are required for image and PDF processing.

Attach an image via URL:

curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "agent/image-classifier",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "What can you see in this image?"
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/image.jpg",
          "detail": "auto"
        }
      ]
    }
  ]
}'

Attach a PDF via base64:

PDF_B64="data:application/pdf;base64,$(base64 path/to/document.pdf | tr -d '\n')"

curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
  \"model\": \"agent/my-agent\",
  \"input\": [
    {
      \"role\": \"user\",
      \"content\": [
        { \"type\": \"input_text\", \"text\": \"Summarize this document.\" },
        {
          \"type\": \"input_file\",
          \"filename\": \"document.pdf\",
          \"file_data\": \"$PDF_B64\"
        }
      ]
    }
  ]
}"

See the full Create Response API reference.

Continue a Conversation

API & SDK
MCP

After receiving a response, continue the conversation by passing the previously received response id as previous_response_id in the next request. The agent maintains full context from previous exchanges.

curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "agent/my-agent",
  "previous_response_id": "resp_01K6D8QESESZ6SAXQPJPFQXPFT",
  "input": "Can you expand on the challenges section?"
}'

The continuation returns a new response id for the extended conversation. The agent retains full context from all prior turns.

See the full Create Response API reference.

Task continuation requires direct API or SDK calls. Use list_traces to inspect previous runs and verify task states:

Show me the latest traces for the "support-bot" agent to see which tasks are still active

The assistant uses list_traces filtered to the agent to surface active and inactive task states.

Use Memory Stores

To call the Agent with a memory store, we’ll use the Responses API with an Embedded message and Linked memory.

curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "agent/agent-memories",
  "memory": {
    "entity_id": "customer_456"
  },
  "input": "Do you remember what is my name?"
}'

You can use multiple memory stores per call, ensure that the entity_id sent during the calls maps the same way to all previously declared memory stores during agent creation.

Attach Metadata

Attach arbitrary key-value pairs to a response using the metadata field. Metadata is stored on the response and visible in traces. Use it to tag runs by session, user, environment, or any other dimension useful for filtering in Observability. Values must be strings.

curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "agent/my-agent",
  "input": "Summarize the latest product updates.",
  "metadata": {
    "session_id": "sess_abc123",
    "user_id": "user_456",
    "environment": "production"
  }
}'

The metadata is returned on the response object:

{
  "metadata": {
    "session_id": "sess_abc123",
    "user_id": "user_456",
    "environment": "production"
  }
}

Schedule Agents

Run an agent on a recurring cadence without holding open an HTTP connection. Each scheduled run follows the same execution path, tracing, and billing as a direct API call.

Create a Schedule

AI Studio
API & SDK

Open the agent and go to the Schedules tab. Click New schedule to open the form.

Agent schedule creation form showing Name, Frequency toggle with Hourly, Daily, and Weekly options, Time, Summary, Input, Variables, and Metadata fields.

Field	Description
Name	A display label for the schedule in the UI. Required. Not sent to the agent.
Frequency	Hourly, Daily, or Weekly.
Time	The hour the schedule fires, in local time. Shown for Daily and Weekly.
Pick the day	Day of the week to fire. Shown for Weekly only.
Summary	Auto-generated human-readable description of the schedule.
Input	The user message sent to the agent on each firing. Required, since every agent invocation needs a user message.
Variables	Key-value pairs passed to the agent on each run. See below.
Metadata	Key-value pairs attached to every response this schedule generates. See below.

VariablesUse the Variables section to define values that the agent needs on each run. Variables are sent alongside the input as a distinct payload field, and can be consumed by the agent’s instructions, any configured tool, or a subagent wherever the variable is wired up.

For example, a support agent with an HTTP tool that looks up a customer in an external system can receive customer_id=1234 from the schedule and use it to query the right record on every run. See the screenshot below.

Variables cannot be referenced inside the Input field itself. Wire them into the agent’s instructions, a tool, or a subagent instead.MetadataUse the Metadata section to attach arbitrary key-value pairs to every response generated by this schedule. Metadata is not passed to the agent: it is stored on the trace and can be used to filter traces in Observability, identify which schedule triggered a run, or tag responses for downstream processing.Click Create to activate the schedule. It starts firing at the next matching time.

A saved agent schedule entry showing the schedule name, frequency, next run time, and the configured variables and metadata key-value pairs.

Only cron schedules are supported. Expressions use the 6-field format: sec min hour dom month dow. Three patterns are accepted:

Pattern	Expression	Example
Hourly	`0 0 * * * *`	Fires every hour
Daily	`0 0 <hour> * * *`	`0 0 9 * * *` (9:00 AM UTC daily)
Weekly	`0 0 <hour> * * <day>`	`0 0 9 * * 1` (9:00 AM UTC every Monday)

<day> is 0 (Sunday) through 6 (Saturday). All times are stored in UTC; the UI displays them in user’s local timezone.

Only cron is accepted. Seconds and minutes must be 0, dom and month must be *, and the weekday field must be a single integer 0-6 or * (names like mon and ranges like 1-5 are rejected). To run an agent in response to an event rather than a clock, call the Responses API directly.Expressions that do not match a supported pattern return 400 with "code": "invalid_expression". The message field describes the specific violation, for example invalid schedule expression: day-of-month and month fields must be '*'

curl -X POST https://api.orq.ai/v3/agents/ops_digest/schedules \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cron",
    "expression": "0 0 9 * * *",
    "display_name": "Morning briefing",
    "payload": {
      "input": "Generate the morning briefing for {{region}}",
      "variables": { "region": "EMEA" }
    }
  }'

The TypeScript SDK uses camelCase keys (agentKey, requestBody) and nests the request body under requestBody, while the Python SDK uses flat keyword arguments. Both map to the same wire format.

payload is required. Response (schedule records use _id rather than id):

{
  "_id": "01KPN29WWKSK0VDPJNTKZPVNRB",
  "agent_key": "ops_digest",
  "type": "cron",
  "expression": "0 0 9 * * *",
  "display_name": "Morning briefing",
  "is_active": true,
  "generation": 1,
  "payload": {
    "input": "Generate the morning briefing for {{region}}",
    "variables": { "region": "EMEA" }
  },
  "trigger_count": 0,
  "created": "2026-04-20T10:00:00Z",
  "updated": "2026-04-20T10:00:00Z"
}

Schedule fields:

Field	Type	Description
`display_name`	string	Optional. Label shown in the UI Schedules tab.
`type`	string	Must be `cron`.
`expression`	string	6-field cron expression matching one of the three supported patterns.
`agent_tag`	string	Pin the schedule to a specific agent version. Omit to always run the active version.

Payload fields:

Field	Type	Description
`input`	string or array	The instruction the agent runs on each firing. Same shape as the Responses API `input`. Supports template variables via `{{variable}}`.
`variables`	object	Template variable substitution. Use `{"secret": true, "value": "..."}` for secret values.
`memory_entity_id`	string	Memory store entity to attach on each run.
`metadata`	object	Opaque key/value pairs attached to every response this schedule generates.

generation increments each time type or expression changes and resets trigger_count to 0. Use it to distinguish firings before and after a cadence change.Use agent_tag (string) to pin the schedule to a specific agent version. Omit it to always use the active version:

{
  "type": "cron",
  "expression": "0 0 9 * * *",
  "display_name": "Morning briefing",
  "agent_tag": "v2",
  "payload": { "input": "Generate the morning briefing for {{region}}" }
}

List & Retrieve

AI Studio
API & SDK

All schedules for the agent are listed in the Schedules tab. Click a schedule row to open its details, including trigger count and last fired time.

# List all schedules
curl https://api.orq.ai/v3/agents/ops_digest/schedules \
  -H "Authorization: Bearer $ORQ_API_KEY"

# Get a single schedule
curl https://api.orq.ai/v3/agents/ops_digest/schedules/{schedule_id} \
  -H "Authorization: Bearer $ORQ_API_KEY"

List returns { "schedules": [...] }, most recent first. The single-schedule response includes trigger_count, last_triggered_at (UTC timestamp string; null before the first firing), and generation.

Pause and Resume

AI Studio
API & SDK

Click on the schedule row, then click Enable to toggle the schedule on or off. Field edits saved while paused take effect on the next active run.

# Pause
curl -X PATCH https://api.orq.ai/v3/agents/ops_digest/schedules/{schedule_id} \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

# Resume
curl -X PATCH https://api.orq.ai/v3/agents/ops_digest/schedules/{schedule_id} \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": true }'

Payload-only and agent_tag-only changes do not reset the firing cadence and apply to the next regular run. Changing type or expression shifts the cadence from the PATCH time and resets trigger_count to 0.Lifecycle notes:

Missed firings: Not replayed. If the service is unavailable when a schedule fires, that firing is lost. The schedule resumes on its next scheduled time once service is restored.

Trigger On Demand

API & SDK

Runs the schedule’s payload immediately without affecting its regular cadence. Useful for smoke-testing a new schedule or manually re-running a missed execution.

curl -X POST https://api.orq.ai/v3/agents/ops_digest/schedules/{schedule_id}/execution \
  -H "Authorization: Bearer $ORQ_API_KEY"

Returns 202 Accepted with:

{
  "status": "triggered",
  "schedule_id": "01KPN29WWKSK0VDPJNTKZPVNRB"
}

The run appears in traces as a schedule.<agent_key> leading span roughly 10 seconds later, carrying orq.schedule_id and the full agent execution chain. Schedule-driven cost and token usage appear in usage reports alongside HTTP-invoked runs. Inactive schedules return 400 schedule_inactive.

Delete

AI Studio
API & SDK

Click on the schedule row, then click Delete. The action is immediate and permanent.

curl -X DELETE https://api.orq.ai/v3/agents/ops_digest/schedules/{schedule_id} \
  -H "Authorization: Bearer $ORQ_API_KEY"

Returns 204 No Content. Deleting the agent itself removes all its schedules automatically.

Examples

API & SDK

Daily morning briefing (9 AM UTC)

curl -X POST https://api.orq.ai/v3/agents/ops_digest/schedules \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cron",
    "expression": "0 0 9 * * *",
    "display_name": "Daily morning briefing",
    "agent_tag": "v2",
    "payload": {
      "input": "Generate the morning briefing for {{region}}",
      "variables": { "region": "EMEA" },
      "metadata": { "run_source": "daily-briefing" }
    }
  }'

Hourly background summarizer (with memory)

curl -X POST https://api.orq.ai/v3/agents/knowledge_indexer/schedules \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cron",
    "expression": "0 0 * * * *",
    "display_name": "Hourly knowledge indexer",
    "payload": {
      "input": "Fetch new entries and update the knowledge base",
      "memory_entity_id": "mem_entity_123"
    }
  }'

memory_entity_id attaches a Memory Store entity to every run. The agent can read from and write to the store on each firing, accumulating context across executions.

Scheduled run with secret variables

curl -X POST https://api.orq.ai/v3/agents/daily_sync/schedules \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cron",
    "expression": "0 0 3 * * *",
    "display_name": "Nightly warehouse sync",
    "payload": {
      "input": "Sync new rows from {{table}} to the analytics warehouse",
      "variables": {
        "table": "orders",
        "warehouse_token": { "secret": true, "value": "sk-secret-123" }
      }
    }
  }'

Secret values are redacted from traces and stripped from the stored payload’s observable form, same as the Responses API.

Agent and Task States

AI Studio
API & SDK
MCP

Agent execution can take a long time. If the agent appears to be hanging, it is most likely still running. Wait and check the panel again later.

Agent states:

State	Description
Active	Execution in progress; continuation requests blocked
Inactive	Waiting for user input or tool results; ready for continuation
Error	Execution failed; continuation blocked
Approval Required	Tool execution requires manual approval (coming soon)

Task states:

State	Description
Submitted	Task created and queued for execution
Working	Agent actively processing
Input Required	Waiting for user input or tool results
Completed	Task finished successfully
Failed	Task encountered an error
Canceled	Task was manually canceled

Response status values:

Status	Description
`in_progress`	Agent is actively processing
`completed`	Response finished successfully
`failed`	Response encountered an error

The status field is returned on every response object from POST /v3/router/responses. See the Create Response API reference for the full response shape.

Inspect task states through traces:

Show me the last 10 traces for "support-bot" and summarize their completion states

The assistant uses list_traces filtered to the agent and surfaces the state distribution.

Multi-Agent Workflows

AI Studio
API & SDK
MCP

Multi-agent workflows are configured at the agent level. Each agent in a team is created individually, then the orchestrator references sub-agents through its team_of_agents configuration.The Description field on each sub-agent is critical: orchestrators use it to decide when to delegate.

To configure multi-agent setups, see Build Agents: Instructions for how to write descriptions that enable effective delegation.

Multi-agent workflows use a hierarchical system:

Orchestrator: Main agent that delegates tasks using call_sub_agent.
Sub-agents: Specialized agents for specific functions.
Delegation: Automatic routing based on sub-agent descriptions and capabilities.

Step 1: Create sub-agents.Create each specialized agent individually. The description field drives orchestrator delegation decisions.Step 2: Create the orchestrator.Reference sub-agents in the team_of_agents array. Include retrieve_agents and call_sub_agent tools.

curl -X POST https://api.orq.ai/v2/agents \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "orchestrator",
  "role": "Task Coordinator",
  "description": "Coordinates specialized agents to handle diverse user requests",
  "instructions": "Answer the user using your sub-agents. Use retrieve_agents to discover available agents, then call_sub_agent to delegate tasks based on their capabilities.",
  "settings": {
    "max_iterations": 15,
    "max_execution_time": 600,
    "tools": [
      { "type": "retrieve_agents" },
      { "type": "call_sub_agent" }
    ]
  },
  "model": "openai/gpt-4o",
  "path": "Default/agents",
  "team_of_agents": [
    { "key": "specialist-a", "role": "Handles domain A" },
    { "key": "specialist-b", "role": "Handles domain B" }
  ]
}'

Step 3: Invoke the orchestrator.Invoke the orchestrator the same way as any other agent. It handles delegation internally.

Orchestrator agents must include retrieve_agents to discover sub-agents before delegating. Add explicit instructions: “Use retrieve_agents to see what specialized agents are available, then call_sub_agent to delegate.”

Update the orchestrator at any time with PATCH /v2/agents/{key} to add or remove sub-agents from team_of_agents.

Find all agents available as sub-agents:

Search for all agents in the Default/agents project

The assistant uses search_entities with type: "agent" to list available agents.

Set up an orchestrator:

Create an orchestrator agent that coordinates "youth-agent" and "formal-agent" for tone-matched responses

The assistant uses create_agent with the team_of_agents array and retrieve_agents / call_sub_agent tools.

Traces

AI Studio
API & SDK
MCP

The Traces tab in the agent page shows execution logs filtered to the agent automatically.

Traces tab for the bank_creditcard_agent showing a list of invoke-agent runs with timestamps, duration, and cost, filtered to this agent.

Trace data includes:

Execution history with timestamps
Input and output for each call
Token usage and cost per execution
Execution duration and performance metrics
Errors and debugging information
Tool calls executed (function, HTTP, code, or MCP calls)
Knowledge retrieval results and RAG context
Memory store interactions

List recent traces for an agent:

Show me the last 20 traces for "support-bot" sorted by most recent

The assistant uses list_traces with a filter on the agent key.

Inspect a specific trace:

Show me the full span details for trace ID 01K6D8QESESZ6SAXQPJPFQXPFT

The assistant uses list_spans to retrieve the full execution tree for that trace.

Debug errors:

Find all failed traces for "support-bot" from the last 24 hours and summarize the errors

The assistant uses list_traces filtered by status:=ERROR and time range, then get_span on relevant spans to surface root causes.

Trace Views

Each trace can be inspected in three views:

Trace
Thread
Timeline

The Trace view shows the full execution tree for a single agent run. Each step is displayed hierarchically, including LLM calls, tool invocations, knowledge retrievals, and memory interactions.

Trace view showing the single-product-agent span tree with nested invoke-agent, gpt-4o chat-completion, and current_date spans, with properties panel on the right.

Creating Custom Views

Save frequently used filter combinations as reusable views:

Set the desired filters.
Click All Rows (top right).
Select Create New View.
Give the view a title.
Optionally check Set view private (default is shared with project members).

For advanced filtering and cross-agent analysis, see Traces.

​Run Agents

​Pass Variables

​Attach Files

​Continue a Conversation

​Use Memory Stores

​Attach Metadata

​Schedule Agents

​Create a Schedule

​List & Retrieve

​Pause and Resume

​Trigger On Demand

​Delete

​Examples

​Agent and Task States

​Multi-Agent Workflows

​Traces

​Trace Views

​Creating Custom Views

Run Agents

Pass Variables

Attach Files

Continue a Conversation

Use Memory Stores

Attach Metadata

Schedule Agents

Create a Schedule

List & Retrieve

Pause and Resume

Trigger On Demand

Delete

Examples

Agent and Task States

Multi-Agent Workflows

Traces

Trace Views

Creating Custom Views