Update agent instructions
PATCH /api/agent-definitions/{id}/instructions
Replaces the instructions of a custom agent, an agent created in your account. The instructions are the agent’s system prompt: the text that tells the agent how to handle its task. Set customInstructions to null to clear them. Agents provided by oHallo answer 403 with code: "platform_agent".
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The unique identifier of the custom agent to update instructions for.
Request Body
Section titled “Request Body ”object
The agent’s instructions, which replace its system prompt. Set to null to clear them.
Example
You handle product return requests. Always verify the order number and check that the item is within the return window (30 days from delivery) before you initiate a return.Responses
Section titled “ Responses ”The agent’s instructions were 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 new instructions wait 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; a key restricted to a brand or workspace receives code: "key_lock" when the agent uses an MCP connection outside its restriction.
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.
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"]