Orq.ai Documentation - AI Gateway & LLM Collaboration Platform

Configure every aspect of an agent before execution. For running agents, see Run Agents.

Create an Agent

AI Studio
API & SDK
MCP

Agent 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

Use the + button in the Project or folder.

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

The Agent Studio opens with a customizable template.

The Agent 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.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://api.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-4o"
  },
  "settings": {
    "max_iterations": 3,
    "max_execution_time": 300,
    "tools": []
  }
}'

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-4o and give it a professional, concise tone.

The assistant uses create_agent with the specified key, path, model, and instructions.

Select a Model

AI Studio
API & SDK
MCP

Select the language model that powers the agent from the Configuration panel.

Available models depend on the AI 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.

"model": {
  "id": "openai/gpt-4o",
  "parameters": {
    "temperature": 0.5
  }
}

String format: For simple cases without custom parameters.

"model": "openai/gpt-4o"

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

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 Claude Sonnet 4.6

The assistant uses update_agent with model: { "id": "anthropic/claude-sonnet-4-6" }.

Configure Instructions

AI Studio
API & SDK
MCP

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://api.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"
}'

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.

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.

Snippets

Embed reusable content blocks in agent instructions using {{snippet.key}}, where key is the key of a Prompt Snippet in the project. Updating a snippet propagates the change to every agent instruction that references it.

Variables and Templates

AI Studio
API & SDK
MCP

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.

Agent variable prompt templating in the AI Studio

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.

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 --request POST \
  --url 'https://api.orq.ai/v2/agents/support-bot/responses' \
  --header 'Authorization: Bearer <ORQ_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "message": {
      "role": "user",
      "parts": [{"kind": "text", "text": "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 --request POST \
  --url 'https://api.orq.ai/v2/agents/support-bot/responses' \
  --header 'Authorization: Bearer <ORQ_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "message": {
      "role": "user",
      "parts": [{"kind": "text", "text": "I need help."}]
    },
    "variables": {
      "company_name": "Acme",
      "customer_name": "Sarah",
      "is_premium": true
    }
  }'

For a complete reference of all template features including filters, macros, and more, see Prompt Templating.

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

curl --request POST \
  --url 'https://api.orq.ai/v2/agents/my-agent/responses' \
  --header 'Authorization: Bearer <ORQ_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "message": {
      "role": "user",
      "parts": [{"kind": "text", "text": "I need help with my account."}]
    },
    "variables": {
      "user_name": "John Smith",
      "user_role": "admin",
      "company_name": "Acme Corp"
    }
  }'

See the full Create Response API reference.

Add variables to agent instructions:

Update "support-bot" instructions to use {{user_name}} and {{company_name}} variables

The assistant uses update_agent with the revised instructions field containing {{variable}} placeholders.

Add Tools

AI Studio
API & SDK
MCP

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:

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.

Standard Tools

AI Studio
API & SDK

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
Google Search	`google_search`	Lets an agent perform a Google 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.

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
Google Search	`google_search`	Lets an agent perform a Google 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.

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

Function Tools

Define custom functions inline with an OpenAPI-style schema.

{
  "type": "function",
  "key": "get_local_events",
  "display_name": "Get Local Events",
  "description": "Retrieves local events for a given city and date",
  "function": {
    "name": "get_local_events",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string", "description": "The name of the city" },
        "date": { "type": "string", "description": "The date (YYYY-MM-DD)" }
      },
      "required": ["city", "date"]
    }
  }
}

Python Tools

Embed executable Python code directly in the tool definition. The code runs server-side in a sandboxed environment.

{
  "type": "code",
  "key": "password_generator",
  "display_name": "Password Generator",
  "description": "Generate secure passwords with numbers and symbols",
  "language": "python",
  "code": "import random\nimport string\n\nchars = string.ascii_letters\nif params.get('include_numbers'): chars += string.digits\nif params.get('include_symbols'): chars += '!@#$%^&*'\nresult = {'password': ''.join(random.choice(chars) for _ in range(params.get('length', 12)))}",
  "parameters": {
    "type": "object",
    "properties": {
      "length": { "type": "integer", "description": "Password length", "default": 12 },
      "include_numbers": { "type": "boolean", "default": true },
      "include_symbols": { "type": "boolean", "default": true }
    }
  }
}

The code receives declared parameters via params.get(...) and must assign its output to result. Using return is not supported.

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

MCP Tools

Reference a pre-created MCP tool by its tool_id. Create MCP tools first via the Tools page or API.

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

See the full Create Agent API reference for all tool configuration options.

Connect Knowledge Bases

AI Studio
API & SDK
MCP

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

Click Add context in the Configuration panel.
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://api.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-4o" },
  "settings": {
    "max_iterations": 5,
    "max_execution_time": 600,
    "tools": [
      { "type": "retrieve_knowledge_bases" },
      { "type": "query_knowledge_base" }
    ]
  },
  "knowledge_bases": [
    { "knowledge_id": "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.

Connect Memory Stores

AI Studio
API & SDK
MCP

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

Click Add context in the Configuration panel.
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://api.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-4o",
  "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"]
}'

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.

Configure Evaluators and Guardrails

AI Studio
API & SDK
MCP

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.

Click Add Evaluator or Add Guardrail in the Configuration panel.
Select the evaluator type.
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.

Attach evaluators and guardrails to an agent using the evaluators and guardrails fields 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.

Configure Runtime Constraints

AI Studio
API & SDK
MCP

Control resource usage and execution limits from the Configuration panel.

Constraint	Description
Max Iterations	Maximum number of LLM reasoning iterations per task
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

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

Versions

AI Studio
API & SDK
MCP

The Versions tab shows the full history of all published agent configurations. Open it by selecting Versions from the tabs in the Agent Studio page.

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://api.orq.ai/v2/agents/my-agent@4.0.0/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "background": false,
  "message": {
    "role": "user",
    "parts": [{ "kind": "text", "text": "Hello" }]
  }
}'

Use @environment-name to route to whichever version is assigned to that environment:

# Route to whichever version is assigned to "production"
POST /v2/agents/my-agent@production/responses

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.

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.

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.

Get Started

Build

Observe

Route

Optimize

Manage Prompts

Build Agents

Create an Agent

Select a Model

Configure Instructions

Role and Description

Snippets

Variables and Templates

Add Tools

Standard Tools

Function Tools

Python Tools

HTTP Tools

MCP Tools

Connect Knowledge Bases

Connect Memory Stores

Configure Evaluators and Guardrails

Configure Runtime Constraints

Versions

Comparing Changes

Assigning Environments

Get Started

Build

Observe

Route

Optimize

Manage Prompts

​Create an Agent

​Select a Model

​Configure Instructions

​Role and Description

​Snippets

​Variables and Templates

​Add Tools

​Standard Tools

​Function Tools

​Python Tools

​HTTP Tools

​MCP Tools

​Connect Knowledge Bases

​Connect Memory Stores

​Configure Evaluators and Guardrails

​Configure Runtime Constraints

​Versions

​Comparing Changes

​Assigning Environments

Create an Agent

Select a Model

Configure Instructions

Role and Description

Snippets

Variables and Templates

Add Tools

Standard Tools

Function Tools

Python Tools

HTTP Tools

MCP Tools

Connect Knowledge Bases

Connect Memory Stores

Configure Evaluators and Guardrails

Configure Runtime Constraints

Versions

Comparing Changes

Assigning Environments