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. En la app de Raíz, los agentes se llaman Trabajadores.

Para crear uno paso a paso, sigue Crear un agente. Esta página explica sus partes.

Voz o texto

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

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

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.

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:

La referencia 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. 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 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: 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 completada de exactamente ese contenido en la que pasaron todos los casos. Si no, responde 409 EVAL_GATE_UNMET.

Operaciones

Todas están en la referencia de Agents, y la guía Crear un agente muestra cada solicitud y sus errores.