Crear un agente

Un agente de Raíz habla con los contactos de tu organización, en llamadas telefónicas (voice) o en WhatsApp y el chat web (text). Esta guía crea un agente de texto con raiz.agents.create y luego lo lee, lo cambia y lo pone en un canal.

Antes de empezar

Necesitas una credencial de tu organización que tenga raiz:agents:write (consulta Autenticación). Los ejemplos leen una API key de ARBOL_API_KEY.

Cada una acepta una API key, un token de máquina o la sesión de una persona. Una API key necesita el scope entre los que se eligieron al crearla; el token de una persona cuenta solo hasta donde sus roles lo otorgan.

Crear el agente

Solo modality y name son obligatorios. Agrega instructions, language y timeZone para que el agente conozca su trabajo y hable en el idioma y la zona horaria correctos:

curl https://api.getarbol.com/v1/raiz/agents \
  --request POST \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "modality": "text",
    "name": "Recordatorios de citas",
    "instructions": "Recuerdas a los pacientes de Example Clinic sus próximas citas y confirmas si van a asistir. Nunca das consejos médicos.",
    "language": "es-CO",
    "timeZone": "America/Bogota"
  }'

El cuerpo acepta solo los campos que declara su esquema; cualquier otro campo responde 400 INVALID_INPUT. Los opcionales:

Una llamada exitosa responde 200 con el agente en data. La respuesta de abajo está abreviada: el objeto completo también lleva status, ready, settings, skills, integrationSkills y toolCount.

{
  "success": true,
  "data": {
    "id": "agt_01jd8x5k2m7q9r3t6v8w0y4z1b",
    "name": "Recordatorios de citas",
    "modality": "text",
    "version": 1,
    "instructions": "Recuerdas a los pacientes de Example Clinic sus próximas citas y confirmas si van a asistir. Nunca das consejos médicos.",
    "language": "es-CO",
    "timeZone": "America/Bogota",
    "firstMessage": null,
    "description": null,
    "synced": true,
    "syncErrorCode": null,
    "channelCount": 0,
    "channels": [],
    "knowledgeDocumentIds": [],
    "integrationTools": [],
    "createdAt": "2026-10-30T15:04:05Z",
    "updatedAt": "2026-10-30T15:04:05Z"
  },
  "error": null,
  "metadata": { "requestId": "3f6c2a8e-1b4d-4e7a-9c0f-5d2e8b1a7c64" }
}

Guarda data.id: todas las demás operaciones sobre el agente lo reciben como agentId. Dos campos dicen en qué estado está el agente:

• ready: si puede sostener conversaciones. Debe estar active y tener instrucciones, y un agente de voz además debe estar publicado para llamadas.
• synced: si las llamadas ya usan la versión actual. Los agentes de voz se publican en segundo plano, así que revísalo después de cada cambio; syncErrorCode dice por qué falló la publicación. Siempre es true en los agentes de texto.

Leerlo de nuevo

raiz.agents.get recibe agentId en la ruta de la URL y responde con la configuración completa del agente:

curl "https://api.getarbol.com/v1/raiz/agents/agt_01jd8x5k2m7q9r3t6v8w0y4z1b" \
  --header "Authorization: Bearer $ARBOL_API_KEY"

Para encontrar agentes, raiz.agents.list filtra por status, modality y q (el nombre, sin distinguir tildes ni mayúsculas), del más reciente al más antiguo:

curl "https://api.getarbol.com/v1/raiz/agents?modality=text&q=recordatorios" \
  --header "Authorization: Bearer $ARBOL_API_KEY"

Los agentes están en data.data, 25 por página por defecto; pasa data.pageInfo.nextCursor como cursor para la página siguiente. Consulta Paginación.

Actualizarlo

Indica agentId en la ruta y envía los campos que quieres cambiar y, como expectedVersion, la version que leíste:

curl https://api.getarbol.com/v1/raiz/agents/agt_01jd8x5k2m7q9r3t6v8w0y4z1b \
  --request PATCH \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "expectedVersion": 1,
    "instructions": "Recuerdas a los pacientes de Example Clinic sus próximas citas, confirmas si van a asistir y pasas al equipo las solicitudes de reprogramación. Nunca das consejos médicos."
  }'

• Los campos que omites se quedan como están, y null borra un campo que lo acepte.
• settings, integrationTools, integrationSkills, skills y knowledgeDocumentIds reemplazan el valor completo. Lee primero el agente y envía el valor nuevo completo; los ajustes que omitas vuelven a su valor por defecto.
• Con expectedVersion, el cambio se aplica solo si nadie cambió el agente desde que lo leíste. Si no, responde 409 VERSION_CONFLICT: lee el agente de nuevo y vuelve a aplicar tu cambio.
• "status": "paused" hace que el agente deje de responder y de llamar.
• modality solo cambia mientras el agente no tenga canales ni una línea de voz publicada.

Ponerlo en un canal

Asigna el agente a un número de WhatsApp, un número de teléfono o un widget de chat web para que responda ahí. Encuentra el canal con raiz.channels.list y luego envía su id y el del agente a raiz.channels.update:

{
  "channelId": "chn_01jd8x6b3c4d5e6f7g8h9j0k1m",
  "agentId": "agt_01jd8x5k2m7q9r3t6v8w0y4z1b"
}

La modalidad del agente debe corresponder al canal: texto para WhatsApp y chat web, voz para números de teléfono.

Errores

Todo fallo lleva error.code, error.message, error.retryable y metadata.requestId. Consulta Respuestas y errores.