Create a custom agent

POST

/api/agent-definitions/custom

Production

Creates a new custom specialist agent. Custom agents are automatically assigned the ‘specialist’ role and become available for the orchestrator to dispatch during conversation processing. Connect the agent to MCP servers to give it access to your business system tools. After creation, the MCP hub cache is invalidated so the new agent is immediately available.

Authorizations

bearerAuth

Request Body

object

displayName

required

Human-readable name for the agent.

string

>= 1 characters

Example

Shipping Tracker

description

required

What this agent does. The orchestrator reads this to decide when to dispatch the agent, so be specific about capabilities.

string

>= 1 characters

Example

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

model

LLM model ID. Omit to use the platform default.

string

Example

claude-sonnet-4-6

customInstructions

Additional behavioral instructions appended to the agent’s system prompt.

string

Example

Always convert tracking dates to the customer's local timezone.

mcpConnections

MCP server connections and the specific tools this agent can access.

Array<object>

object

connectionId

required

ID of a registered MCP connection.

string format: uuid

allowedTools

required

Tool names this agent can call on the connection.

Array<string>

Example

[
  "get_shipment_status",
  "get_tracking_url"
]

Responses

201

The custom agent was created and is immediately available to the orchestrator.

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

422

Validation error. Required fields are missing or invalid.

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