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

id

required

Unique identifier for the agent definition.

string format: uuid

Example

ag1a2b3c-5678-9abc-def0-1234567890ab

tenantId

required

The account the agent belongs to; null on an agent provided by oHallo.

string | null 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

system for an agent that runs a step of oHallo’s own conversation handling, specialist for an agent the orchestrator hands tasks to. Every agent created in the account is a specialist.

string

Allowed values: system specialist

Example

specialist

roleSlug

required

The role the agent’s model is chosen for. An agent created in the account has agent.specialist_llm.

string

Example

agent.specialist_llm

model

On an agent created in the account, the model chosen for it: an id from GET /api/agent-definitions/available-models; null is Automatic, where oHallo chooses the model. oHallo chooses the model for the agents it provides.

string | null

Example

claude-sonnet-4-6

systemPrompt

The agent’s system prompt: its instructions, how it does its work. On an agent created in the account, the text set as systemPrompt on create or update, or with PATCH /api/agent-definitions/{id}/instructions.

string | null

Example

You track shipments. Look up the order's shipment with get_shipment_status and give the customer the expected delivery date and the tracking link.

customInstructions

Instructions added to an agent oHallo provides: on a system agent, the ones the account adds in the dashboard; on oHallo’s other agents, oHallo’s own. An agent created in the account takes its instructions from systemPrompt.

string | null

acceptsGuidance

On a system agent: whether guidance the account adds in the dashboard reaches the agent’s instructions. It is false for the agents that check replies before they are sent and that learn from resolved conversations, which work from oHallo’s instructions alone. Absent on every other agent.

boolean

Example

true

requiredCapabilities

required

On an agent provided by oHallo, the capabilities it works with: when the list is not empty, the assistant hands it tasks in a workspace where an active MCP connection offers one of them. Empty on an agent created in the account, which works with its own mcpConnections.

Array<string>

Example

[]

maxIterations

required

The most tool-use steps the agent takes in one run. A run that reaches them ends with terminationReason max_iterations.

integer

Example

10

promptVersion

required

The revision of an agent provided by oHallo, raised each time oHallo refines it. An agent created in the account keeps 1; its changes are recorded in its versions.

integer

Example

1

voiceExecution

required

How the agent works on a voice call. direct: the voice assistant calls the agent’s tools itself. worker: the voice assistant hands the task to the agent and keeps talking with the caller while it works, telling the caller what it finds. An agent created in the account is direct unless create or update sets it; oHallo sets it on the agents it provides.

string

Allowed values: direct worker

Example

direct

publishedVersionId

The agent’s current version, as GET /api/agent-definitions/{id}/versions lists it; null on an agent provided by oHallo.

string | null format: uuid

mcpConnections

The MCP connections the agent calls tools on, with the tools it may call on each. The two list endpoints return it on every agent created in the account.

Array<object>

One MCP connection an agent calls tools on, and the tools on it the agent may call.

object

connectionId

required

The id of an MCP connection, as GET /api/mcp-connections returns it.

string format: uuid

Example

11111111-2222-4788-9444-555555555555

allowedTools

required

The tools on the connection the agent may call, each one the connection declares. An empty list places no restriction: the agent may call every tool on the connection.

Array<string>

Example

[
  "get_shipment_status",
  "get_tracking_url"
]

dispatchableChannels

Returned when GET /api/agent-definitions is read with workspaceId: the types of the workspace’s active, enabled channels, on an agent the assistant in that workspace hands tasks to. An empty list on any other agent.

Array<string>

Example

[
  "email",
  "chat"
]

createdAt

required

Timestamp when the agent was created.

string format: date-time

Example

2026-02-15T10:00:00.000Z

updatedAt

required

Timestamp when the agent was last updated.

string format: date-time

Example

2026-03-20T16:30:00.000Z