> ## 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 Agents
> Build AI agents in Orq.ai: set instructions, pick models, and attach tools, knowledge bases, memory, and guardrails via AI Studio, the API, or Orq MCP.
Configure every aspect of an agent before execution. For running agents, see [Run Agents](/docs/ai-studio/ai-engineering/run-agents).
Common use cases include customer support assistants, RAG-powered document Q\&A, coding assistants, research and data extraction pipelines, and any multi-step AI workflow that needs tools, memory, and knowledge bases.
## Create an Agent
**AI Studio** is the visual interface for building, configuring, and testing AI agents without writing code.
Open [the AI Studio](https://my.orq.ai).
Open **Agents** in the **Managed Agents** section, then click Agent.
Name and describe the Agent. Use the AI assistant to pre-configure role and instructions, or choose **Start from scratch** for full manual control.
AI Studio opens with a customizable template.
AI Studio has three panels:
* **Instructions Panel (left)**: Define what the agent does and how it behaves.
* **Configuration Panel (center)**: Set up model, tools, context, evaluators, and constraints.
* **Chat Panel (right)**: Chat with the agent and test their behaviour.
Save the configuration at any time using the Publish button.
The Agents API provides endpoints for creating, executing, and managing AI agents with support for tools, memory, knowledge bases, and real-time streaming. Payloads follow the [A2A Protocol](https://a2a-protocol.org/latest/).
**Prerequisites:**
* A Project in the workspace (used as the `path` for resources)
* An [API Key](/docs/ai-studio/organization/api-keys)
* Optionally, one of the [Orq SDKs](/reference/client-libraries)
Create an agent with a minimal configuration:
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://my.orq.ai/v2/agents \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"key": "my-agent",
"role": "Assistant",
"description": "A helpful assistant for general tasks",
"instructions": "Be helpful and concise",
"path": "Default/agents",
"model": {
"id": "openai/gpt-5.6-sol",
"parameters": {
"temperature": 1
}
},
"settings": {
"max_iterations": 3,
"max_execution_time": 300,
"tools": []
}
}'
```
```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-agent",
role="Assistant",
description="A helpful assistant for general tasks",
instructions="Be helpful and concise",
path="Default/agents",
model={"id": "openai/gpt-5.6-sol", "parameters": {"temperature": 1}},
settings={
"max_iterations": 3,
"max_execution_time": 300,
"tools": []
}
)
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-agent',
role: 'Assistant',
description: 'A helpful assistant for general tasks',
instructions: 'Be helpful and concise',
path: 'Default/agents',
model: { id: 'openai/gpt-5.6-sol', parameters: { temperature: 1 } },
settings: { maxIterations: 3, maxExecutionTime: 300, tools: [] }
});
console.log(`Agent created: ${agent.key}`);
```
See the full [Create Agent API reference](/reference/agents/create-agent).
Use the [Orq MCP server](/docs/ai-studio/integrations/code-assistants/orq-mcp) to manage agents directly from an AI code assistant.
**Find an existing agent:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Search for the "support-bot" agent in my workspace
```
The assistant uses `search_entities` with `type: "agent"` to locate agents by name or key.
***
**Retrieve full agent configuration:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Get the full configuration of the "support-bot" agent
```
The assistant uses `get_agent` to return instructions, model, tools, and all settings.
***
**Create an agent:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Create a customer support agent called "support-bot" in the Default/agents project. Use GPT-5.6 Sol with temperature 1 and give it a professional, concise tone.
```
The assistant uses `create_agent` with the specified key, path, model, model parameters, and instructions.
Create an agent with a minimal configuration using [`orq agents create`](/reference/cli):
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq agents create \
--key my-agent \
--role Assistant \
--description "A helpful assistant for general tasks" \
--instructions "Be helpful and concise" \
--path Default/agents \
--model '{"id": "openai/gpt-5.6-sol", "parameters": {"temperature": 1}}' \
--settings '{"max_iterations": 3, "max_execution_time": 300, "tools": []}'
```
See [install and setup](/reference/cli) to get started with the CLI. Run `orq agents create --help` for the full flag reference.
## Select a Model
Select the language model that powers the agent from the Configuration panel.
Available models depend on the [AI Gateway](/docs/ai-gateway/using-the-router) configuration. Switch models at any time and the agent uses the new model on its next execution.
**Considerations when selecting a model:**
* **Speed vs Quality**: Smaller models are faster but less capable.
* **Cost**: Larger models cost more per token.
* **Capability**: Some tasks require more advanced reasoning models.
* **Latency**: Models that use reasoning tokens add latency. Consider the impact of Max Iterations and Max Execution Time constraints.
The `model` field supports two formats.
**Object format (recommended)**: Specify model parameters alongside the model ID.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"model": {
"id": "openai/gpt-5.6-luna",
"parameters": {
"temperature": 1
}
}
```
**String format**: For simple cases without custom parameters.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"model": "openai/gpt-5.6-luna"
```
Use the `provider/model-id` format. For a complete list of supported models, see the [AI Gateway](/docs/ai-gateway/using-the-router).
See the full [API reference](/reference/agents/create-agent) for all supported model parameters.
**List available models:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
List all available chat models in my workspace
```
The assistant uses `list_models` with `type: "chat"`.
***
**Update the model on an existing agent:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Switch the "support-bot" agent to use GPT-5.6 Luna
```
The assistant uses `update_agent` with `model: { "id": "openai/gpt-5.6-luna" }`.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq agents update my-agent \
--model '{"id": "openai/gpt-5.6-luna", "parameters": {"temperature": 1}}'
```
See [install and setup](/reference/cli) to get started with the CLI. Run `orq agents update --help` for the full flag reference.
## Configure Instructions
The **Instructions** panel defines the agent's behavior, goals, and personality. Write clear, exhaustive instructions to keep behavior consistent across executions.
Use the AI button to generate effective instructions for the agent.
```
You are an experienced customer support specialist for the SaaS company **{company_name}**.
Your job is to provide clear, concise, and accurate answers to customer inquiries about {product_name}.
Responses should be brief, no more than **150 words**, and include any necessary next-step actions.
**Step-by-Step Instructions**
1. **Read the query**: `{customer_query}`.
2. **Extract the core problem** (e.g., password reset, API error, pricing).
3. **Draft a concise answer**: no more than 150 words.
4. **Add suggested next steps**: at most 3 actions the customer can take.
5. **End with a friendly closing** and a reminder of available support channels (`{support_contact}`).
```
The key instruction fields on the agent object:
| Field | Description |
| --------------- | ------------------------------------------------------------ |
| `instructions` | Main instructions for the agent's behavior and goals |
| `role` | Agent's responsibility and coverage, reinforced at execution |
| `description` | Used by other agents to discover and delegate to this agent |
| `system_prompt` | Additional system-level context injected before execution |
Update instructions on an existing agent:
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PATCH https://my.orq.ai/v2/agents/my-agent \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"instructions": "You are a helpful assistant. Be concise and accurate.",
"role": "General Assistant",
"description": "A general-purpose assistant for answering questions and completing tasks"
}'
```
```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.update(
agent_key="my-agent",
instructions="You are a helpful assistant. Be concise and accurate.",
role="General Assistant",
description="A general-purpose assistant for answering questions and completing tasks"
)
```
```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'] ?? '' });
await orq.agents.update({
instructions: 'You are a helpful assistant. Be concise and accurate.',
role: 'General Assistant',
description: 'A general-purpose assistant for answering questions and completing tasks'
}, 'my-agent');
```
See the full [Update Agent API reference](/reference/agents/update-agent).
**Update agent instructions:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Show me the current instructions for "support-bot", then update them to always respond in the user's language
```
The assistant uses `get_agent` to retrieve the current instructions, then `update_agent` with the revised `instructions` field.
***
**Set role and description:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Update the "support-bot" agent to add a detailed description of its capabilities for use in multi-agent workflows
```
The assistant uses `update_agent` with the `description` field.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq agents update my-agent \
--instructions "You are a helpful assistant. Be concise and accurate." \
--role "General Assistant" \
--description "A general-purpose assistant for answering questions and completing tasks"
```
See [install and setup](/reference/cli) to get started with the CLI. Run `orq agents update --help` for the full flag reference.
### Role and Description
* **Role**: Defines the agent's responsibility and coverage. Sent to the agent during execution to reinforce its perimeter.
* **Description**: Used by other agents in multi-agent setups to understand what this agent can do. Write a detailed description so orchestrators delegate correctly.
To learn more about multi-agent orchestration, see [Multi-Agent Workflows](/docs/ai-studio/ai-engineering/run-agents#multi-agent-workflows).
### Skills
[Skills](/docs/ai-studio/ai-engineering/skills) can be used with agents in two ways:
**Static reference:** Use `{{skill.key}}` directly in the instruction text to inject a Skill's content at that position on every run. Use this for content that should always be present, such as a company policy or a standard output format.
**On-demand attachment:** Click Skills in the **Skills** section of the agent configuration to attach a Skill.
Attached Skills are available for the agent to invoke when relevant, without being statically embedded in the instructions. Any update to a Skill propagates automatically to every agent that references or has it attached.
### Variables and Templates
Reference dynamic values in agent instructions using double braces: `{{variableName}}`. Pass a key-value map in the `variables` field at invocation time and **Orq.ai** substitutes each variable before execution.
**Orq.ai** supports three template engines. Select the **Template Engine** from the Agent Settings panel:
* **Text** (default): variables use `{{double_braces}}` syntax.
* **Jinja**: full templating with conditionals, loops, filters, and more.
* **Mustache**: logic-less templating with sections.
**Instructions template:**
```jinja theme={"theme":{"light":"github-light","dark":"github-dark"}}
You are a support assistant for {{company_name}}.
{% if user_tier == "premium" %}
{{customer_name}} is a premium customer. Greet them by name and let them know they have priority support.
{% else %}
{{customer_name}} is on the free plan. Standard response time is 24 hours.
{% endif %}
```
**Invoke the agent:**
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://my.orq.ai/v3/router/responses \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "agent/support-bot",
"input": "I need help.",
"variables": {
"company_name": "Acme",
"customer_name": "Sarah",
"user_tier": "premium"
}
}'
```
**Instructions template:**
```handlebars theme={"theme":{"light":"github-light","dark":"github-dark"}}
You are a support assistant for {{company_name}}.
{{# is_premium}}
{{customer_name}} is a premium customer. Priority support with a 2-hour SLA.
{{/ is_premium}}
{{^ is_premium}}
{{customer_name}} is on the free plan. Standard response time is 24 hours.
{{/ is_premium}}
```
**Invoke the agent:**
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://my.orq.ai/v3/router/responses \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "agent/support-bot",
"input": "I need help.",
"variables": {
"company_name": "Acme",
"customer_name": "Sarah",
"is_premium": true
}
}'
```
For a complete reference of all template features including filters, loops, and more, see [Prompt Templating](/docs/ai-studio/prompts/prompt-templating).
To test declared variables without calling the API, use the Chat Panel's Variables button. See [Test in the Chat Panel](#test-in-the-chat-panel) below.
Use `{{variableName}}` placeholders in agent instructions and pass the corresponding values in the `variables` field at invocation time.
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
--url 'https://my.orq.ai/v3/router/responses' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"model": "agent/my-agent",
"input": "I need help with my account.",
"variables": {
"user_name": "John Smith",
"user_role": "admin",
"company_name": "Acme Corp"
}
}'
```
```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:
response = orq.responses.create(
model="agent/my-agent",
input="I need help with my account.",
variables={
"user_name": "John Smith",
"user_role": "admin",
"company_name": "Acme Corp",
},
)
print(response.output[0]["content"][0]["text"])
```
```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 response = await orq.responses.create({
model: 'agent/my-agent',
input: 'I need help with my account.',
variables: {
user_name: 'John Smith',
user_role: 'admin',
company_name: 'Acme Corp',
},
});
console.log(response.output?.[0]?.content?.[0]?.text);
```
See the full [Create Response API reference](/reference/responses/create-response).
**Add variables to agent instructions:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Update "support-bot" instructions to use {{user_name}}, {{user_role}}, and {{company_name}} variables
```
The assistant uses `update_agent` with the revised `instructions` field containing `{{variable}}` placeholders.
**Step 1 — add `{{variable}}` placeholders to the agent's instruction template:**
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq agents update my-agent \
--instructions "You are a helpful assistant for {{user_name}} ({{user_role}}) at {{company_name}}. Be concise and accurate."
```
**Step 2 — supply variable values at runtime:**
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq responses create \
--model agent/my-agent \
--input '"I need help with my account."' \
--variables user_name="John Smith" --variables user_role=admin --variables company_name="Acme Corp"
```
See [install and setup](/reference/cli) to get started with the CLI. Run `orq agents update --help` and `orq responses create --help` for the full flag reference.
## Add Tools
Tools extend the agent's capabilities by allowing it to interact with external systems, execute code, or fetch information. Add tools from the Tool selection modal.
Declare tools in the `settings.tools` array when creating or updating an agent.
**Add a standard tool to an agent:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Add the google_search and current_date tools to the "research-bot" agent
```
The assistant uses `update_agent` with the updated `settings.tools` array.
***
**Add a custom tool by key:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Add the HTTP tool with key "weather_api" to the "weather-bot" agent
```
The assistant uses `update_agent` with `{"type": "http", "key": "weather_api"}` in `settings.tools`.
Declare tools in the `settings.tools` array using [`orq agents update`](/reference/cli):
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq agents update my-agent \
--settings '{"tools": [{"type": "google_search"}, {"type": "current_date"}]}'
```
See [install and setup](/reference/cli) to get started with the CLI. Run `orq agents update --help` for the full flag reference.
### Standard Tools
The following tools are available to all agents out of the box:
| Tool | Name | Description |
| ------------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Current Date | `current_date` | Provides the current date to the model |
| Web Search | `google_search` | Lets an agent perform a web search |
| Web Scraper | `web_scraper` | Lets an agent scrape a web page |
| Query Memory Store | `query_memory_store` | Lets an agent query a [Memory Store](/docs/ai-studio/ai-engineering/build-agents#connect-memory-stores). Added automatically when using a Memory Store. |
| Retrieve Memory Stores | `retrieve_memory_stores` | Lets an agent fetch [Memory Stores](/docs/ai-studio/ai-engineering/build-agents#connect-memory-stores). Added automatically when using a Memory Store. |
| Write Memory Store | `write_memory_store` | Lets an agent save to a [Memory Store](/docs/ai-studio/ai-engineering/build-agents#connect-memory-stores). Added automatically when using a Memory Store. |
| Delete Memory Document | `delete_memory_document` | Lets an agent delete a memory document. Added automatically when using a Memory Store. |
| Query Knowledge Base | `query_knowledge_base` | Lets an agent query a [Knowledge Base](/docs/ai-studio/ai-engineering/build-agents#connect-knowledge-bases). Added automatically when using a Knowledge Base. |
| Retrieve Knowledge Bases | `retrieve_knowledge_bases` | Lets an agent fetch a [Knowledge Base](/docs/ai-studio/ai-engineering/build-agents#connect-knowledge-bases). Added automatically when using a Knowledge Base. |
| Call Sub Agent | `call_sub_agent` | Lets an agent invoke another agent. |
| Retrieve Agents | `retrieve_agents` | Lets an agent fetch other agents. |
| Advisor | `advisor` | Lets an agent consult a second, more capable model for advice. See [Advisor and Sidekick Tools](/docs/ai-studio/ai-engineering/build-agents#advisor-and-sidekick-tools). |
| Sidekick | `sidekick` | Lets an agent delegate a self-contained subtask to a second model. See [Advisor and Sidekick Tools](/docs/ai-studio/ai-engineering/build-agents#advisor-and-sidekick-tools). |
Create custom tools to use within Agents:
* [Function Tool](/docs/ai-studio/ai-engineering/create-tools#function-tool)
* [HTTP Tool](/docs/ai-studio/ai-engineering/create-tools#http-tool)
* [JSON Schema Tool](/docs/ai-studio/ai-engineering/create-tools#json-schema-tool)
* [MCP Servers](/docs/ai-gateway/mcp-portal/mcp-servers)
* [Python Tool](/docs/ai-studio/ai-engineering/create-tools#python-tool)
Agent instructions must **explicitly mention the available tools** so the model knows when and how to invoke them.
The model will not use tools unless the instructions clearly describe:
* What each tool does
* When to use it
* How to call it
**Example: Web Search Agent**
```
You are a research assistant. Your job is to find current information.
**Available Tools:**
1. **google_search** - Search the internet for information
- Use this when you need current information or factual data
- Provide clear search queries
- Example: When asked "What are the latest AI developments?", call google_search with "latest AI developments 2025"
```
| Tool | Name | Description |
| ------------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Current Date | `current_date` | Provides the current date to the model |
| Web Search | `google_search` | Lets an agent perform a web search |
| Web Scraper | `web_scraper` | Lets an agent scrape a web page |
| Query Memory Store | `query_memory_store` | Lets an agent query a [Memory Store](/docs/ai-studio/ai-engineering/build-agents#connect-memory-stores). |
| Retrieve Memory Stores | `retrieve_memory_stores` | Lets an agent fetch [Memory Stores](/docs/ai-studio/ai-engineering/build-agents#connect-memory-stores). |
| Write Memory Store | `write_memory_store` | Lets an agent save to a [Memory Store](/docs/ai-studio/ai-engineering/build-agents#connect-memory-stores). |
| Delete Memory Document | `delete_memory_document` | Lets an agent delete a memory document. |
| Query Knowledge Base | `query_knowledge_base` | Lets an agent query a [Knowledge Base](/docs/ai-studio/ai-engineering/build-agents#connect-knowledge-bases). |
| Retrieve Knowledge Bases | `retrieve_knowledge_bases` | Lets an agent fetch a [Knowledge Base](/docs/ai-studio/ai-engineering/build-agents#connect-knowledge-bases). |
| Call Sub Agent | `call_sub_agent` | Lets an agent invoke another agent. |
| Retrieve Agents | `retrieve_agents` | Lets an agent fetch other agents. |
| Advisor | `advisor` | Lets an agent consult a second, more capable model for advice. See [Advisor and Sidekick Tools](/docs/ai-studio/ai-engineering/build-agents#advisor-and-sidekick-tools). |
| Sidekick | `sidekick` | Lets an agent delegate a self-contained subtask to a second model. See [Advisor and Sidekick Tools](/docs/ai-studio/ai-engineering/build-agents#advisor-and-sidekick-tools). |
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"settings": {
"tools": [
{ "type": "current_date" },
{ "type": "google_search" },
{ "type": "web_scraper" },
{ "type": "query_memory_store" },
{ "type": "retrieve_memory_stores" },
{ "type": "write_memory_store" },
{ "type": "delete_memory_document" },
{ "type": "query_knowledge_base" },
{ "type": "retrieve_knowledge_bases" },
{ "type": "call_sub_agent" },
{ "type": "retrieve_agents" }
]
}
}
```
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq agents update my-agent \
--settings '{"tools": [{"type": "current_date"}, {"type": "google_search"}, {"type": "web_scraper"}, {"type": "query_memory_store"}, {"type": "retrieve_memory_stores"}, {"type": "write_memory_store"}, {"type": "delete_memory_document"}, {"type": "query_knowledge_base"}, {"type": "retrieve_knowledge_bases"}, {"type": "call_sub_agent"}, {"type": "retrieve_agents"}]}'
```
See [install and setup](/reference/cli) to get started with the CLI. Run `orq agents update --help` for the full flag reference.
### Advisor and Sidekick Tools
An **Agent** runs every step of a conversation on a single model. That model has to be affordable enough for routine steps, yet capable enough for the hardest reasoning step in the run. Sizing the model for the hardest step makes every step expensive; sizing it for routine steps makes the agent fail exactly when quality matters most. Self-contained subtasks cause a related problem: drafting or summarizing inside the main loop fills the context window with intermediate work the conversation does not need.
The Advisor and Sidekick tools solve this by giving the agent a second model, configured at design time, that it can call mid-run:
* **Advisor**: the agent consults a more capable model when it is stuck or faces a high-stakes decision. The advisor receives the recent conversation transcript plus the agent's question and returns short, actionable guidance. The agent stays in control and produces the final answer itself.
* **Sidekick**: the agent delegates a concrete subtask (drafting, extraction, summarization, transformation) to a second model and receives only the finished result. The sidekick does not see the conversation, so the subtask runs in isolation and the main context stays small.
This enables a cost and quality mix inside one agent: run a fast, low-cost executor model and escalate to a stronger model only in the moments that need it, without building a separate sub-agent.
For both tools, the secondary model and its parameters are fixed in the tool configuration. The agent only supplies the question or task at run time. Each secondary call is metered separately and appears as a nested span in [Traces](/docs/ai-studio/observability/traces). When the secondary model call fails, the agent receives an error message as the tool result and the run continues.
In **AI Studio**, add Advisor or Sidekick from the tool library and open the tool to configure the secondary model and parameters. Via the API, set the fields in the tool's `configuration` object.
#### Advisor
The advisor receives the newest conversation turns within the `max_transcript_tokens` budget, plus the agent's question and optional context, and replies with concise advice.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"type": "advisor",
"configuration": {
"model": "openai/gpt-4o",
"max_uses": 3,
"max_transcript_tokens": 8000
}
}
```
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq agents update my-agent \
--settings '{"tools": [{"type": "advisor", "configuration": {"model": "openai/gpt-4o", "max_uses": 3, "max_transcript_tokens": 8000}}]}'
```
| Field | Required | Description |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `model` | Yes | Secondary model in `provider/model` format. |
| `max_uses` | No | Maximum advisor calls per run. `0` or omitted: unlimited. |
| `max_transcript_tokens` | No | Estimated token budget for the conversation transcript sent to the advisor. The newest turn is always included. `0` or omitted: full transcript. |
| `max_tokens` | No | Maximum output tokens for the secondary model. `0` or omitted: provider default. |
| `temperature` | No | Sampling temperature, `0` to `2`. Omitted: provider default. |
| `reasoning_effort` | No | One of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Omitted: provider default. |
#### Sidekick
The sidekick receives only the task and optional context the agent supplies, together with the configured system prompt and output format. It returns the finished result and nothing else.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"type": "sidekick",
"configuration": {
"model": "openai/gpt-5.6-luna",
"max_tokens": 1024,
"system_prompt": "You are a meticulous copy editor.",
"output_format": "a concise bulleted list"
}
}
```
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq agents update my-agent \
--settings '{"tools": [{"type": "sidekick", "configuration": {"model": "openai/gpt-5.6-luna", "max_tokens": 1024, "output_format": "a concise bulleted list"}}]}'
```
| Field | Required | Description |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------ |
| `model` | Yes | Secondary model in `provider/model` format. |
| `max_uses` | No | Maximum sidekick calls per run. `0` or omitted: unlimited. |
| `system_prompt` | No | Replaces the default sidekick system prompt. Omitted: platform default. |
| `output_format` | No | Free-form guidance for the shape of the result, for example `a concise bulleted list` or `valid JSON`. |
| `max_tokens` | No | Maximum output tokens for the secondary model. `0` or omitted: provider default. |
| `temperature` | No | Sampling temperature, `0` to `2`. Omitted: provider default. |
| `reasoning_effort` | No | One of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Omitted: provider default. |
Mention the tools in the agent instructions so the model knows when to use them, for example: "When unsure about a legal or pricing decision, ask the advisor before answering" or "Delegate document summarization to the sidekick and use its result."
The `model` field is required. When the tool is added without a configured model, tool calls return a configuration error to the agent instead of advice or a result.
### Function Tools
**Function tools** let the model call code that runs in the application invoking the agent, not on the **Orq.ai** platform. See [Choosing a tool type](/docs/ai-studio/ai-engineering/create-tools#choosing-a-tool-type) for when to use one, [Function Tool](/docs/ai-studio/ai-engineering/create-tools#function-tool) to create one, and [Use Tools](/docs/ai-studio/ai-engineering/run-agents#use-tools) for the tool loop the application runs to execute the call and return the result.
Reference a pre-created Function tool by its `key`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"type": "function",
"key": "get_local_events"
}
```
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq agents update my-agent \
--settings '{"tools": [{"type": "function", "key": "get_local_events"}]}'
```
### Python Tools
Reference a pre-created Python tool by its `key`. Create Python tools first via the [Tools page](/docs/ai-studio/ai-engineering/create-tools#python-tool) or API.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"type": "code",
"key": "password_generator"
}
```
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq agents update my-agent \
--settings '{"tools": [{"type": "code", "key": "password_generator"}]}'
```
### HTTP Tools
Reference a pre-created HTTP tool by its `key`. Create HTTP tools first via the [Tools page](/docs/ai-studio/ai-engineering/create-tools#http-tool) or API.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"type": "http",
"key": "weather_api"
}
```
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq agents update my-agent \
--settings '{"tools": [{"type": "http", "key": "weather_api"}]}'
```
### MCP Servers
Reference a pre-created MCP server by its `tool_id`. Create MCP servers first via the [MCP Portal](/docs/ai-gateway/mcp-portal/mcp-servers) or API.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"type": "mcp",
"tool_id": "TOOL_ID"
}
```
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq agents update my-agent \
--settings '{"tools": [{"type": "mcp", "tool_id": "TOOL_ID"}]}'
```
See the full [Create Agent API reference](/reference/agents/create-agent) for all tool configuration options.
### Tool Approval
Any tool an agent can call may require a human decision before it runs. Set `requires_approval` on the tool in `settings.tools`, using the same `tool_id` as [MCP Servers](#mcp-servers):
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"tools": [
{ "type": "mcp", "tool_id": "TOOL_ID", "requires_approval": true }
]
}
```
The flag is honored only when the agent's `tool_approval_required` is `respect_tool`; `all` requires approval for every tool and `none` ignores the flag. Agents created in AI Studio are created with `none`, so set the mode explicitly when the flag must apply.
The agent then raises a **Tool approval** card in the session offering **Allow once**, **Allow always**, and **Reject**.
## Connect Knowledge Bases
Attach a Knowledge Base to ground the agent's responses in relevant data.
1. Click **Add context** in the Configuration panel.
2. Select a [Knowledge Base](/docs/ai-studio/ai-engineering/knowledge-bases).
Unlike Deployments, a Knowledge Base attached to an agent is not queried on every request. The agent decides when to use the `query_knowledge_base` tool based on context.
The Knowledge Base description must be explicit so the agent knows when to query it.
For more on building Knowledge Bases for Agents, see [Knowledge Bases](/docs/ai-studio/ai-engineering/knowledge-bases).
Add the `knowledge_bases` array to the agent configuration. Include the `retrieve_knowledge_bases` and `query_knowledge_base` tools so the agent can discover and query them.
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://my.orq.ai/v2/agents \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"key": "knowledge-agent",
"instructions": "Help the user. First use retrieve_knowledge_bases to see what knowledge sources are available, then query_knowledge_base to find relevant information.",
"path": "Default/agents",
"model": { "id": "openai/gpt-5.6-luna" },
"settings": {
"max_iterations": 5,
"max_execution_time": 600,
"tools": [
{ "type": "retrieve_knowledge_bases" },
{ "type": "query_knowledge_base" }
]
},
"knowledge_bases": [
{ "knowledge_id": "my_knowledge_base" }
]
}'
```
```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="knowledge-agent",
instructions="Help the user. First use retrieve_knowledge_bases to see what knowledge sources are available, then query_knowledge_base to find relevant information.",
path="Default/agents",
model={"id": "openai/gpt-5.6-luna"},
settings={
"max_iterations": 5,
"max_execution_time": 600,
"tools": [
{"type": "retrieve_knowledge_bases"},
{"type": "query_knowledge_base"}
]
},
knowledge_bases=[{"knowledge_id": "my_knowledge_base"}]
)
```
```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'] ?? '' });
await orq.agents.create({
key: 'knowledge-agent',
instructions: 'Help the user. First use retrieve_knowledge_bases to see what knowledge sources are available, then query_knowledge_base to find relevant information.',
path: 'Default/agents',
model: { id: 'openai/gpt-5.6-luna' },
settings: {
maxIterations: 5,
maxExecutionTime: 600,
tools: [
{ type: 'retrieve_knowledge_bases' },
{ type: 'query_knowledge_base' }
]
},
knowledgeBases: [{ knowledgeId: 'my_knowledge_base' }]
});
```
Agents must use `retrieve_knowledge_bases` before querying. Guide the agent with instructions like: "First use retrieve\_knowledge\_bases to see what knowledge sources are available, then query\_knowledge\_base to find relevant information."
See the full [Create Agent API reference](/reference/agents/create-agent) and [Knowledge Bases](/docs/ai-studio/ai-engineering/knowledge-bases) for more details.
**Attach a knowledge base to an agent:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Add the knowledge base with ID "product-docs" to the "support-bot" agent and make sure the query and retrieve tools are included
```
The assistant uses `update_agent` with the `knowledge_bases` array and adds `query_knowledge_base` and `retrieve_knowledge_bases` to `settings.tools`.
Attach a Knowledge Base to an existing agent using [`orq agents update`](/reference/cli):
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq agents update my-agent \
--instructions "Help the user. First use retrieve_knowledge_bases to see what knowledge sources are available, then query_knowledge_base to find relevant information." \
--settings '{"max_iterations": 5, "max_execution_time": 600, "tools": [{"type": "retrieve_knowledge_bases"}, {"type": "query_knowledge_base"}]}' \
--knowledge-bases '[{"knowledge_id": "my_knowledge_base"}]'
```
See [install and setup](/reference/cli) to get started with the CLI. Run `orq agents update --help` for the full flag reference.
## Connect Memory Stores
Attach a Memory Store to give the agent persistent memory across conversations.
1. Click **Add context** in the Configuration panel.
2. Select a [Memory Store](/docs/ai-studio/ai-engineering/memory-stores).
Memory Stores are created and managed through the API. To learn more, see [Using Memory Stores](/docs/ai-studio/ai-engineering/memory-stores).
To use a Memory Store correctly, a **Memory Entity ID** must be sent during agent execution. This entity ID scopes memories to a specific user or session.
For more on using Memory Stores with Agents, see the [Memory Stores](/docs/ai-studio/ai-engineering/memory-stores) documentation.
Add the `memory_stores` array to the agent configuration. Include the memory tools so the agent can discover, query, write, and delete memories.
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://my.orq.ai/v2/agents \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"key": "memory-agent",
"instructions": "You have access to user memories. Use retrieve_memory_stores to find what stores are available, then query_memory_store to search for relevant information before responding.",
"path": "Default/agents",
"model": "openai/gpt-5.6-luna",
"settings": {
"max_iterations": 5,
"max_execution_time": 300,
"tools": [
{ "type": "retrieve_memory_stores" },
{ "type": "query_memory_store" },
{ "type": "write_memory_store" },
{ "type": "delete_memory_document" }
]
},
"memory_stores": ["customer_information"]
}'
```
```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="memory-agent",
instructions="You have access to user memories. Use retrieve_memory_stores to find what stores are available, then query_memory_store to search for relevant information before responding.",
path="Default/agents",
model="openai/gpt-5.6-luna",
settings={
"max_iterations": 5,
"max_execution_time": 300,
"tools": [
{"type": "retrieve_memory_stores"},
{"type": "query_memory_store"},
{"type": "write_memory_store"},
{"type": "delete_memory_document"}
]
},
memory_stores=["customer_information"]
)
```
```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'] ?? '' });
await orq.agents.create({
key: 'memory-agent',
instructions: 'You have access to user memories. Use retrieve_memory_stores to find what stores are available, then query_memory_store to search for relevant information before responding.',
path: 'Default/agents',
model: 'openai/gpt-5.6-luna',
settings: {
maxIterations: 5,
maxExecutionTime: 300,
tools: [
{ type: 'retrieve_memory_stores' },
{ type: 'query_memory_store' },
{ type: 'write_memory_store' },
{ type: 'delete_memory_document' }
]
},
memoryStores: ['customer_information']
});
```
Memory stores do not automatically save all information from conversations. Explicitly instruct the agent what to save. Without clear save instructions, the agent may miss important details.
Pass a `memory.entity_id` at execution time to scope memories to a specific user or session. See [Run Agents](/docs/ai-studio/ai-engineering/run-agents#use-memory-stores) for execution details.
**Attach a memory store to an agent:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Add the "customer_information" memory store to the "support-bot" agent and include all four memory tools
```
The assistant uses `update_agent` with the `memory_stores` array and the four memory tools in `settings.tools`.
Attach a Memory Store to an existing agent using [`orq agents update`](/reference/cli):
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq agents update my-agent \
--instructions "You have access to user memories. Use retrieve_memory_stores to find what stores are available, then query_memory_store to search for relevant information before responding." \
--settings '{"max_iterations": 5, "max_execution_time": 300, "tools": [{"type": "retrieve_memory_stores"}, {"type": "query_memory_store"}, {"type": "write_memory_store"}, {"type": "delete_memory_document"}]}' \
--memory-stores customer_information
```
See [install and setup](/reference/cli) to get started with the CLI. Run `orq agents update --help` for the full flag reference.
## Configure Evaluators and Guardrails
Evaluators measure agent performance against defined criteria. Guardrails can block execution when an evaluation fails.
Only pre-configured Evaluators can be attached to agents. To see available standard evaluators or create custom ones, see [Evaluators](/docs/ai-studio/optimize/evaluators).
1. Click **Add Evaluator** or **Add Guardrail** in the Configuration panel.
2. Select the evaluator type.
3. Configure evaluation parameters:
* **Input or Output**: whether to evaluate the agent's input or its output.
* **Sample Rate** (Evaluators only): the fraction of executions that trigger evaluation.
Evaluators run automatically during task execution and provide performance metrics.
**Output Guardrails and Streaming**: When an agent is invoked with streaming enabled, output guardrails are deactivated because they cannot run on partial chunks.
To learn more, see [Evaluators and Guardrails in Deployments](/docs/ai-studio/ai-engineering/deployments#evaluators-and-guardrails).
Attach evaluators and guardrails to an agent using the `evaluators` and `guardrails` fields inside `settings` in the create or update payload.
For the full schema of evaluator and guardrail configuration, see the [Create Agent API reference](/reference/agents/create-agent) and [Evaluators](/docs/ai-studio/optimize/evaluators).
Use [`PATCH /v2/agents/{key}`](/reference/agents/update-agent) to add or update evaluators and guardrails on an existing agent without recreating it.
**Add an evaluator to an agent:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Add the "response-quality" LLM evaluator to the "support-bot" agent, configured for output evaluation
```
The assistant uses `update_agent` with the `evaluators` field.
***
**Add a guardrail:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Add a guardrail to "support-bot" that blocks responses when the toxicity evaluator score is above 0.8
```
The assistant uses `update_agent` with the `guardrails` field.
`evaluators` and `guardrails` are fields inside `settings`, reachable through the existing `--settings` flag on [`orq agents update`](/reference/cli):
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq agents update my-agent \
--settings '{"evaluators": [{"id": "response-quality", "execute_on": "output", "sample_rate": 100}], "guardrails": [{"id": "toxicity-guardrail", "execute_on": "output", "sample_rate": 100}]}'
```
See [install and setup](/reference/cli) to get started with the CLI. Run `orq agents update --help` for the full flag reference.
## Configure Runtime Constraints
Control resource usage and execution limits from the Configuration panel.
| Constraint | Description |
| ---------------------- | ------------------------------------------------------- |
| **Max Iterations** | Maximum number of LLM reasoning iterations per response |
| **Max Execution Time** | Maximum time the agent runs (in seconds) |
Max Iterations and Max Execution Time compound: an agent requiring many reasoning steps can hit both limits simultaneously. `max_execution_time` counts only LLM thinking time; tool call and sub-agent call duration is excluded. Start conservative and increase as needed.
Agents are run and scaled by **Orq.ai**. No infrastructure setup required.
Set constraints in the `settings` object:
| Field | Type | Description |
| -------------------- | ------- | ------------------------------------------ |
| `max_iterations` | integer | Maximum number of LLM reasoning iterations |
| `max_execution_time` | integer | Maximum execution time in seconds |
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"settings": {
"max_iterations": 5,
"max_execution_time": 300
}
}
```
Update constraints on an existing agent with `PATCH /v2/agents/{key}`.
**Update execution constraints:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Set the max iterations to 10 and max execution time to 600 seconds on the "research-bot" agent
```
The assistant uses `update_agent` with the updated `settings.max_iterations` and `settings.max_execution_time` fields.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq agents update my-agent \
--settings '{"max_iterations": 5, "max_execution_time": 300}'
```
See [install and setup](/reference/cli) to get started with the CLI. Run `orq agents update --help` for the full flag reference.
## Versions
The **Versions** tab shows the full history of all published agent configurations. Open it by selecting **Versions** from the tabs in AI Studio.
Each version entry shows the version number, author, timestamp, optional commit message, and any assigned environment badges (e.g. `latest`, `production`).
By default, invoking an agent routes to the version tagged **latest**. To target a specific version, append `@version-number` to the agent key. Route by environment with `@environment-name`.
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://my.orq.ai/v3/router/responses \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "agent/my-agent@4.0.0",
"input": "Hello"
}'
```
```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:
response = orq.responses.create(
model="agent/my-agent@4.0.0",
input="Hello",
)
print(response)
```
```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 response = await orq.responses.create({
model: 'agent/my-agent@4.0.0',
input: 'Hello',
});
console.log(response);
```
Use `@environment-name` to route to whichever version is assigned to that environment:
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://my.orq.ai/v3/router/responses \
-H "Authorization: Bearer $ORQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "model": "agent/my-agent@production", "input": "..." }'
```
See the full [Create Response API reference](/reference/responses/create-response).
**Retrieve agent version history:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Show me all published versions of the "support-bot" agent
```
The assistant uses `get_agent` to retrieve the agent including its version history.
***
**Check the current configuration of a specific version:**
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
What are the instructions on version 3.0.0 of the "support-bot" agent?
```
The assistant uses `get_agent` with the version-pinned key `support-bot@3.0.0`.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq responses create \
--model agent/my-agent@4.0.0 \
--input '"Hello"'
```
Route by environment with `@environment-name`:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
orq responses create \
--model agent/my-agent@production \
--input '"..."'
```
See [install and setup](/reference/cli) to get started with the CLI. Run `orq responses create --help` for the full flag reference.
### Comparing Changes
Click on any version to open the **Compare Changes** view. Use the **From** and **To** dropdowns to compare any two versions, including **Current** (unpublished working changes).
Two view modes are available:
* **Instructions**: diff of agent instructions only.
* **Snapshot**: full JSON diff of the complete agent configuration.
Use the button to toggle between side-by-side and unified diff layouts.
### Restoring a Version
Open **Compare Changes** (see above), then click Restore next to an older version to load it into the current working draft.
Restore does not publish automatically: the agent is loaded into the draft as unpublished changes, and Publish still needs to be clicked for it to become a real version. Earlier versions are never deleted, so restoring is always reversible.
Restore replaces the full agent configuration, including connected **Knowledge Bases**, **Memory Stores**, [**Team of Agents**](/docs/ai-studio/ai-engineering/run-agents#multi-agent-workflows), **Skills**, **Variables**, and **Tools**.
If there are unpublished changes already, a confirmation dialog asks for confirmation before overwriting them.
### Assigning Environments
Click on a version to assign it to an environment:
* Select an existing environment (e.g. `develop`, `production`).
* Create environment: add a new environment from this dropdown.
* Manage environments: open the full environment management settings.
A version can be assigned to multiple environments. Assigned badges appear on the version row.
To learn more about environments, see [Environments](/docs/ai-studio/organization/environments).
## Test in the Chat Panel
The Chat Panel, labeled **Chat Playground**, sends messages to the agent using its current working configuration, including unpublished changes, so instructions, tools, and model changes can be tested before publishing.
* Send a message to see the agent's response, including any tool calls it makes.
* Click Chat History to switch between, rename, or delete previous test conversations.
Use the Variables button above the message input to test declared variables without calling the API. The button shows a count once the instructions declare one or more variables; click a variable to set its value, using Open in panel for longer values. Sent values persist with the conversation until changed.
The Variables panel lists variables already declared with `{{variableName}}` in the instructions. Adding a new variable name is not supported from this panel; add the placeholder to the instructions first.