Skip to main content
GET
/
v2
/
agents
/
{agent_key}
Retrieve agent
curl --request GET \
  --url https://api.orq.ai/v2/agents/{agent_key} \
  --header 'Authorization: Bearer <token>'
{
  "_id": "<string>",
  "key": "<string>",
  "project_id": "<string>",
  "path": "Default",
  "skills": [
    "<string>"
  ],
  "role": "<string>",
  "description": "<string>",
  "instructions": "<string>",
  "model": {
    "id": "<string>",
    "integration_id": "<string>",
    "parameters": {
      "name": "<string>",
      "frequency_penalty": 123,
      "max_tokens": 123,
      "max_completion_tokens": 123,
      "presence_penalty": 123,
      "response_format": {},
      "verbosity": "<string>",
      "seed": 123,
      "stop": "<string>",
      "thinking": {},
      "temperature": 1,
      "top_p": 0.5,
      "top_k": 123,
      "parallel_tool_calls": true,
      "modalities": [],
      "guardrails": [
        {}
      ],
      "fallbacks": [
        {
          "model": "openai/gpt-4o-mini"
        }
      ],
      "cache": {
        "ttl": 3600
      },
      "load_balancer": {
        "type": "weight_based",
        "models": [
          {
            "model": "openai/gpt-4o",
            "weight": 0.7
          },
          {
            "model": "anthropic/claude-3-5-sonnet",
            "weight": 0.3
          }
        ]
      },
      "timeout": {
        "call_timeout": 30000
      }
    },
    "retry": {
      "count": 3,
      "on_codes": [
        429,
        500,
        502,
        503,
        504
      ]
    },
    "fallback_models": [
      "<string>"
    ]
  },
  "display_name": "<string>",
  "created_by_id": "<string>",
  "updated_by_id": "<string>",
  "created": "<string>",
  "updated": "<string>",
  "version": "<string>",
  "memory_stores": [],
  "team_of_agents": [],
  "metrics": {
    "total_cost": 0
  },
  "variables": {},
  "knowledge_bases": [
    {
      "knowledge_id": "customer-knowledge-base"
    }
  ],
  "engine": "text",
  "type": "internal",
  "system_prompt": "<string>",
  "settings": {
    "max_execution_time": 600,
    "max_iterations": 100,
    "max_cost": 0,
    "tool_approval_required": "respect_tool",
    "tools": []
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.orq.ai/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
agent_key
string
required

The unique key of the agent to retrieve

Response

Agent successfully retrieved. Returns the complete agent manifest with all configuration details, including models, tools, knowledge bases, and execution settings.

​
_id
string
required
​
key
string
required

Unique identifier for the agent within the workspace

Pattern: ^[A-Za-z][A-Za-z0-9]*([._-][A-Za-z0-9]+)*$
​
project_id
string
required
​
status
enum<string>
required

The status of the agent. Live is the latest version of the agent. Draft is a version that is not yet published. Pending is a version that is pending approval. Published is a version that was live and has been replaced by a new version.

Available options:
live,
draft,
pending,
published
​
path
string
required

Entity storage path.

With workspace-level API keys, use the format project/folder/subfolder/.... The first element identifies the project, followed by nested folders (auto-created as needed). Example: Default/agents.

With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: agents. For backward compatibility, a leading project name is ignored when it matches the scoped project.

Example:

"Default"

​
skills
string[]
required

List of skills that the agent can utilize. This field allows you to specify which skills the agent has access to, enabling more complex and dynamic behavior.

​
role
string
required
Minimum string length: 1
​
description
string
required
​
instructions
string
required
​
model
object
required
​
display_name
string
​
created_by_id
string | null
​
updated_by_id
string | null
​
created
string
​
updated
string
​
version
string

Current semantic version of the agent manifest.

​
memory_stores
string[]

Array of memory store identifiers. Accepts both memory store IDs and keys.

​
team_of_agents
object[]

The agents that are accessible to this orchestrator. The main agent can hand off to these agents to perform tasks.

​
metrics
object
​
variables
object

Extracted variables from agent instructions

​
knowledge_bases
object[]

Agent knowledge bases reference

​
source
enum<string>
Available options:
internal,
external,
experiment
​
engine
enum<string>
default:text
Available options:
text,
jinja,
mustache
​
type
enum<string>
default:internal

Agent type: internal (Orquesta-managed) or a2a (external A2A-compliant)

Available options:
internal,
a2a
​
system_prompt
string | null
Minimum string length: 1
​
settings
object