Orq.ai Documentation - AI Gateway & LLM Collaboration Platform

This guide walks you through every step of getting started with orq.ai. By the end you will have a working AI agent that can search the web and answer questions, with full visibility into every call it makes.

Create your orq.ai account

Add your provider API key

orq.ai routes requests through provider credentials managed in the workspace, keeping spend and data under full control. This quickstart uses OpenAI as an example, but any supported provider works the same way.

Go to AI Router > Providers in the AI Studio.
Find the OpenAI provider.
Click Setup your own API Key and enter the OpenAI API key.

Supported providers

See the full list of supported model providers and how to connect them.

Enable models in the AI Router

With your provider connected:

Go to AI Router > Models and search for gpt-4o.
Click on it and toggle it on.

Only enabled models can be selected when creating Agents and Deployments.

AI Router

Browse and manage all available models across providers.

Get your orq.ai API key

Go to Organization > API Keys in the left sidebar. Click Create API Key, give it a name, and copy it.Then open a terminal and run the command below, replacing your-api-key-here with the key you just copied. The code samples in the next steps read it from this environment variable.

export ORQ_API_KEY="your-api-key-here"

Create your agent

Build an Agent named my-assistant with OpenAI GPT-4o and the Web Search and Web Scraper tools.

AI Studio
API & SDK
MCP

Open the AI Studio and navigate to your project.
Click the + button and select Agent.
In the popup, select openai/gpt-4o as the model.
Name the agent my-assistant.
Add a description: A helpful assistant with web search.
Click Create.
Set the agent’s instructions to: You are a helpful assistant. Be concise and accurate. When answering questions that require current or up-to-date information, use the web search tool to find the latest data before responding.
Under Tools, add Web Search and Web Scraper.
Click Publish, choose a version bump (Major, Minor, or Patch), and click Publish to confirm.

See the Agent Studio guide for the full walkthrough.

Use the Create Agent API. The key is a unique identifier for invoking the agent later, and path is the Project folder it lives in. Tools are attached under settings.tools using their built-in type.

curl -X POST https://api.orq.ai/v2/agents \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "my-assistant",
    "role": "Assistant",
    "description": "A helpful assistant with web search",
    "instructions": "You are a helpful assistant. Be concise and accurate. When answering questions that require current or up-to-date information, use the web search tool to find the latest data before responding.",
    "path": "YOUR_PROJECT_NAME",
    "model": { "id": "openai/gpt-4o" },
    "settings": {
      "max_iterations": 5,
      "max_execution_time": 300,
      "tools": [
        { "type": "google_search" },
        { "type": "web_scraper" }
      ]
    }
  }'

See Build agents with the API for the full list of built-in tool types and how to attach custom HTTP, function, or MCP tools.

Install the Orq MCP server in the editor or AI assistant, then ask the coding assistant:

Create an agent called "my-assistant" with the instructions "You are a helpful assistant. Be concise and accurate. When answering questions that require current or up-to-date information, use the web search tool to find the latest data before responding." using the openai/gpt-4o model. Add the web_search and web_scraper tools. Create it in the <YOUR_PROJECT_NAME> project.

The assistant calls create_agent and the new Agent appears in the AI Studio.

Call your agent

Send a message to my-assistant and read the response.

AI Studio
API & SDK
MCP

Open the Agent in the AI Studio and use the built-in chat panel to send a message. Conversations and traces are saved automatically.

Invoke the Agent by passing agent/my-assistant as the model on the unified router responses endpoint (POST /v3/router/responses).

curl --request POST \
  --url 'https://my.orq.ai/v3/router/responses' \
  --header "Authorization: Bearer $ORQ_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "agent/my-assistant",
    "input": "What is the capital of France?"
  }'

Install with pip install orq-ai-sdk (Python) or npm install @orq-ai/node (TypeScript).

Streaming responses

For long-running agents or chat interfaces, use the streaming API to receive partial output as it is generated. See Execute the Agent for details.

Ask the assistant to invoke the Agent directly:

Run my-assistant with the message "What is the capital of France?" and print the response.

The assistant uses invoke_agent and returns the Agent’s reply, including any tool calls it made along the way.

View your traces

Every Agent call is automatically traced. Execution history, token counts, latency, and cost are visible in the AI Studio or queryable through MCP.

AI Studio
MCP

Open my-assistant in the AI Studio and click the Traces tab to see the full execution history, including model calls, tool use, token counts, and latency.

Ask the assistant to query analytics for the Agent:

How is my-assistant performing?

The assistant calls query_analytics and returns a summary:

my-assistant analytics returned by the MCP client

Run your first experiment

Compare prompts, models, and configurations side by side to find what performs best before shipping.

Add an evaluator

Score your Agent’s outputs automatically with LLM-based, code, or human Evaluators.

Connect a knowledge base

Give your Agent access to your own documents and data with built-in RAG.

Log your first trace

Already running agents elsewhere? Connect via OpenTelemetry to get full trace visibility and cost tracking.

Get Started

AI Router

Observability

AI Engineering

Optimize

Manage Prompts

Quick Start | Build

Create your orq.ai account

Add your provider API key

Supported providers

Enable models in the AI Router

AI Router

Get your orq.ai API key

Create your agent

Call your agent

View your traces

Run your first experiment

Add an evaluator

Connect a knowledge base

Log your first trace

Get Started

AI Router

Observability

AI Engineering

Optimize

Manage Prompts

Documentation Index

​Create your orq.ai account

​Add your provider API key

Supported providers

​Enable models in the AI Router

AI Router

​Get your orq.ai API key

​Create your agent

​Call your agent

​View your traces

Run your first experiment

Add an evaluator

Connect a knowledge base

Log your first trace

Create your orq.ai account

Add your provider API key

Enable models in the AI Router

Get your orq.ai API key

Create your agent

Call your agent

View your traces