Get an Agent
Read one Agent's complete setup: instructions, first message, language, time zone, settings, integration tools (each with its connection and effect), Knowledge document ids, procedures (trigger plus free-form instructions or structured steps) and connection procedures, and channels. ready says whether it can hold conversations; for a voice Agent, synced says whether its phone line already runs this version, and syncErrorCode why not. Read it before update_agent and send its version as expectedVersion.
- Scopes: any one of
raiz:agents:read,raiz:agents:write - Credentials: an API key, a client-credentials token or a person's access token
- Effect: read-only; safe to retry
- Limits: response up to 1 MB
- CLI:
arbol raiz agents get· MCP tool:raiz_agents_get
https://api.getarbol.com/v1/raiz/agents/{agentId}Authorization
- Authorizationstringrequired
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with any one of the scopesraiz:agents:read,raiz:agents:write. Get an API key.
Path parameters
Returns
200
Successful operation.
- dataobjectrequired
- knowledgeDocumentIdsarray ofstringrequired
The Knowledge documents the Agent consults.
pattern: ^(?:kdc_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))|(?:con)_(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$ - settingsobjectrequired
- recoveryManagerobject | nullrequired
Optional WhatsApp recovery advisor. Null or enabled=false disables it. A journaled evidence check precedes any paid review. One tool-free model call per turn before autonomous escalation or after terminal provider failure; unresolved terminal recovery hands off. Completed handoffs and conservatively recognized human requests bypass generation. Model selects the existing provider route. Prices must be conservative upper bounds including provider overhead; missing or invalid prices disable recovery. The cost bound covers only the advisor. No tools or automatic provider retries.
- modelarbolito/agileorarbolito/balancedorarbolito/advancedorarbolito/toprequired
arbolito/agile: quickest and least expensive, for direct conversations.arbolito/balanced: more deliberate answers at moderate cost.arbolito/advanced: strong reasoning for complex instructions and many tools, with an adjustablereasoningEffort.arbolito/top: the most capable, for the hardest cases, with an adjustablereasoningEffortup toxhigh. Every tier reads images and PDF documents. - advisorAgentIdoptionalstring | null
Optional active text Agent in the same organization, other than this Agent, whose instructions and procedures provide specialist guidance. The configured recovery model and cost bounds stay unchanged; no specialist tools or conversation history are accessed.
pattern: ^agt_(?:[0-7][0-9a-hjkmnp-tv-z]{25}|(?:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}|[a-f0-9]{32}))$
- attachmentReadervisionorocrornullrequired
Text Agents on WhatsApp. Who reads an image or PDF when the Agent calls
read_attachment:vision(a vision model describes and transcribes it, with a stronger one when the first reads nothing) orocr(text recognition, which also answers thefieldsthe Agent asks for, each null when absent or unclear; the vision model reads the file when recognition cannot). Withocrthe Agent sees files as markers and reads them withread_attachment; withvision, tiers that read files themselves see the original. Null:vision. - budgetExhaustedMessagestring | nullrequired
Text Agents on WhatsApp. What the contact reads when the Agent has used its
monthlyTokenBudget: the conversation then goes to the team, as an escalation does, and the Agent writes nothing until the budget is raised or the month ends. Null:handoffMessage, including an empty notice when disabled.maxLength: 1000 · minLength: 1 - closingMessagestring | nullrequired
Text Agents on WhatsApp. After a reply that completed an action (an integration tool that changes data succeeded), explicitly finished the case with end_conversation and left nothing pending (no question, no offered choices, no handoff), a contact message that only thanks or closes («gracias», «ok», «listo», an emoji) gets this text at once, without the model; the Agent still reads both in its next turn. Write it in the Agent's language and ask nothing in it. Null: the Agent answers such messages itself.
maxLength: 1000 · minLength: 1 - evalGateboolean | nullrequired
Text and voice Agents. When true, an
updateAgentthat changes what the model reads (instructions, procedures, connection procedures,modelorreasoningEffort) must sendevalRunId: a completedcreateEvalRunof this Agent with exactly that content, in which every case passed (EVAL_GATE_UNMET otherwise). Null: no requirement. - handoffMessagestring | nullrequired
Text Agents on WhatsApp. The notice appended after an escalation or a requested human handoff. Null: the current localized review notice or the case-specific notice supplied under the Agent's instructions. An empty string disables the notice; the handoff and pause still happen. The model does not write this notice.
maxLength: 1000 - humanReplyTimeoutMinutesinteger | nullrequired
Text Agents on WhatsApp. After a manual takeover, resume automatic replies when the contact's newest message waits this many minutes. An Agent handoff always stays with the team until a person explicitly resumes AI. Null: only a person resumes automatic replies.
maximum: 1440 · minimum: 1 - investigationsEnabledboolean | nullrequired
Opt this Agent into internal root-cause investigations of tool failures, human escalations, failed outcomes and negative feedback. Incidents are grouped only with participating Agents in the same organization. Null or false: disabled. Turning this off stops new events and pending dispatch when no participating Agent remains; an already active investigation may finish.
- modelarbolito/agileorarbolito/balancedorarbolito/advancedorarbolito/topornullrequired
Text Agents. The tier that writes replies.
arbolito/agile: quickest and least expensive, for direct conversations.arbolito/balanced: more deliberate answers at moderate cost.arbolito/advanced: strong reasoning for complex instructions and many tools, with an adjustablereasoningEffort.arbolito/top: the most capable, for the hardest cases, with an adjustablereasoningEffortup toxhigh. Every tier reads images and PDF documents. Null: the default, asarbolito/agile. - modelTrialrequired}
One of the following:
- RaizAgentModelTrial
- modelarbolito/agileorarbolito/balancedorarbolito/advancedorarbolito/toprequired
The tier the trial's conversations are answered with.
- percentintegerrequired
The share of new conversations in the trial, in percent.
maximum: 50 · minimum: 1 - reasoningEffortnoneorlowormediumorhighorxhighornullrequired
The trial tier's reasoning, as
reasoningEffort. Null: the tier's default.
- null
- monthlyTokenBudgetinteger | nullrequired
Text Agents. Tokens (input, cached input included, plus output) the Agent may use per calendar month (UTC), on every channel. On WhatsApp, a reply that would start past it does not run: the contact reads
budgetExhaustedMessageand the team continues; at 80 % the API logs an alert once a month. Null: no limit.maximum: 1000000000000 · minimum: 10000 - pauseOnHumanReplyboolean | nullrequired
Text Agents on WhatsApp: pause automatic replies when a live WhatsApp Business App message that says something (not a reaction, an edit or a deletion) proves a person took over. Null: disabled. The recipient stays paused until resumed or until that conversation closes; their next conversation starts with the AI.
- policyrequired}
One of the following:
- RaizAgentTurnPolicy
- maxOutputTokensoptionalinteger
Output tokens per model call, reasoning included. Default 4096.
maximum: 16384 · minimum: 256 - maxStepsoptionalinteger
Model calls one reply may make: tool rounds plus the answer. The last call never offers tools, so the contact always gets an answer. Default 16.
maximum: 32 · minimum: 2 - maxWritesPerStepoptionalinteger
Integration tool calls that change data (
effect: write) one model step may run. A further one is refused with a fixed reason, and the Agent runs it in its next step after reading the first result. 0 forbids writes. Default 1.maximum: 3 · minimum: 0 - repeatedReadLimitoptionalinteger
Identical reads (same tool, same arguments) one reply may run; the next is refused with a fixed reason. Omitted: no limit, as an Agent that polls a pending operation repeats one read on purpose.
maximum: 10 · minimum: 1 - toolsoptionalobject
Per-tool rules, by the name the model sees.
- null
- pollPendingOperationsboolean | nullrequired
Text Agents on WhatsApp: when a reply ends while an integration answered that its work is still pending (
status: pendingwith anoperationId) and the same connection offersgetOperation, Raíz checks it again on its own and the Agent answers with the result, without waiting for the contact to write. Null: disabled. - reasoningEffortnoneorlowormediumorhighorxhighornullrequired
Text Agents whose tier reasons (
arbolito/advanced,arbolito/top, or an Agent already running a model that reasons):noneanswers fastest,highdeliberates most, andxhigh, onarbolito/advancedandarbolito/top, deliberates past it. Null: the tier's default. A tier that does not reason refuses it (AGENT_SETTINGS_INVALID). - voicerequired}
One of the following:
- RaizAgentVoiceSettings
- keywordsarray ofstringrequired
Names and terms the transcriber should favor (people, places, products).
maxLength: 64 · minLength: 1 - maxDurationSecondsinteger | nullrequired
Hard limit of one call. Null: 600 seconds.
maximum: 7200 · minimum: 30 - recordCallsbooleanrequired
Keep the call recording (copied to Raíz after the call).
- silenceEndCallTimeoutSecondsinteger | nullrequired
Hang up after this much caller silence. Null: the platform default.
maximum: 600 · minimum: 10 - similarityBoostnumber | nullrequiredmaximum: 1 · minimum: 0
- speednumber | nullrequiredmaximum: 1.2 · minimum: 0.7
- stabilitynumber | nullrequiredmaximum: 1 · minimum: 0
- turnTimeoutSecondsinteger | nullrequired
Seconds to wait for the caller before prompting again. Null: the platform default.
maximum: 30 · minimum: 1 - llmarbolito/agileorarbolito/balancedorarbolito/advancedorarbolito/topornullrequired
The tier the Agent thinks with on calls.
arbolito/agile: quickest and least expensive, for direct conversations.arbolito/balanced: more deliberate answers at moderate cost.arbolito/advanced: strong reasoning for complex instructions and many tools, with an adjustablereasoningEffort.arbolito/top: the most capable, for the hardest cases, with an adjustablereasoningEffortup toxhigh. Every tier reads images and PDF documents. Null: the default, asarbolito/agile. - voiceIdstring | nullrequired
A voice from
listVoices. Null uses the default voice.pattern: ^vce_[A-Za-z0-9_-]{20,156}$ - redactKeypadInputoptionalboolean
Replace numbers entered on the phone keypad with <REDACTED> in stored transcripts and analysis. False (the default) keeps them visible. Applies to future calls; the Agent still receives the digits during the call.
default: false - reasoningEffortoptionalnoneorminimalorlowormediumorhighorxhigh+2 more
Reasoning effort on calls, when supported by the selected model. Null uses the model default.
- responseDelayMessagesoptionalboolean
Speak a short contextual message while preparing a slow response. False disables automatic delay messages. Omitted preserves the current runtime setting.
- toolCallSoundoptionaltypingornull
typing: Play a typing sound while this Agent's tools execute. Null disables the sound; omitted preserves the current setting. Applies to future calls after synchronization.
- backupModelsoptionalarray | null
Ordered backup tiers when the primary voice model fails. Null restores the runtime default. Omitted preserves the current runtime setting. An empty list is not allowed because calls need a fallback.
- null
400
INVALID_INPUT: The request does not match the published schema.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
401
UNAUTHORIZED: A valid access token is required.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
403
FORBIDDEN: The token does not authorize this operation.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
404
NOT_FOUND: The requested operation does not exist.RESOURCE_NOT_FOUND: The requested resource does not exist in this organization.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
405
HTTP_METHOD_NOT_ALLOWED: The HTTP method is not supported for this resource.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
413
REQUEST_TOO_LARGE: The request exceeds the allowed size.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
415
UNSUPPORTED_MEDIA_TYPE: The request content type is not supported.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
429
RATE_LIMITED: The request rate limit was exceeded. Try again later.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
500
INTERNAL_ERROR: The service could not complete the operation.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
502
OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
503
UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.VOICE_UNAVAILABLE: Calls are unavailable right now. Try again in a few minutes.INTEGRATIONS_UNAVAILABLE: The organization's integrations cannot be read right now. Try again shortly.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
504
UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.
- errorrequired}
One of the following:
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object
- object