Datos, reportes y tareas

Además de hablar, tus agentes capturan datos, como por qué llamó un paciente o qué sede prefiere. Decides qué capturar con las definiciones, y cada valor capturado para un contacto o una conversación es un hecho que registra quién lo escribió y de dónde salió. Los reportes convierten las conversaciones y los hechos en cifras, el historial de cambios registra quién cambió qué, y las tareas son los trabajos largos que corren en segundo plano.

Definiciones

Una definición es una cosa que se captura:

Campo	Qué es
`kind`	`attribute` (una propiedad), `category` (una clasificación), `metric` (un número medido, con una `unit` UCUM) o `assessment` (una evaluación, es decir, un juicio sobre una conversación; las evaluaciones de sí o no alimentan el reporte de evaluaciones).
`subject`	Qué describen sus hechos: un `contact` o una `conversation`.
`valueType`	`text`, `number`, `boolean`, `date` (`YYYY-MM-DD`) u `option`, con hasta 100 `options`, cada una con una `key` y una `label`.
`key`	Un nombre de máquina estable: letras minúsculas, dígitos y `_`, empezando por una letra. Una columna de CSV con este encabezado se importa en ella.
`name`, `instructions`	Su nombre para las personas, y cómo decide la IA el valor.
`agentIds`	Los agentes que la usan. Vacío: todos los agentes.
`status`	`draft` mientras la preparas, `active` cuando los agentes la usan y acepta hechos, o `retired`.

raiz.definitions.create agrega una; una clave que ya usa una definición en borrador o activa responde 409 KEY_IN_USE. raiz.definitions.update cambia una, con expectedVersion. Sus options y sus agentIds son conjuntos completos, y una opción que omites se retira, nunca se elimina, porque hay hechos que la usan. El tipo de valor y el sujeto no pueden cambiar una vez que la definición tiene hechos (409 DEFINITION_TYPE_LOCKED), y una definición retirada no puede cambiar en absoluto. raiz.definitions.list lista por defecto las definiciones en borrador y activas, por kind, subject y status.

Hechos

Un hecho es el valor de una definición para un contacto o una conversación. Los contactos y las conversaciones vienen con sus hechos actuales, en facts: para cada definición, la afirmación más reciente que no fue rechazada, mientras que las anteriores quedan como historial. Cada hecho dice quién lo escribió (author: person, ai, system, import o provider), qué tan segura estaba la IA (confidence, de 0 a 1), cuándo se observó y su reviewStatus.

raiz.facts.create registra un valor bajo una definición activa. El valor sigue el tipo de la definición: un texto, un número, un booleano, una fecha YYYY-MM-DD o la clave de una opción. Da contactId o conversationId, según cuál sea el sujeto de la definición. Di de dónde salió el valor con reason y, como evidencia, con el sourceConversationId de una conversación cerrada y su sourceMessageId. En este ejemplo, la definición es la sede preferida de un contacto, de tipo option, y north es una de sus claves de opción:

curl https://api.getarbol.com/v1/raiz/facts \
  --request POST \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "definitionId": "def_01jd8xfm2n3p4q5r6s7t8v9w0x",
    "contactId": "cnt_01jd8x7c4d5e6f7g8h9j0k1m2n",
    "value": "north",
    "reason": "El paciente dijo que prefiere la sede Norte.",
    "sourceConversationId": "cnv_01jd8x8d5e6f7g8h9j0k1m2n3p"
  }'

"valueStatus": "unknown" o "not_applicable", sin value, registra que no hay ninguno. raiz.facts.update revisa un hecho: confirmed lo respalda, y rejected lo retira, así que la afirmación anterior vuelve a ser la actual.

Reportes

raiz.reports.get responde con las cifras detrás de una pregunta, y name elige el reporte:

`name`	Filas	Filtros
`conversations_daily`	Las conversaciones en las que participó la IA, por día, agente, tipo de canal y dirección, con éxitos, fallos, escalamientos y sentimiento negativo.	`agentId`, `channelType`
`booking_outcomes`	Agendamientos a partir de constancias de agendamiento verificadas, por día de finalización, agente e integración: citas nuevas, reprogramaciones, cancelaciones, y constancias fallidas, pendientes, no verificadas y duplicadas.	`agentId`
`tool_calls_daily`	Llamadas a herramientas por día, agente y herramienta, con fallos y duraciones.	`agentId`
`tool_calls`	Cada llamada a una herramienta, de la más reciente a la más antigua, sin sus entradas ni sus salidas.	`agentId`
`assessment_results_daily`	Resultados de las evaluaciones por día y definición: sí, no y desconocido.	`definitionId`
`pqrsf_daily`	Clasificación de PQRSF, resoluciones confirmadas y remisiones, a partir de los hechos `pqrsf_*`.	`agentId`, `channelType`
`campaign_progress`	Los destinatarios de cada campaña por estado.	`campaignId`

Los reportes diarios cuentan los días en la zona horaria de la organización, de from a to (YYYY-MM-DD, ambos incluidos; los últimos 30 días por defecto). Un reporte tiene como máximo 1000 filas, y hasMore significa que debes reducir el rango o los filtros. Un filtro que el reporte no recibe responde 400 REPORT_FILTER_UNSUPPORTED. En booking_outcomes, createdCount cuenta las citas nuevas que creó la IA, no las confirmaciones de citas existentes, y confirmedCount es otro nombre para lo mismo, así que nunca sumes los dos. Sus filas son constancias históricas, no el estado actual de una cita.

Historial de cambios

raiz.changes.list es el registro de auditoría: quién creó, actualizó o eliminó qué, cuándo y por qué, de lo más reciente a lo más antiguo. Cada cambio tiene el resourceType y el resourceId, la action, el author y el authorId (la persona o el cliente; ninguno para la IA ni para Raíz mismo), el reason cuando quien escribió dio uno, como merge, contact_import o conversation_analysis, y, en una actualización, cada campo cambiado con su valor from y to. Filtra por resourceId, resourceType, contactId (con los duplicados que absorbió), authorId, createdAfter y createdBefore. Los valores pueden incluir datos personales de los contactos; leer el historial requiere el permiso (scope) raiz:changes:read.

Tareas

Los trabajos largos corren en segundo plano como tareas: importaciones de contactos (contact_import), reanálisis de conversaciones (analysis_run) y rastreos de sitios web (knowledge_crawl). raiz.tasks.get lee una; después de que una acción devuelve una tarea, vuelve a consultarla cada pocos segundos. raiz.tasks.list las lista, de la más reciente a la más antigua, por kind y status:

`status`	Significado
`queued`, `running`	En espera, o trabajando. `progress` cuenta los pasos de una tarea dividida en partes.
`completed`	Terminada. `result` contiene lo que produjo, como los conteos de una importación.
`failed`	`errorCode` dice por qué, y `retryable`, si puede volver a ejecutarse.
`cancelled`	Detenida a petición. Lo que ya hizo queda hecho.

raiz.tasks.cancel cancela de inmediato una tarea en cola, y le pide a una que está corriendo que se detenga en su siguiente punto de control (cancelRequestedAt); pedirlo de nuevo no cambia nada. raiz.tasks.retry vuelve a poner en cola una tarea fallida, desde donde se detuvo. Una tarea de un tipo que nunca se reintenta, o que agotó todos sus intentos, responde 409 TASK_NOT_RETRYABLE.