---
title: "Agentes"
description: "De qué se compone un agente de Raíz, cuándo está listo para hablar con pacientes, su configuración y cómo cambiarlo con seguridad."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentes

Un agente es la IA que habla con tus pacientes por ti. Le dices en palabras sencillas cuál es su trabajo y qué no debe hacer nunca, le das documentos para consultar y herramientas para buscar información en tus sistemas, y lo pones en un número de teléfono, un número de WhatsApp o el chat de tu sitio web. Responde ahí, y un agente de voz también puede llamar a personas para una [campaña](/developers/raiz/campaigns/). En la app de Raíz, los agentes se llaman **Trabajadores**.

Para crear uno paso a paso, sigue [Crear un agente](/developers/guides/create-an-agent/). Esta página explica sus partes.

## Voz o texto

Cada agente tiene una `modality`, que se elige al crearlo:

| `modality` | Habla en | Cómo abre la conversación |
| --- | --- | --- |
| `voice` | Llamadas telefónicas, entrantes y salientes. | `firstMessage`: lo que dice cuando se conecta una llamada. |
| `text` | WhatsApp y chat web. | En WhatsApp, `settings.greeting` decide cómo responde a un contacto que abre una conversación. Una conversación que tu organización inicia en WhatsApp se abre con una [plantilla](/developers/raiz/campaigns/#plantillas-de-whatsapp) aprobada. |

La modalidad debe corresponder al canal: los agentes de voz atienden números de teléfono, y los agentes de texto, números de WhatsApp y chat web. Solo puede cambiar mientras el agente no tenga canales ni una línea de voz publicada; si no, la actualización responde `409 AGENT_MODALITY_LOCKED`.

## De qué se compone un agente

| Campo | Qué es |
| --- | --- |
| `name` | Hasta 120 caracteres. Obligatorio, junto con `modality`. |
| `instructions` | Su trabajo en palabras sencillas: su rol, lo que puede y no puede hacer, la información en la que se apoya. Hasta 100.000 caracteres. |
| `firstMessage` | Agentes de voz: lo primero que dice cuando se conecta una llamada, entrante o saliente. |
| `language`, `timeZone` | Una etiqueta de idioma BCP 47, como `es-CO`, y una zona horaria IANA, como `America/Bogota`. |
| `status` | `active` o `paused`. Un agente en pausa no responde nada ni hace llamadas. |
| `settings` | Cómo se comporta. Consulta [Configuración](#configuración). |
| `knowledgeDocumentIds` | Hasta 100 documentos de [Conocimiento](/developers/raiz/knowledge/) que consulta. |
| `integrationTools` | Hasta 200 herramientas de tus [integraciones](/developers/integrations/) que puede llamar. Consulta [Herramientas y skills](#herramientas-y-skills). |
| `integrationSkills` | Agentes de texto: hasta 32 skills que publican tus conexiones. |
| `skills` | Agentes de texto: hasta 32 procedimientos propios, de 256 KiB en total. |
| `description` | Texto libre, hasta 2000 caracteres. |

Un agente también informa sus `channels` (hasta 50, cada uno con su tipo y su estado), `channelCount`, `toolCount` y `version`.

## Listo y sincronizado

Dos campos dicen si un agente puede trabajar:

- **`ready`** es `true` cuando puede sostener conversaciones: está `active`, tiene instrucciones y, si es un agente de voz, está publicado para llamadas.
- **`synced`** dice si las llamadas ya usan su versión actual. Un agente de voz se publica en sus líneas telefónicas en segundo plano después de cada cambio; hasta que `synced` sea `true`, las llamadas usan la versión anterior, y `syncErrorCode` da el error del último intento. Corregir la causa, como un `voiceId` inválido o la falta de instrucciones, lo vuelve a publicar. Los agentes de texto siempre están `synced`.

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

## Configuración

`settings` contiene cómo se comporta el agente. Los ajustes de texto aplican solo a los agentes de texto, y los de voz, solo a los agentes de voz; un ajuste que no corresponde a la modalidad, o que contradice a otro, responde `422 AGENT_SETTINGS_INVALID`. En una actualización, `settings` es el valor nuevo completo: las claves que omitas vuelven a su valor por defecto. Algunos de ellos:

| Ajuste | Agentes | Qué hace |
| --- | --- | --- |
| `model` | Texto | El nivel que escribe las respuestas: `arbolito/agile` (el predeterminado; el más rápido y económico), `arbolito/balanced`, `arbolito/advanced` o `arbolito/top` (el más capaz). |
| `reasoningEffort` | Texto | Cuánto deliberan `arbolito/advanced` y `arbolito/top`, de `none` a `xhigh`. Un nivel que no razona lo rechaza. |
| `greeting` | Texto, WhatsApp | Cómo responde a un contacto que abre una conversación que nadie ha respondido todavía. Su `type` es `message` (un texto fijo), `businessApp` (el saludo que envía la app WhatsApp Business) o `instructions` (instrucciones adicionales para su primera respuesta). |
| `followUpAfterMinutes`, `followUpMessage` | Texto | Cuando fue el último en hablar y preguntó algo, escribir una vez más después de esta cantidad de minutos de silencio (solo WhatsApp, dentro de su ventana de 24 horas). |
| `sessionCloseAfterMinutes` | Texto | Cerrar una conversación después de esta cantidad de minutos sin mensajes. Por defecto: 1440 en WhatsApp, 30 en chat web. |
| `humanEscalation.instructions` | Ambos | Cuándo pedirle a tu equipo que intervenga. Una solicitud explícita de hablar con una persona siempre se respeta. |
| `handoffMessage` | Texto, WhatsApp | El aviso que se agrega después de pasarle la conversación a tu equipo. Un texto vacío desactiva el aviso; el traspaso igual ocurre. |
| `automaticKnowledge` | Texto | Buscar Conocimiento relevante antes de responder un mensaje con contenido sustancial, no solo cuando el agente busca. |
| `monthlyTokenBudget` | Texto | Un límite mensual de tokens. En WhatsApp, cuando se agota, el contacto lee `budgetExhaustedMessage` y la conversación pasa a tu equipo. |
| `evalGate` | Texto, WhatsApp | Exigir una [ejecución de evaluación](/developers/raiz/evaluations/#exigir-una-ejecución-aprobada) aprobada antes de que entre en vigor un cambio en lo que lee el modelo. |
| `voice.voiceId` | Voz | Una voz de [`raiz.voices.list`](/api/raiz/voices/list/), que filtra las voces por `language` y enlaza muestras para escuchar. |
| `voice.llm` | Voz | El nivel con el que piensa en las llamadas, de los mismos cuatro. |
| `voice.recordCalls` | Voz | Guardar la grabación de cada llamada. |
| `voice.redactKeypadInput` | Voz | Reemplazar por `<REDACTED>` los números marcados en el teclado del teléfono en las transcripciones y los análisis guardados, para las llamadas futuras. El agente igual recibe los dígitos. Desactivado por defecto. |
| `voice.maxDurationSeconds` | Voz | Lo máximo que puede durar una llamada. Por defecto: 600 segundos. |

La [referencia](/api/raiz/agents/update/) lista todos los ajustes, como `humanReplyTimeoutMinutes`: cuándo se reanudan las respuestas automáticas después de que una persona toma un chat de WhatsApp.

## Herramientas y skills

- **Herramientas de integración.** Cada entrada empareja un `connectionId` con una `tool` que ofrece esa conexión, tal como las lista [`account.connections.list`](/api/account/connections/list/). Raíz guarda cada herramienta con su definición en ese momento, su `digest` y su `effect`: `read` solo consulta, `write` puede cambiar datos. Si la herramienta de la conexión cambia después, el agente conserva la definición guardada hasta que lo vuelvas a guardar. Una herramienta que no está en la conexión, o que Raíz no puede ejecutar, responde `422 INTEGRATION_TOOL_UNAVAILABLE`.
- **Las skills de integración** son skills que publica una conexión, guardadas con su texto en ese momento. Sus nombres deben ser distintos de los de las skills propias del agente.
- **Las skills** son tus propios procedimientos, cada una con un `name`, una `description` de una línea, sus `instructions` y hasta 16 `resources` de referencia. El agente carga una cuando la necesita. Las skills nunca le dan más herramientas a un agente ni ejecutan scripts.

Para algo temporal, como un día sin citas, publica una [novedad](/developers/raiz/campaigns/#novedades) en lugar de cambiar las instrucciones.

## Versiones y actualizaciones seguras

Cada agente lleva una `version`. Envía la que leíste como `expectedVersion` a [`raiz.agents.update`](/api/raiz/agents/update/): el cambio se aplica solo si nadie cambió el agente desde entonces, y si no, responde `409 VERSION_CONFLICT`, así que vuelve a leerlo y aplica de nuevo tu cambio. Los campos que omites se quedan como están; `settings`, `integrationTools`, `integrationSkills`, `skills` y `knowledgeDocumentIds` reemplazan el valor completo.

Con `settings.evalGate` activado, una actualización que cambia lo que lee el modelo (instrucciones, skills, skills de integración, `model` o `reasoningEffort`) también debe enviar `evalRunId`: una [ejecución de evaluación](/developers/raiz/evaluations/) completada de exactamente ese contenido en la que pasaron todos los casos. Si no, responde `409 EVAL_GATE_UNMET`.

## Operaciones

| Operación | Qué hace |
| --- | --- |
| [`raiz.agents.create`](/api/raiz/agents/create/) | Crea un agente. No es idempotente: después de un resultado desconocido, lista los agentes antes de intentarlo de nuevo. |
| [`raiz.agents.get`](/api/raiz/agents/get/) | Lee la configuración completa de un agente por `agentId`. |
| [`raiz.agents.list`](/api/raiz/agents/list/) | Busca agentes por `status`, `modality` o `q` (el nombre), del más reciente al más antiguo. |
| [`raiz.agents.update`](/api/raiz/agents/update/) | Cambia un agente. `"status": "paused"` hace que deje de responder y de llamar. |
| [`raiz.voices.list`](/api/raiz/voices/list/) | Busca una voz para un agente de voz. |
| [`raiz.channels.update`](/api/raiz/channels/update/) | Pone el agente en un canal. Consulta [Canales](/developers/raiz/channels/#asignar-un-agente-y-controlar-el-tráfico). |

Todas están en la [referencia de Agents](/api/raiz/tags/agents/), y la guía [Crear un agente](/developers/guides/create-an-agent/) muestra cada solicitud y sus errores.

Source: https://docs.getarbol.com/developers/raiz/agents/index.mdx