> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Build your first AI agent with Orq.ai
> 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.
### Create your orq.ai account
[Sign up](https://my.orq.ai/auth/signup) for a free **orq.ai** account and create a workspace.
### 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](/docs/integrations/providers/overview) works the same way.
* Go to **AI Gateway > BYOK** in the [AI Studio](https://my.orq.ai).
* Find the [OpenAI](/docs/integrations/providers/openai) provider.
* Click Setup your own API Key and enter the OpenAI API key.
See the full list of supported model providers and how to connect them.
### Enable models in the AI Gateway
With your provider connected:
* Go to **AI Gateway > Models** and search for `gpt-4o`.
* Click on it and toggle it on.
Only enabled models can be selected when creating **Agents** and **Deployments**.
Browse and manage all available models across providers.
### Get your orq.ai API key
Go to **Organization > [API Keys](/docs/administer/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.
```bash macOS / Linux theme={"theme":{"light":"github-light","dark":"github-dark"}}
export ORQ_API_KEY="your-api-key-here"
```
```powershell Windows theme={"theme":{"light":"github-light","dark":"github-dark"}}
$env: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.
1. Open the [AI Studio](https://my.orq.ai) and navigate to your project.
2. Click the **+** button and select **Agent**.
3. In the popup, select **openai/gpt-4o** as the model.
4. Name the agent `my-assistant`.
5. Add a description: `A helpful assistant with web search`.
6. Click Create.
7. 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.`
8. Under **Tools**, add **Web Search** and **Web Scraper**.
9. Click Publish, choose a version bump (**Major**, **Minor**, or **Patch**), and click Publish to confirm.
See the [Agent Studio guide](/docs/agents/agent-studio) for the full walkthrough.
Use the [Create Agent API](/reference/agents/create-agent). 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`.
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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" }
]
}
}'
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from orq_ai_sdk import Orq
import os
with 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}")
```
```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/docs/agents/agent-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](/docs/workspace-mcp) in the editor or AI assistant, then ask the coding assistant:
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 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.
Open the **Agent** in the [AI Studio](https://my.orq.ai) 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](/docs/agents/agent-api#execute-the-agent) (`POST /v3/router/responses`).
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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?"
}'
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
from orq_ai_sdk import Orq
client = 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)
```
```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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).
For long-running agents or chat interfaces, use the streaming API to receive partial output as it is generated. See [Execute the Agent](/docs/agents/agent-api#execute-the-agent) for details.
Ask the assistant to invoke the **Agent** directly:
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
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**.
Open `my-assistant` in the [AI Studio](https://my.orq.ai) 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**:
```prompt theme={"theme":{"light":"github-light","dark":"github-dark"}}
How is my-assistant performing?
```
The assistant calls `query_analytics` and returns a summary:
***
Compare prompts, models, and configurations side by side to find what performs best before shipping.
Score your **Agent**'s outputs automatically with LLM-based, code, or human **Evaluators**.
Give your **Agent** access to your own documents and data with built-in RAG.
Already running agents elsewhere? Connect via OpenTelemetry to get full trace visibility and cost tracking.