Update agent instructions

PATCH

/api/agent-definitions/{id}/instructions

Production

Updates the custom instructions for any agent, including platform-provided agents. Custom instructions are appended to the agent’s system prompt and influence its behavior during conversation processing. Set to null to clear custom instructions and revert to default behavior.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string format: uuid

The unique identifier of the agent to update instructions for.

Request Body

object

customInstructions

required

Custom instructions to append to the agent’s system prompt. Set to null to clear.

string | null

Example

When the customer mentions a competitor product, acknowledge it professionally but do not provide comparisons.

Responses

200

The agent’s instructions were updated.

An agent definition configures an agent that the orchestrator can dispatch during conversation processing. Specialist agents execute domain tasks via the MCP tools they are connected to. System agents are platform-provided and cannot be deleted, though their instructions can be customised.

object

required

Unique identifier for the agent definition.

string format: uuid

Example

ag1a2b3c-5678-9abc-def0-1234567890ab

tenantId

required

The tenant this agent belongs to.

string format: uuid

Example

a0b1c2d3-4567-89ab-cdef-0123456789ab

name

required

Internal name used to identify the agent in logs and workflow execution records.

string

Example

shipping_tracker

displayName

required

Human-readable name shown in the dashboard.

string

Example

Shipping Tracker

description

Describes what this agent does. The orchestrator reads this description when deciding whether to dispatch to this specialist.

string | null

Example

Looks up shipping status, delivery dates, and tracking information using the logistics MCP server.

agentRole

required

Whether this is a platform system agent or a tenant specialist agent. Finer-grained behaviour is carried by the agent’s role slug, which is not exposed on this endpoint.

string

Allowed values: system specialist

Example

specialist

model

The LLM model ID used by this agent. When null, the platform default is used.

string | null

Example

claude-sonnet-4-6

customInstructions

Additional instructions that guide this agent’s behavior. Appended to the system prompt. Use this to customize how the agent interprets data, formats responses, or handles edge cases.

string | null

Example

Always convert tracking dates to the customer's local timezone. If the shipment is delayed, proactively mention the estimated new delivery date.

mcpConnections

The MCP server connections this agent has access to, along with which specific tools it can invoke on each connection.

Array<object>

object

connectionId

required

Reference to a registered MCP connection.

string format: uuid

Example

mc1a2b3c-5678-9abc-def0-1234567890ab

allowedTools

required

List of tool names this agent is permitted to call on the connection. Empty array means no tools are allowed.

Array<string>

Example

[
  "get_shipment_status",
  "get_tracking_url"
]

createdAt

Timestamp when the agent was created.

string format: date-time

Example

2026-02-15T10:00:00.000Z

updatedAt

Timestamp when the agent was last updated.

string format: date-time

Example

2026-03-20T16:30:00.000Z

404

No agent exists with the given ID.

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found

422

Validation error.

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found