Skip to main content
PATCH
Update agent
Related guide: Build agents guide. See the Build agents guide for a walkthrough with examples.

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

Request body for updating an existing agent via the API. Uses simplified tool input format.

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-5.6-sol or anthropic/claude-sonnet-5). 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 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.

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.

Example:

"Default Project"

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.

skills
string[] | null

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.

agent_plugins
object[] | null
variables
object

Extracted variables from agent instructions

engine
enum<string>
Available options:
text,
jinja,
mustache
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.

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.

Example:

"Default Project"

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.

skills
string[]

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.

agent_plugins
object[]
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 (orq.ai-managed) or a2a (external A2A-compliant)

Available options:
internal,
a2a
system_prompt
string | null
Minimum string length: 1
settings
object