Sign in
Agents

Create agent

Create a new agent with the specified model, instructions, tools, and knowledge bases. Supports fallback models and configurable execution settings.

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 Project",
  "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 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 50 of the 254 revisions of this API.47101225

  • b22330eb2d5a11See the full diff
    • ▲

      removed FileSystemToolInput from the settings/tools/items/ request property anyOf list

      request-property-any-of-removed

    • ○

      removed file_system discriminator mapping keys from the settings/tools/items/ request property

      request-property-discriminator-mapping-deleted

    This revision also has 61 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 3a2f6c296c092See the full diff
    • ○

      added FileSystemToolInput to the settings/tools/items/ request property anyOf list

      request-property-any-of-added

    • ○

      added file_system discriminator mapping keys to the settings/tools/items/ request property

      request-property-discriminator-mapping-added

    This revision also has 9 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 9642bb8e4f8311See the full diff
    • ▲

      removed FileSystemToolInput from the settings/tools/items/ request property anyOf list

      request-property-any-of-removed

    • ○

      removed file_system discriminator mapping keys from the settings/tools/items/ request property

      request-property-discriminator-mapping-deleted

    This revision also has 39 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • a38e9ab597712See the full diff
    • ○

      added FileSystemToolInput to the settings/tools/items/ request property anyOf list

      request-property-any-of-added

    • ○

      added file_system discriminator mapping keys to the settings/tools/items/ request property

      request-property-discriminator-mapping-added

    This revision also has 9 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • d5a398a9e78d11See the full diff
    • ▲

      removed FileSystemToolInput from the settings/tools/items/ request property anyOf list

      request-property-any-of-removed

    • ○

      removed file_system discriminator mapping keys from the settings/tools/items/ request property

      request-property-discriminator-mapping-deleted

    This revision also has 16 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 1f8d6c19ffa22See the full diff
    • ○

      added FileSystemToolInput to the settings/tools/items/ request property anyOf list

      request-property-any-of-added

    • ○

      added file_system discriminator mapping keys to the settings/tools/items/ request property

      request-property-discriminator-mapping-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 34cb457678d211See the full diff
    • ▲

      removed FileSystemToolInput from the settings/tools/items/ request property anyOf list

      request-property-any-of-removed

    • ○

      removed file_system discriminator mapping keys from the settings/tools/items/ request property

      request-property-discriminator-mapping-deleted

    This revision also has 16 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 2e6a40acc9a52See the full diff
    • ○

      added FileSystemToolInput to the settings/tools/items/ request property anyOf list

      request-property-any-of-added

    • ○

      added file_system discriminator mapping keys to the settings/tools/items/ request property

      request-property-discriminator-mapping-added

  • addad33219df4See the full diff
    • ○

      added TraceScrubbingPlugin to the fallback_models/items/anyOf[subschema #2]/parameters/plugins/items/ request property anyOf list

      request-property-any-of-added

    • ○

      added TraceScrubbingPlugin to the model/anyOf[subschema #2]/parameters/plugins/items/ request property anyOf list

      request-property-any-of-added

    • ○

      added TraceScrubbingPlugin to the model/fallback_models/items/anyOf[subschema #2]/parameters/plugins/items/ response property anyOf list for the response status 201

      response-property-any-of-added

    • ○

      added TraceScrubbingPlugin to the model/parameters/plugins/items/ response property anyOf list for the response status 201

      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

  • 1586760a252f22See the full diff
    • ▲

      removed TraceScrubbingPlugin from the fallback_models/items/anyOf[subschema #2]/parameters/plugins/items/ request property anyOf list

      request-property-any-of-removed

    • ▲

      removed TraceScrubbingPlugin from the model/anyOf[subschema #2]/parameters/plugins/items/ request property anyOf list

      request-property-any-of-removed

    • ○

      removed TraceScrubbingPlugin from the model/fallback_models/items/anyOf[subschema #2]/parameters/plugins/items/ response property anyOf list for the response status 201

      response-property-any-of-removed

    • ○

      removed TraceScrubbingPlugin from the model/parameters/plugins/items/ response property anyOf list for the response status 201

      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

Of the 254 revisions, 71 have no diff computed.