Build Agents

Configure every aspect of an agent before execution. For running agents, see 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
API & SDK
MCP
CLI

AI Studio is the visual interface for building, configuring, and testing AI agents without writing code.

Navigate to the AI Studio

Open the AI Studio.

Create a new Agent

Open Agents in the Managed Agents section, then click Agent.

New entity menu listing Folder, Agent (Beta), Dataset, Deployment, Evaluator, Experiment, Knowledge, Playground, Prompt, Snippet, and Tool.

Configure the Agent

Select the model, set the Agent key, and describe the Agent. Choose Create with AI to pre-configure role and instructions, or Start from scratch for full manual control.

Create Agent dialog with the Create with AI and Start from scratch tabs, and fields for Select model, Agent key, and Description.

AI Studio opens with a customizable template.

AI Studio has three panels:

AI Studio showing settings on the left, instructions in the center, and the Playground on the right. — AI Studio three-panel layout.

Settings (left): Set up the model, tools, context, evaluators, and constraints.
Instructions (center): Define what the agent does and how it behaves.
Playground (right): Chat with the agent and test its behaviour.

Save the configuration at any time using the Publish button.

The Agents API creates and manages internal Orq.ai Agents. Execute them through the Responses API with model: "agent/<key>". This management API does not use the A2A wire contract. To register an external A2A Agent or expose an internal Agent to A2A clients, see Agents Gateway.Prerequisites:

A Project in the workspace (used as the path for resources)
An API Key
Optionally, one of the Orq SDKs

Create an agent with a minimal configuration:

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": []
  }
}'

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}")

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.

Use the Orq MCP server to manage agents directly from an AI code assistant.Find an existing agent:

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:

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:

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:

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 to get started with the CLI. Run orq agents create --help for the full flag reference.

Select a Model

AI Studio
API & SDK
MCP
CLI

Select the language model that powers the agent in the Model section.

Available models depend on the AI Gateway configuration. Switch models at any time and the agent uses the new model on its next execution.

Access the model parameters sub-menu to configure temperature and other parameters.

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. Turns and Max. Execution Time constraints.

The model field supports two formats.Object format (recommended): Specify model parameters alongside the model ID.

"model": {
  "id": "openai/gpt-5.6-luna",
  "parameters": {
    "temperature": 1
  }
}

String format: For simple cases without custom parameters.

"model": "openai/gpt-5.6-luna"

Use the provider/model-id format. For a complete list of supported models, see the AI Gateway.

See the full API reference for all supported model parameters.

List available models:

List all available chat models in my workspace

The assistant uses list_models with type: "chat".

Update the model on an existing agent:

Switch the "support-bot" agent to use GPT-5.6 Luna

The assistant uses update_agent with model: { "id": "openai/gpt-5.6-luna" }.

orq agents update my-agent \
  --model '{"id": "openai/gpt-5.6-luna", "parameters": {"temperature": 1}}'

See install and setup to get started with the CLI. Run orq agents update --help for the full flag reference.

Configure Instructions

AI Studio
API & SDK
MCP
CLI

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.

Example: Customer Support 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:

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"
}'

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"
    )

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.

Update agent instructions:

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:

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.

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 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.

Skills

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

AI Studio
API & SDK
MCP
CLI

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.

AI Studio editor showing instructions with a {{language}} variable highlighted in green. — Variables defined in the agent instructions are highlighted in the AI Studio.

Orq.ai supports three template engines. Select an engine from the Template Engine section:

Text (default): variables use {{double_braces}} syntax.
Jinja: full templating with conditionals, loops, filters, and more.
Mustache: logic-less templating with sections.

Template Engine dropdown with Text currently selected, and options for Jinja and Mustache. — Selecting an engine in the Template Engine section.

Jinja example

Instructions template:

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:

cURL

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"
    }
  }'

Mustache example

Instructions template:

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:

cURL

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.

To test declared variables without calling the API, use the Variables button in the Playground panel. See Test in the Playground below.

Use {{variableName}} placeholders in agent instructions and pass the corresponding values in the variables field at invocation time.

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-agent",
    "input": "I need help with my account.",
    "variables": {
      "user_name": "John Smith",
      "user_role": "admin",
      "company_name": "Acme Corp"
    }
  }'

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"])

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.

Add variables to agent instructions:

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:

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:

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 to get started with the CLI. Run orq agents update --help and orq responses create --help for the full flag reference.

Each invocation records the values it received as the orq.variables span attribute. Open Traces, select the step, and read them under Metadata.

Add Tools

AI Studio
API & SDK
MCP
CLI

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.

Tool library showing available tools including Web search, Current date, Write memory store, Delete memory document, http_tool, python_tool, and others. — Browse the tool library to find all tools available in the Project.

Declare tools in the settings.tools array when creating or updating an agent.

Add a standard tool to an agent:

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:

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:

orq agents update my-agent \
  --settings '{"tools": [{"type": "google_search"}, {"type": "current_date"}]}'

See install and setup to get started with the CLI. Run orq agents update --help for the full flag reference.

Standard Tools

AI Studio
API & SDK
CLI

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. Added automatically when using a Memory Store.
Retrieve Memory Stores	`retrieve_memory_stores`	Lets an agent fetch Memory Stores. Added automatically when using a Memory Store.
Write Memory Store	`write_memory_store`	Lets an agent save to a Memory Store. 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. Added automatically when using a Knowledge Base.
Retrieve Knowledge Bases	`retrieve_knowledge_bases`	Lets an agent fetch a Knowledge Base. 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.
Sidekick	`sidekick`	Lets an agent delegate a self-contained subtask to a second model. See Advisor and Sidekick Tools.

Create custom tools to use within Agents:

Best Practices: Using Tools in Agent Instructions

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.
Retrieve Memory Stores	`retrieve_memory_stores`	Lets an agent fetch Memory Stores.
Write Memory Store	`write_memory_store`	Lets an agent save to a Memory Store.
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.
Retrieve Knowledge Bases	`retrieve_knowledge_bases`	Lets an agent fetch 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.
Sidekick	`sidekick`	Lets an agent delegate a self-contained subtask to a second model. See Advisor and Sidekick Tools.

{
  "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" }
    ]
  }
}

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 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. 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.

{
  "type": "advisor",
  "configuration": {
    "model": "openai/gpt-5.6-sol",
    "max_uses": 3,
    "max_transcript_tokens": 8000
  }
}

orq agents update my-agent \
  --settings '{"tools": [{"type": "advisor", "configuration": {"model": "openai/gpt-5.6-sol", "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.

{
  "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"
  }
}

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 for when to use one, Function Tool to create one, and 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:

{
  "type": "function",
  "key": "get_local_events"
}

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 or API.

{
  "type": "code",
  "key": "password_generator"
}

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 or API.

{
  "type": "http",
  "key": "weather_api"
}

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 or API.

{
  "type": "mcp",
  "tool_id": "TOOL_ID"
}

orq agents update my-agent \
  --settings '{"tools": [{"type": "mcp", "tool_id": "TOOL_ID"}]}'

See the full Create Agent API reference 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:

{
  "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

AI Studio
API & SDK
MCP
CLI

Attach a Knowledge Base to ground the agent’s responses in relevant data.

Click Add context in the Context section.
Select a Knowledge Base.

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.

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.

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" }
  ]
}'

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"}]
    )

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 and Knowledge Bases for more details.

Attach a knowledge base to an agent:

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:

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 to get started with the CLI. Run orq agents update --help for the full flag reference.

Connect Memory Stores

AI Studio
API & SDK
MCP
CLI

Attach a Memory Store to give the agent persistent memory across conversations.

Click Add context in the Context section.
Select a Memory Store.

Memory Stores are created and managed through the API. To learn more, see Using 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 documentation.

Add the memory_stores array to the agent configuration. Include the memory tools so the agent can discover, query, write, and delete memories.

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"]
}'

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"]
    )

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 for execution details.

Attach a memory store to an agent:

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:

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 to get started with the CLI. Run orq agents update --help for the full flag reference.

Configure Evaluators and Guardrails

AI Studio
API & SDK
MCP
CLI

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.

Select an evaluator in the Evaluators section, or a guardrail in the Guardrails section.
Configure evaluation parameters:
- Input or Output: whether to evaluate the agent’s input or its output.
- Sample Rate (Evaluators only): the percentage of executions that trigger evaluation, 1 to 100.

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.

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 and Evaluators.

Use PATCH /v2/agents/{key} to add or update evaluators and guardrails on an existing agent without recreating it.

Add an evaluator to an agent:

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:

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:

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 to get started with the CLI. Run orq agents update --help for the full flag reference.

Evaluators and guardrails attached to an agent run with the Evaluator’s timeout, or 60 seconds if it has none. The settings.evaluators[] and settings.guardrails[] entries have no timeout field, so the execution limit cannot be changed on the agent. To bound a guardrail explicitly, pass it inline on the invoke request instead:

{
  "model": "agent/support-bot",
  "input": "Summarize the latest escalation.",
  "guardrails": [
    { "id": "toxicity-guardrail", "execute_on": "output", "is_guardrail": true, "timeout": 15000 }
  ]
}

Request-level guardrails are honored on agent invokes, and each entry carries its own timeout, defaulting to the Evaluator’s timeout, or 60 seconds if it has none, and capped at 10 minutes. See Guardrail timeout. An output guardrail does not run when the agent is invoked with stream: true, because it cannot gate a response that has already been streamed.

An evaluator attached both on the agent and inline runs twice, because Orq.ai does not dedupe agent settings against the request. Remove it from the agent when using the inline workaround.

Configure Runtime Constraints

AI Studio
API & SDK
MCP
CLI

Control resource usage and execution limits from the Runtime Constraints section.

Constraint	Description
Max. Turns	Maximum number of LLM reasoning iterations per response. Defaults to 100.
Max. Execution Time	Maximum accumulated model time across iterations, in seconds. Defaults to 600.

Max. Turns 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 accumulated model time across iterations, in seconds

{
  "settings": {
    "max_iterations": 5,
    "max_execution_time": 300
  }
}

Update constraints on an existing agent with PATCH /v2/agents/{key}.

Update execution constraints:

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.

orq agents update my-agent \
  --settings '{"max_iterations": 5, "max_execution_time": 300}'

See install and setup to get started with the CLI. Run orq agents update --help for the full flag reference.

Versions

AI Studio
API & SDK
MCP
CLI

The Versions toggle shows the full history of all published agent configurations. Select Versions next to Settings in the left panel to open it.

Versions panel below the Settings and Versions toggles, listing v4.1.0 (latest, beta_env), v4.0.0 (production), v3.0.0, and v2.0.0, each with author and timestamp. — The Versions panel shows the full history of published agent configurations with environment assignments.

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.

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"
}'

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)

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:

cURL

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.

Retrieve agent version history:

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:

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.

orq responses create \
  --model agent/my-agent@4.0.0 \
  --input '"Hello"'

Route by environment with @environment-name:

orq responses create \
  --model agent/my-agent@production \
  --input '"..."'

See install and setup 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).

Side-by-side diff view comparing two agent versions, highlighting changed lines in the instructions field. — Compare Changes shows a side-by-side diff between any two versions.

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, 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.

Version row showing environment badge labels assigned to a specific version. — Environment tags are visible next to version number.

To learn more about environments, see Environments.

Test in the Playground

The Playground panel 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.

Playground message input with a Variables button showing a count of 2 declared variables. — Testing an agent's declared variables from the Playground.

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.

Overview

Managed Agents

Context Management

Test & Evaluate

Chat

Create an Agent

Select a Model

Configure Instructions

Role and Description

Skills

Variables and Templates

Add Tools

Standard Tools

Advisor and Sidekick Tools

Advisor

Sidekick

Function Tools

Python Tools

HTTP Tools

MCP Servers

Tool Approval

Connect Knowledge Bases

Connect Memory Stores

Configure Evaluators and Guardrails

Configure Runtime Constraints

Versions

Comparing Changes

Restoring a Version

Assigning Environments

Test in the Playground

​Create an Agent

​Select a Model

​Configure Instructions

​Role and Description

​Skills

​Variables and Templates

​Add Tools

​Standard Tools

​Advisor and Sidekick Tools

​Advisor

​Sidekick

​Function Tools

​Python Tools

​HTTP Tools

​MCP Servers

​Tool Approval

​Connect Knowledge Bases

​Connect Memory Stores

​Configure Evaluators and Guardrails

​Configure Runtime Constraints

​Versions

​Comparing Changes

​Restoring a Version

​Assigning Environments

​Test in the Playground

Create an Agent

Select a Model

Configure Instructions

Role and Description

Skills

Variables and Templates

Add Tools

Standard Tools

Advisor and Sidekick Tools

Advisor

Sidekick

Function Tools

Python Tools

HTTP Tools

MCP Servers

Tool Approval

Connect Knowledge Bases

Connect Memory Stores

Configure Evaluators and Guardrails

Configure Runtime Constraints

Versions

Comparing Changes

Restoring a Version

Assigning Environments

Test in the Playground