Skip to main content
PATCH
/
v2
/
agents
/
{agent_key}
Update agent
curl --request PATCH \
  --url https://api.orq.ai/v2/agents/{agent_key} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "key": "<string>",
  "display_name": "<string>",
  "project_id": "<string>",
  "role": "<string>",
  "description": "<string>",
  "instructions": "<string>",
  "system_prompt": "<string>",
  "model": "<string>",
  "fallback_models": [
    "<string>"
  ],
  "settings": {
    "max_iterations": 100,
    "max_execution_time": 600,
    "max_cost": 0,
    "tool_approval_required": "respect_tool",
    "tools": [],
    "evaluators": [
      {
        "id": "<string>",
        "execute_on": "input",
        "sample_rate": 50
      }
    ],
    "guardrails": [
      {
        "id": "<string>",
        "execute_on": "input",
        "sample_rate": 50
      }
    ]
  },
  "path": "Default",
  "memory_stores": [
    "<string>"
  ],
  "knowledge_bases": [
    {
      "knowledge_id": "customer-knowledge-base"
    }
  ],
  "team_of_agents": [
    {
      "key": "<string>",
      "role": "<string>"
    }
  ],
  "variables": {},
  "engine": "text",
  "a2a": {
    "agent_url": "<string>",
    "card_url": "<string>",
    "headers": {}
  },
  "versionIncrement": "major",
  "versionDescription": "<string>"
}
'
{
  "_id": "<string>",
  "key": "<string>",
  "project_id": "<string>",
  "status": "live",
  "path": "Default",
  "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": {
        "type": "text"
      },
      "reasoning_effort": "none",
      "verbosity": "<string>",
      "seed": 123,
      "stop": "<string>",
      "thinking": {
        "type": "disabled"
      },
      "temperature": 1,
      "top_p": 0.5,
      "top_k": 123,
      "tool_choice": "none",
      "parallel_tool_calls": true,
      "modalities": [
        "text"
      ],
      "guardrails": [
        {
          "id": "orq_pii_detection",
          "execute_on": "input"
        }
      ],
      "fallbacks": [
        {
          "model": "openai/gpt-4o-mini"
        }
      ],
      "cache": {
        "type": "exact_match",
        "ttl": 3600
      },
      "load_balancer": {
        "type": "weight_based",
        "models": {
          "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"
    }
  ],
  "source": "internal",
  "engine": "text",
  "type": "internal",
  "system_prompt": "<string>",
  "settings": {
    "max_execution_time": 600,
    "max_iterations": 100,
    "max_cost": 0,
    "tool_approval_required": "respect_tool",
    "tools": []
  },
  "a2a": {
    "agent_url": "<string>",
    "card_url": "<string>",
    "headers": {},
    "cached_card": "<unknown>"
  }
}

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 update

Body

application/json
​
key
string
Pattern: ^[A-Za-z][A-Za-z0-9]*([._-][A-Za-z0-9]+)*$
​
display_name
string
​
project_id
string
​
role
string
Minimum string length: 1
​
description
string

A brief description of what the agent does

Minimum string length: 1
​
instructions
string
​
system_prompt
string | null

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

Minimum string length: 1
​
model

A model ID string (e.g., openai/gpt-4o or anthropic/claude-haiku-4-5-20251001). The agent can be run with a wide range of models with different capabilities, performance characteristics, and price points. Only models that support tool calling (function_calling) can be used to run agents. See (supported models)[/docs/proxy/supported-models] documentation for the complete list of available models.

​
fallback_models
(string | Fallback Model Configuration · object)[]

Optional array of fallback models used when the primary model fails. Fallbacks are attempted in order. All models must support tool calling.

A fallback model ID string (e.g., openai/gpt-4o-mini). Will be used if the primary model request fails. Must support tool calling.

​
settings
object
​
path
string

Entity storage path in the format: project/folder/subfolder/...

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.

Example:

"Default"

​
memory_stores
string[]

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

​
knowledge_bases
object[]
​
team_of_agents
Team of agents · object[]

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

​
variables
object

Extracted variables from agent instructions

​
engine
enum<string>
Available options:
text,
jinja,
mustache
​
a2a
Update A2A Configuration · object

Update A2A agent configuration (only applicable to A2A agents)

​
versionIncrement
enum<string>

Optional semantic version bump to create after a successful publish.

Available options:
major,
minor,
patch
​
versionDescription
string

Optional description stored with the created version.

Maximum string length: 300

Response

Agent configuration successfully updated. Returns the complete updated agent manifest reflecting all changes made.

​
_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 in the format: project/folder/subfolder/...

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.

Example:

"Default"

​
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
​
a2a
A2A Agent Configuration · object

A2A configuration with agent endpoint and authentication. Only present for A2A agents.