ORorq-ai
Agents

Retrieve agent

Changed on

Retrieve the complete agent manifest by key, including model assignments, tools, knowledge bases, memory stores, and execution parameters.

get/v2/agents/{agent_key}

Request

  • Base URL
    https://my.orq.ai
  • URL
    https://my.orq.ai/v2/agents/{agent_key}
  • Auth
    HTTP bearer

Path parameters

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

_idstring required
keystring required

Unique identifier for the agent within the workspace

display_namestring
project_idstring required
created_by_idstring nullable
updated_by_idstring nullable
createdstring
updatedstring
status'live' | 'draft' | 'pending' | 'published' 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.

versionstring

Current semantic version of the agent manifest.

pathstring required

Entity storage path.

With workspace-level API keys, use the format project/folder/subfolder/.... The first element must be the display name of an existing project, followed by nested folders (auto-created as needed). Example: Default Project/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.

memory_storesstring[]

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

skillsstring[]

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.

variablesobject

Extracted variables from agent instructions

source'internal' | 'external' | 'experiment'
engine'text' | 'jinja' | 'mustache'
type'internal' | 'a2a'

Agent type: internal (orq.ai-managed) or a2a (external A2A-compliant)

rolestring required
descriptionstring required
system_promptstring nullable
instructionsstring required

Example response

{
  "path": "Default Project",
  "knowledge_bases": [
    {
      "knowledge_id": "customer-knowledge-base"
    }
  ],
  "model": {
    "parameters": {
      "fallbacks": [
        {
          "model": "openai/gpt-5.4-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": [
      {
        "parameters": {
          "fallbacks": [
            {
              "model": "openai/gpt-5.4-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
          ]
        }
      }
    ]
  }
}

Changes

  • 928a71e92252Revision changes
    • breaking

      added to the ///// response property oneOf list for the response status

    • breaking

      added to the // response property oneOf list for the response status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added between_tools discriminator mapping keys to the ///// response property for the response status

    • info

      added between_tools discriminator mapping keys to the // response property for the response status

  • 33d63277cd4eRevision changes
    • warning

      removed the optional property /////// from the response with the status

    • warning

      removed the optional property /////// from the response with the status

    • warning

      removed the optional property //// from the response with the status

    • warning

      removed the optional property //// from the response with the status

    • info

      removed between_tools discriminator mapping keys from the ///// response property for the response status

    • info

      removed between_tools discriminator mapping keys from the // response property for the response status

    • info

      removed from the ///// response property oneOf list for the response status

    • info

      removed from the // response property oneOf list for the response status