Orq MCP is live: Use natural language to interrogate traces, spot regressions, and experiment your way to optimal AI configurations. Available in Claude Desktop, Claude Code, Cursor, and more. Start now →
Build an AI agent with Orq.ai: create the agent, connect a model, add tools, and call it from your code. Beginner-friendly, no AI experience needed.
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.
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 Settings > 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.
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.
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" } ] } }'
from orq_ai_sdk import Orqimport oswith Orq(api_key=os.getenv("ORQ_API_KEY", "")) as orq: agent = orq.agents.create( 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"}, ], }, ) print(f"Agent created: {agent.key}")
import { Orq } from "@orq-ai/node";const orq = new Orq({ apiKey: process.env.ORQ_API_KEY ?? "" });const agent = await orq.agents.create({ 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: { maxIterations: 5, maxExecutionTime: 300, tools: [ { type: "google_search" }, { type: "web_scraper" }, ], },});console.log(`Agent created: ${agent.key}`);
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.
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?" }'
import osfrom orq_ai_sdk import Orqclient = Orq( api_key=os.environ["ORQ_API_KEY"], server_url="https://my.orq.ai",)response = client.responses.create( model="agent/my-assistant", input="What is the capital of France?",)print(response.output[0]["content"][0]["text"])print(response.usage)
import { Orq } from "@orq-ai/node";const client = new Orq({ serverURL: "https://my.orq.ai", apiKey: process.env.ORQ_API_KEY,});const response = await client.responses.create({ model: "agent/my-assistant", input: "What is the capital of France?",});console.log(response.output[0].content[0].text);console.log(response.usage);
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.
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.
my-assistant traces in orq.ai Studio
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.