Update a custom agent

PATCH

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

• Production

Updates a custom specialist agent definition. You can modify the display name, description, model, instructions, and MCP tool assignments. Changes take effect immediately — the MCP hub cache is invalidated on update.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

The unique identifier of the custom agent to update.

Request Body

object

displayName

Updated display name.

string

>= 1 characters

description

Updated description (read by the planner for dispatch decisions).

string

>= 1 characters

model

Updated LLM model ID.

string

customInstructions

Updated instructions. Set to null to clear.

string | null

mcpConnections

Updated MCP connections and tool assignments. Replaces existing assignments entirely.

Array<object>

object

connectionId

required

string format: uuid

allowedTools

required

Array<string>

Responses

200

The agent definition was updated.

An agent definition configures an AI agent within the conversation pipeline. oHallo uses a four-layer agent model: the planner determines intent and selects specialist agents, specialists execute domain-specific tasks via MCP tools, the message agent drafts the customer-facing reply, and the validator fact-checks the draft. You can create custom specialist agents and connect them to your MCP servers.

object

id

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 planner agent reads this description to decide 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

The role this agent plays in the conversation pipeline. ‘planner’ analyzes intent and selects specialists. ‘specialist’ executes domain tasks via MCP tools. ‘message’ drafts the customer-facing reply. ‘validator’ fact-checks drafts against the knowledge base and conversation context.

string

Allowed values: planner specialist message validator

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 custom agent exists with the given ID. Note: platform agents cannot be updated via this endpoint — use the instructions endpoint instead.

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