Update a custom agent
PATCH /api/agent-definitions/custom/{id}
Updates a custom specialist agent definition. Only the fields sent change: the display name, description, system prompt, model, and MCP connections with their tools. Changes take effect for the orchestrator as soon as the call returns. When your account reviews agent changes before they apply, the change is saved as a version that waits for approval in the dashboard and the answer is 202; mcpConnections is not part of that version, and in that mode an agent’s connections are changed with the assignment endpoints. Requires the agents:write scope, and mcp:write as well when the body carries mcpConnections.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The unique identifier of the custom agent to update.
Request Body
Section titled “Request Body ”object
Updated display name.
Updated description (read by the orchestrator when making dispatch decisions).
The agent’s instructions: its system prompt. Send null to clear them.
The model the agent runs on: an id from GET /api/agent-definitions/available-models. Send null to return the agent to Automatic, where oHallo chooses the model.
Example
claude-sonnet-4-6How the agent works on a voice call. 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. direct: the voice assistant calls the agent’s tools itself.
Example
workerThe MCP connections the agent calls tools on, each connection once. Replaces the agent’s connections and tools entirely. Every connection must be one the caller may change, and every tool named must be one the connection declares.
One MCP connection an agent calls tools on, and the tools on it the agent may call.
object
The id of an MCP connection, as GET /api/mcp-connections returns it.
Example
11111111-2222-4788-9444-555555555555The 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.
Example
[ "get_shipment_status", "get_tracking_url"]Responses
Section titled “ Responses ”The agent definition was updated.
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
Unique identifier for the agent definition.
Example
ag1a2b3c-5678-9abc-def0-1234567890abThe account the agent belongs to; null on an agent provided by oHallo.
Example
a0b1c2d3-4567-89ab-cdef-0123456789abInternal name used to identify the agent in logs and workflow execution records.
Example
shipping_trackerHuman-readable name shown in the dashboard.
Example
Shipping TrackerDescribes what this agent does. The orchestrator reads this description when deciding whether to dispatch to this specialist.
Example
Looks up shipping status, delivery dates, and tracking information using the logistics MCP server.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.
Example
specialistThe role the agent’s model is chosen for. An agent created in the account has agent.specialist_llm.
Example
agent.specialist_llmOn 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.
Example
claude-sonnet-4-6The 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.
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.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.
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.
Example
trueOn 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.
Example
[]The most tool-use steps the agent takes in one run. A run that reaches them ends with terminationReason max_iterations.
Example
10The 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.
Example
1How 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.
Example
directThe agent’s current version, as GET /api/agent-definitions/{id}/versions lists it; null on an agent provided by oHallo.
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.
One MCP connection an agent calls tools on, and the tools on it the agent may call.
object
The id of an MCP connection, as GET /api/mcp-connections returns it.
Example
11111111-2222-4788-9444-555555555555The 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.
Example
[ "get_shipment_status", "get_tracking_url"]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.
Example
[ "email", "chat"]Timestamp when the agent was created.
Example
2026-02-15T10:00:00.000ZTimestamp when the agent was last updated.
Example
2026-03-20T16:30:00.000ZYour account reviews agent changes before they apply: the change waits for approval as the version versionId, and the agent is unchanged until it is approved.
A change saved as a version that waits for approval in the dashboard. An account that reviews changes before they apply receives this for an update, and the record stays as it was until the version is approved.
object
Always true.
Example
trueThe version that waits for approval.
Example
55443322-1100-4988-8776-655443322110The caller may not change this agent. An agent provided by oHallo answers with code: "platform_agent". People need the owner or admin role. An API key needs the agents:write scope, and mcp:write when the body carries mcpConnections; a key without one of them receives missing_scopes. A key restricted to a brand or workspace changes an agent only when every connection the agent uses is inside its restriction, and receives code: "key_lock" otherwise; it gives an agent only connections its restriction covers, as on create.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]No agent exists with the given ID.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]Validation error: a field is invalid, mcpConnections lists a connection twice, a connection is unknown or outside the API key’s brand or workspace restriction (connectionId names it), a tool is not declared by its connection (undeclaredTools and declaredTools list them), the connection is Identity Verification, which is assigned to no agent (connectionId names it), or the model is not available.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]The models available to the account could not be read, and nothing was changed. Or the other changes were saved and the model could not be applied: the body then carries agentId and modelApplied: false, so send the model again.
Standard error response returned by all endpoints on failure.
object
A human-readable error message describing what went wrong.
Example
Conversation not foundA machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.
Example
key_lockOn a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.
Example
[ "mcp:write"]On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.
Example
11223344-5566-4788-99aa-bbccddeeff00On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.
On the same 422: the tool names the connection does not declare.
Example
[ "get_orders"]On the same 422: the tools the connection declares.
Example
[ "get_order", "search_orders"]