Sign in

v

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-0926150111.7 MB
Agents

Create agent

Creates a new agent with the specified configuration, including model selection, instructions, tools, and knowledge bases. Agents are intelligent assistants that can execute tasks, interact with tools, and maintain context through memory stores. The agent can be configured with a primary model and optional fallback models for automatic failover, custom instructions for behavior control, and various settings to control execution limits and tool usage.

post/v2/agents

Request body

keystring required

Unique identifier for the agent within the workspace

display_namestring

agent display name within the workspace

rolestring required

The role or function of the agent

descriptionstring required

A brief description of what the agent does

instructionsstring required

Detailed instructions that guide the agent's behavior

system_promptstring nullable

A custom system prompt template for the agent. If omitted, the default template is used.

pathstring required

The path where the agent will be stored in the project structure. The first element identifies the project, followed by nested folders (auto-created as needed).

With project-based API keys, the first element is treated as a folder name, as the project is predetermined by the API key.

memory_storesstring[]

Optional array of memory store identifiers for the agent to access. Accepts both memory store IDs and keys.

skillsstring[] nullable

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
source'internal' | 'external' | 'experiment'
engine'text' | 'jinja' | 'mustache'

Example request

{
  "path": "Default",
  "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
        ]
      }
    }
  ],
  "settings": {
    "tools": [
      {
        "type": "mcp",
        "id": "01KA84ND5J0SWQMA2Q8HY5WZZZ",
        "tool_id": "01KXYZ123456789",
        "requires_approval": false
      }
    ]
  },
  "knowledge_bases": [
    {
      "knowledge_id": "customer-knowledge-base"
    }
  ]
}

Response

Agent successfully created and ready for use. Returns the complete agent manifest including the generated ID, configuration, and all 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 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.

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