List custom agent definitions

GET

/api/agent-definitions/custom

Production

Returns only custom (tenant-created) specialist agent definitions, excluding platform-provided agents. Use this to manage the agents you have created to handle domain-specific tasks.

Authorizations

bearerAuth

Responses

200

Custom agent definitions for the tenant. Returns an empty array if none have been created.

List of agent definitions, including both platform-provided agents and tenant-specific custom agents.

Array<object>

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