Skip to content
WP EngineDocumentation

Update an agent

PATCH
/v1/agents/{agent_id}
<?php


$client = new \GuzzleHttp\Client();


$response = $client->request('PATCH', 'https://api.ai.wpengine.com/v1/agents/example', [
  'body' => '{ "name": "Site Concierge", "model": "anthropic/claude-sonnet-4-6", "description": "example", "system_prompt": "example", "project_id": "example", "temperature": 1, "max_tokens": 1, "reasoning_effort": "example", "scopes": [ "example" ], "settings": {}, "mcp_servers": [ {} ], "tools": [ { "type": "custom", "name": "example", "description": "example", "input_schema": {}, "label": "example", "defer_loading": false } ], "skills": [ {} ], "metadata": { "additionalProperty": "example" } }',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);


echo $response->getBody();

Partially updates an existing agent. Fields omitted from the request body are left unchanged. When updating the model, the new model must support the tools capability; models without this capability return HTTP 400. Accepts a service-token bearer authenticating a site or an API key, either of which must be authorized for the agent’s project; reassigning project_id requires authorization for the new project too, and it cannot be cleared.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
agent_id
required
string

The unique identifier of the agent to update.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Partial update request for an agent. All fields are optional; omit a field to preserve its current value.

object
name

Human-readable agent name. Cannot be cleared (must be non-empty if provided).

string
>= 1 characters <= 255 characters
Example
Site Concierge
model

Identifier of the model that powers the agent (e.g. anthropic/claude-sonnet-4-6). Cannot be cleared.

string
>= 1 characters <= 255 characters
Example
anthropic/claude-sonnet-4-6
description

Free-form description of what the agent does. Send empty string or null to clear.

string
nullable <= 4096 characters
system_prompt

User prompt template (site prompt) prepended to every conversation powered by this agent. Send empty string or null to clear.

string
nullable <= 32768 characters
project_id

Reassigns the agent to a different project. Cannot be cleared (an agent always belongs to exactly one project); the caller must be authorized for the new project (same rules as CreateAgentRequest.project_id).

string
temperature

Sampling temperature applied to chat completions. Send null to clear.

number format: float
nullable <= 2
max_tokens

Hard upper bound on output tokens per agent turn (see CreateAgentRequest.max_tokens for semantics). Send null to clear and fall back to provider-specific defaults on subsequent turns.

integer
nullable >= 1 <= 200000
reasoning_effort

Catalog-native reasoning effort for this agent’s model. Allowed values are the model’s parameters.reasoning_effort on GET /v1/models. Send null to clear (provider default). Omit the field to preserve the stored value. Changing model clears a stored value the new model does not accept.

string
nullable
scopes

Permission scopes the agent operates under. Must be drawn from the site’s existing scopes (e.g. chat, search). Send null or empty array to clear.

Array<string>
nullable
settings

Feature toggles for the agent (e.g. disable_kb_rag: true to skip knowledge-base retrieval). Capped at 32 keys and 4 KiB serialized. Send null or empty object to clear.

object
<= 32 properties
key
additional properties
any
mcp_servers

MCP server definitions the agent may connect to. Full replacement; send empty array or null to clear.

Array<object>
nullable <= 20 items
object
key
additional properties
any
tools

Tool declarations available to the agent. Full replacement; send an empty array or null to clear all of them. See AgentTool for the per-entry contract.

Array
nullable <= 128 items
One of: discriminator: type
object
type

Discriminator for the tools[] union. Omit for a plain client tool (the default); custom is the only value this schema accepts.

string
Allowed values: custom
name
required

Unique tool name. Must be unique within the agent’s tools array (across every entry, regardless of type).

string
<= 64 characters /^[a-zA-Z0-9_-]{1,64}$/
description

Human-readable description of what the tool does.

string
input_schema

JSON Schema defining the tool’s input parameters.

object
label

Optional short human-readable name for the tool, used alongside name and description when the gateway matches a search query against deferred tools. Supply it when the tool’s name is a slug whose wording a natural-language query would not contain.

string
<= 64 characters
defer_loading

When true, the tool is declared but kept out of the model’s tool list until it is needed, so a large catalogue costs no context up front. The gateway offers the agent a search over the deferred tools and loads the matches, and a deferred tool the model names directly is loaded on demand. Once loaded, its input is enforced strictly against its schema — unlike a non-deferred tool, which keeps today’s lenient handling — so a malformed call is rejected with a model-readable error instead of failing downstream. Leave false (the default) for tools that must be callable from the first turn.

boolean
skills

Skills enabled for the agent. Full replacement; send empty array or null to clear.

Array<object>
nullable <= 64 items
object
key
additional properties
any
metadata

Arbitrary string key-value metadata. Per-key patch: set a key to a string to add/update it, or to null to delete that key; omitted keys are preserved. Maximum 16 keys, keys up to 64 characters, values up to 512 characters. The keys “scopes” and “settings” are reserved.

object
<= 16 properties
key
additional properties
string
nullable <= 512 characters

Responses

Section titled “Responses”

200

Section titled “200”

The updated agent

Media typeapplication/json
object
id
required

Unique identifier for the agent.

string
type
required
string
Allowed values: agent
project_id
required

The project the agent belongs to.

string
name
required
string
model
required
string
description
string
system_prompt

User prompt template (site prompt).

string
temperature
number format: float
max_tokens

Output-token limit per turn (see CreateAgentRequest.max_tokens). Omitted when unset on the agent.

integer
reasoning_effort

Catalog-native reasoning effort stored on the agent. Omitted when unset. Allowed values follow the agent’s current model on GET /v1/models.

string
scopes

Permission scopes the agent operates under (round-trips the request value).

Array<string>
settings

Feature toggles for the agent (round-trips the request value).

object
key
additional properties
any
mcp_servers
Array<object>
object
key
additional properties
any
tools

Tool declarations (client tools, knowledge_base grounding entries, and echo/random_number evaluation tool opt-ins) round-tripped from the request.

Array
One of: discriminator: type
object
type

Discriminator for the tools[] union. Omit for a plain client tool (the default); custom is the only value this schema accepts.

string
Allowed values: custom
name

Unique tool name. Must be unique within the agent’s tools array (across every entry, regardless of type). Always present for tools created since name validation was added; may be absent on an agent whose tools were stored before that validation existed.

string
<= 64 characters /^[a-zA-Z0-9_-]{1,64}$/
description

Human-readable description of what the tool does.

string
input_schema

JSON Schema defining the tool’s input parameters.

object
label

Optional short human-readable name for the tool, used alongside name and description when the gateway matches a search query against deferred tools. Supply it when the tool’s name is a slug whose wording a natural-language query would not contain.

string
<= 64 characters
defer_loading

When true, the tool is declared but kept out of the model’s tool list until it is needed, so a large catalogue costs no context up front. The gateway offers the agent a search over the deferred tools and loads the matches, and a deferred tool the model names directly is loaded on demand. Once loaded, its input is enforced strictly against its schema — unlike a non-deferred tool, which keeps today’s lenient handling — so a malformed call is rejected with a model-readable error instead of failing downstream. Leave false (the default) for tools that must be callable from the first turn.

boolean
skills
Array<object>
object
key
additional properties
any
metadata

User-supplied string metadata. Reserved keys (“scopes”, “settings”) are surfaced on their own top-level fields rather than appearing here.

object
key
additional properties
string
<= 512 characters
created_at
required
string format: date-time
updated_at
string format: date-time
nullable
Example
{
  "type": "agent",
  "tools": [
    {
      "type": "custom",
      "defer_loading": false
    }
  ]
}

400

Section titled “400”

Invalid request body or parameters

Media typeapplication/json
object
error
required
object
message
required
string
type
required
string
code
required
integer
request_id
required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string
Example
{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

401

Section titled “401”

Missing or invalid bearer token

Media typeapplication/json
object
error
required
object
message
required
string
type
required
string
code
required
integer
request_id
required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string
Example
{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

Headers

Section titled “Headers”
WWW-Authenticate
string
Example
Bearer realm="ai-services"

403

Section titled “403”

The token is valid, but the caller is not permitted to perform this action — either its scope/permission is insufficient or the authenticated user is not authorized for the target account (error type “permission_error”). On /v1/chat/completions specifically, a 403 with error type “content_policy_violation” instead means the request content was blocked by content moderation policy; that response never identifies which filter or category matched.

Media typeapplication/json
object
error
required
object
message
required
string
type
required
string
code
required
integer
request_id
required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string
Example
{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

404

Section titled “404”

The requested resource was not found

Media typeapplication/json
object
error
required
object
message
required
string
type
required
string
code
required
integer
request_id
required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string
Example
{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

409

Section titled “409”

The request conflicts with an existing resource

Media typeapplication/json
object
error
required
object
message
required
string
type
required
string
code
required
integer
request_id
required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string
Example
{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

429

Section titled “429”

Rate limit exceeded. The request was throttled at the edge; wait and retry later. The response body is a short HTML page generated by the load balancer, not a structured JSON error — clients should rely on the 429 status code rather than parsing the body.

Media typetext/html
string

500

Section titled “500”

The server encountered an unexpected error while handling the request. Safe to retry once; if it persists, the cause is server-side and the request payload was not the problem.

Media typeapplication/json
object
error
required
object
message
required
string
type
required
string
code
required
integer
request_id
required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string
Example
{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

503

Section titled “503”

A required dependency is temporarily unavailable. Retry after a short delay with exponential back-off.

Media typeapplication/json
object
error
required
object
message
required
string
type
required
string
code
required
integer
request_id
required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string
Example
{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}