Agents

An agent is the AI that talks to your patients for you. You tell it in plain words what its job is and what it must never do, give it documents to consult and tools to look things up in your systems, and put it on a phone number, a WhatsApp number or your website’s chat. It answers there, and a voice agent can also call people for a campaign. In the Raíz Dashboard, agents are called Workers.

To create one step by step, follow Create an agent. This page explains the parts.

Voice or text

Every agent has one modality, chosen when it’s created:

The modality must fit the channel: voice agents serve phone numbers, text agents serve WhatsApp numbers and web chat. It can change only while the agent has no channels and no published voice line; otherwise the update answers 409 AGENT_MODALITY_LOCKED.

What an agent is made of

An agent also reports its channels (up to 50, each with its type and status), channelCount, toolCount and version.

Ready and synced

Two fields say whether an agent can work:

• ready is true when it can hold conversations: it is active, it has instructions and, for a voice agent, it is published for calls.
• synced says whether calls already use its current version. A voice agent is published to its phone lines in the background after each change; until synced is true, calls use the older version, and syncErrorCode gives the error of the last attempt. Fixing the cause, such as an invalid voiceId or missing instructions, publishes it again. Text agents are always synced.

curl -s "https://api.getarbol.com/v1/raiz/agents/agt_01jd8x5k2m7q9r3t6v8w0y4z1b" \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  | jq '.data | {status, ready, synced, syncErrorCode, version}'

Settings

settings holds how the agent behaves. Text settings apply only to text agents and voice settings only to voice agents; a setting that doesn’t fit the modality, or that contradicts another, answers 422 AGENT_SETTINGS_INVALID. In an update, settings is the complete new value: keys you leave out return to their default. Some of them:

The reference lists every setting, such as humanReplyTimeoutMinutes: when automatic replies resume after a person takes over a WhatsApp chat.

Tools and skills

• Integration tools. Each entry pairs a connectionId with a tool that connection offers, as account.connections.list lists them. Raíz saves each tool with its definition at that moment, its digest, and its effect: read only looks, write may change data. If the connection’s tool changes later, the agent keeps the saved definition until you save the agent again. A tool that isn’t on the connection, or that Raíz can’t run, answers 422 INTEGRATION_TOOL_UNAVAILABLE.
• Integration skills are skills a connection publishes, saved with their text at that moment. Their names must differ from the agent’s own skills.
• Skills are your own procedures, each with a name, a one-line description, its instructions and up to 16 reference resources. The agent loads one when it needs it. Skills never give an agent more tools and never run scripts.

For something temporary, such as a day without appointments, post a bulletin instead of changing the instructions.

Versions and safe updates

Every agent carries a version. Send the one you read as expectedVersion to raiz.agents.update: the change applies only if nobody changed the agent since, and otherwise answers 409 VERSION_CONFLICT, so read it again and reapply your change. Fields you leave out stay as they are; settings, integrationTools, integrationSkills, skills and knowledgeDocumentIds replace the whole value.

With settings.evalGate on, an update that changes what the model reads (instructions, skills, integration skills, model or reasoningEffort) must also send evalRunId: a completed evaluation run of exactly that content in which every case passed. Otherwise it answers 409 EVAL_GATE_UNMET.

Operations

All of them are in the Agents reference, and the Create an agent guide shows each request and its errors.