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/v2/agents/my-agent/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "background": false,
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "Help me plan a microservices architecture for our e-commerce platform."
      }
    ]
  }
}'

With background: false (default), the call waits for the agent to finish and returns a completed task object including an output array:

{
  "id": "01K6D8QESESZ6SAXQPJPFQXPFT",
  "contextId": "0ae12412-cdea-408e-a165-9ff8086db400",
  "kind": "task",
  "status": {
    "state": "completed",
    "timestamp": "2025-09-30T12:14:35.123Z",
    "message": {
      "role": "agent",
      "parts": [{ "kind": "text", "text": "Here's a microservices architecture..." }]
    }
  },
  "output": [
    {
      "parts": [{ "kind": "text", "text": "Here's a microservices architecture..." }]
    }
  ],
  "metadata": {
    "orq_agent_key": "my-agent"
  }
}

Set background: true to return immediately without waiting: the response will have status.state: "submitted" and no output. 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/v2/agents/my-agent/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "role": "user",
      "parts": [{"kind": "text", "text": "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 parts array of the message:

Images: Via URL (uri) or base64 encoding (bytes)
PDFs: Base64 encoding only (bytes). URI links are not supported for PDFs.
MIME Types: Required. Specify the correct mimeType (e.g. image/jpeg, application/pdf).

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/v2/agents/image-classifier/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "What can you see in this image?"
      },
      {
        "kind": "file",
        "file": {
          "uri": "https://example.com/image.jpg",
          "mimeType": "image/jpeg",
          "name": "image.jpg"
        }
      }
    ]
  }
}'

Attach a PDF via base64: Convert the file to base64 first:

Python

import base64

def file_to_base64(file_path: str) -> str:
    with open(file_path, "rb") as file:
        return base64.b64encode(file.read()).decode("utf-8")

pdf_base64 = file_to_base64("path/to/document.pdf")

Then include it in the message:

{
  "kind": "file",
  "file": {
    "bytes": "<base64-encoded-content>",
    "mimeType": "application/pdf",
    "name": "document.pdf"
  }
}

See the full Create Response API reference.

Continue a Task

API & SDK
MCP

After receiving a task response, continue the conversation by passing the previously received task_id in the next request. The agent maintains full context from previous exchanges.When polling task state, a task in input-required state means the agent is waiting and ready for continuation (the agent is in inactive state). Pass the same task_id to resume.

curl -X POST https://api.orq.ai/v2/agents/my-agent/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "task_id": "01K6D8QESESZ6SAXQPJPFQXPFT",
  "background": false,
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "Can you expand on the challenges section?"
      }
    ]
  }
}'

The continuation returns a new task 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/v2/agents/agent-memories/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "memory": {
    "entity_id": "customer_456"
  },
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "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.

Schedule Agents

Run an agent on a recurring or one-off 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 UTC, 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 (UTC)	The hour the schedule fires. 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.

Three schedule types are supported:

Type	Expression	Example	Fires
`interval`	`@every <duration>`	`@every 6h`	Every 6 hours from creation
`cron`	6-field cron: `sec min hour dom month dow`	`0 0 9 * * mon-fri`	9:00 UTC Mon–Fri
`once`	`@at <RFC3339-UTC>`	`@at 2026-06-01T09:00:00Z`	Exactly once

Predefined descriptors also work: @hourly, @daily, @weekly, @monthly, @yearly. All timestamps are UTC.

Minimum interval is 1 hour. Expressions that fire more frequently (e.g. @every 30m, */5 * * * * *) are rejected at validation time. once schedules are exempt. To run an agent in response to an event rather than a clock, call the Responses API directly.

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 * * mon-fri",
    "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 * * mon-fri",
  "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"
}

Payload fields:

Field	Type	Description
`input`	string	The instruction the agent runs on each firing. 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 * * mon-fri",
  "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:

once schedules: After firing, is_active flips to false automatically. PATCH both is_active: true and a new future expression to re-run:

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, "expression": "@at 2026-07-01T09:00:00Z" }'

Missed firings: Not replayed. If the service is unavailable when a schedule fires, that firing is lost. Cron and interval schedules resume on their 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.

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

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

An agent in inactive state accepts continuation requests. An agent in active, error, or approval_required state does not.

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.

Get Started

AI Router

Observability

AI Engineering

Optimize

Manage Prompts

Run Agents

Run Agents

Pass Variables

Attach Files

Continue a Task

Use Memory Stores

Schedule Agents

Create a Schedule

List & Retrieve

Pause and Resume

Trigger On Demand

Delete

Agent and Task States

Multi-Agent Workflows

Traces

Trace Views

Creating Custom Views

Get Started

AI Router

Observability

AI Engineering

Optimize

Manage Prompts

Documentation Index

​Run Agents

​Pass Variables

​Attach Files

​Continue a Task

​Use Memory Stores

​Schedule Agents

​Create a Schedule

​List & Retrieve

​Pause and Resume

​Trigger On Demand

​Delete

​Agent and Task States

​Multi-Agent Workflows

​Traces

​Trace Views

​Creating Custom Views

Run Agents

Pass Variables

Attach Files

Continue a Task

Use Memory Stores

Schedule Agents

Create a Schedule

List & Retrieve

Pause and Resume

Trigger On Demand

Delete

Agent and Task States

Multi-Agent Workflows

Traces

Trace Views

Creating Custom Views