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 to the planner for dispatching 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 planner 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 planner.

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

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

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