Build AI agents in Orq.ai: set instructions with Jinja or Mustache, pick models, and attach tools, knowledge bases, memory, and guardrails.
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.
Open Agents in the Managed Agents section, then click Agent.
3
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.AI Studio opens with a customizable template.
AI Studio has three panels:
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)
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:
To save a thinking mode on the Agent, set parameters.thinking. It applies on every run as if it were sent in the request. On Sonnet 5.5, between_tools streams progress updates between tool calls without up-front thinking:
See install and setup to get started with the CLI. Run orq agents update --help for the full flag reference.
Structured Output
Structured output makes the agent reply with JSON that matches a schema, so the response can be parsed instead of read.
AI Studio
API & SDK
CLI
Set Response Format in the Model panel, next to the model picker:
JSON Mode returns a JSON object. The instructions still have to ask for JSON.
JSON Schema opens a Schema dropdown that selects a JSON Schema Tool, and the agent answers with that tool’s schema.
The menu lists the formats the selected model supports. Response Format appears only for models that support JSON Mode or JSON Schema.
Set model.parameters.response_format in JSON and Python, or model.parameters.responseFormat in TypeScript. The three formats, their schema rules and strict enforcement are documented in Structured Outputs.
A fallback model is tried when the primary model fails, in the order the list holds. Once the last fallback fails too, the run returns that error.
AI Studio
API & SDK
Add models in the Fallback Models section of Settings. Fallback model appends the first available model, which is then changed in the entry together with its parameters, and the list holds up to five entries.Only models that support tool calling are offered.
Set fallback_models alongside model on the agent. Each entry is a model ID string, or an object with id, parameters, and retry:
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 Orqimport oswith 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');
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.
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.
Attaching a Skill to an agent for on-demand reference.
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.
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.
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 %}
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}}
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.
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.
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"
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.
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" }}
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:
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 Orqimport oswith 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.”
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.
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 Orqimport oswith 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.
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, defaulting to 50. A guardrail in the Guardrails section ignores it and runs on every request.
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.
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:
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:
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
See install and setup to get started with the CLI. Run orq agents update --help for the full flag reference.
Expose an Agent via A2A
Each internal Agent has its own endpoint on the A2A Protocol, so an application or agent framework built outside Orq.ai can call it by URL. Open the Agent in AI Studio, expand Expose via A2A in the Settings panel, and copy the connection details.
The Expose via A2A panel with the Agent URL, the Agent card URL, and the scope the calling API key needs.
Value
Use
Agent URL
Endpoint an A2A client sends messages to
Agent card URL
Discovery document the client reads first, including the Agent’s skills
The calling API key needs a2a.execute, which comes with All permissions or Restricted with Write access to External agents, and access to the Agent’s Project. Create the key under API Keys.
Call the Agent from an A2A client
An A2A client reads the card, then sends messages to the Agent URL. This client prints the Agent’s answer, or the task state when the Agent needs more input, and reads the key from ORQ_API_KEY:
Install the client library with pip install a2a-sdk. Transport bindings, message shapes, and ingress limits are on Agents Gateway.
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.
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).
A PATCH publishes a new version when it changes the agent’s run definition, such as its instructions, role, model, tools or execution settings. The default step is a patch bump, so an agent at 1.0.0 moves to 1.0.1.Changes outside the run definition, such as the display_name, a path that moves the agent to another project, or variables, keep the current version. A PATCH that repeats the stored configuration publishes nothing.Set versionIncrement to major, minor or patch to pick the step: minor turns 1.2.3 into 1.3.0, and major into 2.0.0. versionDescription (up to 300 characters) becomes the commit message on the version row in the Versions panel.The newest version is what @latest and an unpinned key resolve to, so the next unpinned invoke runs the new configuration. A version assigned to an environment keeps its tag until the tag moves.
from orq_ai_sdk import Orqimport oswith Orq(api_key=os.getenv("ORQ_API_KEY", "")) as orq: agent = orq.agents.update( agent_key="my-agent", instructions="Escalate refunds above $500 to a human.", version_increment="minor", version_description="Tighter refund escalation", ) print(agent.version)
import { Orq } from '@orq-ai/node';const orq = new Orq({ apiKey: process.env['ORQ_API_KEY'] ?? '' });const agent = await orq.agents.update( { instructions: 'Escalate refunds above $500 to a human.', versionIncrement: 'minor', versionDescription: 'Tighter refund escalation', }, 'my-agent',);console.log(agent.version);
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.
Environments are assigned from the Versions panel (Assigning Environments). @environment-name follows the tag, so the next request routes to the newly tagged version without changing the model string.
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.Publish a new version:
Update the "support-bot" instructions to escalate refunds above $500 to a human, with a minor version bump and the description "Tighter refund escalation"
The assistant uses update_agent with versionIncrement and versionDescription inside updates on every call: the fields name the version a configuration change publishes.
Publish a new version by changing the configuration and naming the bump:
orq agents update my-agent \ --instructions 'Escalate refunds above $500 to a human.' \ --version-increment minor \ --version-description "Tighter refund escalation"
See install and setup to get started with the CLI. Run orq responses create --help and orq agents update --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).
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.
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.
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.
Turn on Expose in Playground in the Playground section of Settings to offer the agent as a target in the workspace Playground, so it can be tested without opening the agent. The switch is part of the draft, so the agent reaches the Playground target list once published. Registered external agents and experiment agents stay out of that list.
Was this page helpful?
Assistant
Responses are generated using AI and may contain mistakes.