Agents

Retrieve agent

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

get/v2/agents/{agent_key}

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 (Orquesta-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-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": [
      {
        "parameters": {
          "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
          ]
        }
      }
    ]
  }
}

Changes

Changed in 38 of the 261 revisions of this API.22977

Aug 24, 2026addad33219df2See the full diff
- ○
  added to the ////// response property anyOf list for the response status
  response-property-any-of-added
- ○
  added to the /// response property anyOf list for the response status
  response-property-any-of-added
This revision also has 31 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 21, 20261586760a252f2See the full diff
- ○
  removed from the ////// response property anyOf list for the response status
  response-property-any-of-removed
- ○
  removed from the /// response property anyOf list for the response status
  response-property-any-of-removed
This revision also has 173 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 21, 20264fdc24e562eb2See the full diff
- ○
  added to the ////// response property anyOf list for the response status
  response-property-any-of-added
- ○
  added to the /// response property anyOf list for the response status
  response-property-any-of-added
This revision also has 31 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 20, 2026be3fe58ce3892See the full diff
- ○
  removed from the ////// response property anyOf list for the response status
  response-property-any-of-removed
- ○
  removed from the /// response property anyOf list for the response status
  response-property-any-of-removed
This revision also has 175 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 17, 2026f54fa34db0f42See the full diff
- ○
  added to the ////// response property anyOf list for the response status
  response-property-any-of-added
- ○
  added to the /// response property anyOf list for the response status
  response-property-any-of-added
This revision also has 31 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 17, 2026ed68e8b009d72See the full diff
- ○
  removed from the ////// response property anyOf list for the response status
  response-property-any-of-removed
- ○
  removed from the /// response property anyOf list for the response status
  response-property-any-of-removed
This revision also has 173 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 17, 2026d46bd23ae34c2See the full diff
- ○
  added to the ////// response property anyOf list for the response status
  response-property-any-of-added
- ○
  added to the /// response property anyOf list for the response status
  response-property-any-of-added
This revision also has 29 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 17, 2026f459ad9381eb2See the full diff
- ○
  removed from the ////// response property anyOf list for the response status
  response-property-any-of-removed
- ○
  removed from the /// response property anyOf list for the response status
  response-property-any-of-removed
This revision also has 42 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 14, 2026deb8d376faee2See the full diff
- ○
  added to the ////// response property anyOf list for the response status
  response-property-any-of-added
- ○
  added to the /// response property anyOf list for the response status
  response-property-any-of-added
This revision also has 29 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 2, 20266f132f005b2a2See the full diff
- ○
  removed from the ////// response property anyOf list for the response status
  response-property-any-of-removed
- ○
  removed from the /// response property anyOf list for the response status
  response-property-any-of-removed
This revision also has 97 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 261 revisions, 73 have no diff computed.

Full history (38 revisions)