Paso Criterio IA - Insurance Boosters API

El paso decision.evaluate responde preguntas cerradas sobre los datos de tu automatización. Tú defines las respuestas posibles y el paso elige entre ellas, acompañando cada una con su probabilidad. Úsalo cuando el flujo necesita decidir algo antes de seguir. Por ejemplo:

Situación	Pregunta que resuelve
Llega un mensaje a soporte	¿A qué equipo lo mando?
Se sube un documento	¿De qué tipo es?
Un cliente responde una encuesta	¿Qué tan molesto está?
Se crea un prospecto	¿Está listo para contactar?
Se recibe un ticket	¿Requiere intervención humana?

Este paso funciona con los modelos System One de TypeSafe AI, especializados en decisiones tipadas. Las preguntas y las respuestas usan su mismo formato, así que su documentación aplica tal cual. Las respuestas típicas tardan alrededor de 300 ms.

El ciclo completo

Antes de la referencia, así se ve de principio a fin con una sola pregunta. 1. Defines el paso. state son los datos a evaluar y questions lo que quieres saber de ellos. El nombre de cada pregunta lo eliges tú:

{
  "name": "Clasificar el mensaje",
  "actionKey": "decision.evaluate",
  "input": {
    "state": "No puedo entrar a mi cuenta desde ayer.",
    "questions": {
      "tema": {
        "type": "choice",
        "instructions": "¿Sobre qué trata el mensaje?",
        "criteria": {
          "facturacion": "Cobros, pagos y reembolsos",
          "soporte": "Fallas y errores del producto",
          "ventas": "Precios, planes y contrataciones"
        }
      }
    }
  }
}

2. El paso responde. El resultado trae una entrada por pregunta, con el nombre que le pusiste:

{
  "tema": {
    "type": "choice",
    "choice": "soporte",
    "probabilities": {
      "facturacion": 0.08,
      "soporte": 0.89,
      "ventas": 0.03
    },
    "confidence": 0.85
  }
}

3. El siguiente paso lo usa. Se lee con {{steps.N.output...}}, donde N es la posición del paso que produjo el resultado, empezando en 0:

{
  "name": "Notificar al equipo",
  "actionKey": "http.request",
  "input": {
    "method": "POST",
    "url": "https://ejemplo.com/hooks/asignacion",
    "headers": { "Content-Type": "application/json" },
    "body": {
      "equipo": "{{steps.0.output.tema.choice}}"
    }
  }
}

En un caso real, state viene del trigger o de un paso anterior en vez de ir escrito a mano. Las rutas disponibles están en Variables y contexto:

"state": "{{trigger.body.contact.values.<fieldId>}}"

Los tres tipos de pregunta

`type`	Qué responde	Qué defines en `criteria`	Qué recibes
`choice`	Una opción de un conjunto	Un mapa de 2 a 255 opciones con su descripción	La opción ganadora y la probabilidad de cada una
`score`	Una posición en una escala	Un arreglo ordenado de 2 a 10 niveles, de menor a mayor	Un número que puede caer entre niveles
`noul`	Si una afirmación es cierta	Nada, o el significado de `true` y `false`	Una probabilidad de 0 a 1

noul es el nombre que TypeSafe AI le da a su pregunta de sí/no, y su respuesta es un número: qué tan probable es que la afirmación sea cierta. 0.95 es un sí con pocas dudas, 0.5 significa que el modelo no puede distinguir. Tú eliges a partir de qué valor actuar.

Haz preguntas atómicas. En lugar de “¿es urgente y de facturación?”, usa dos preguntas: una choice para el tema y una score para la urgencia. Cada una se evalúa mejor por separado.

Un mismo paso admite hasta 20 preguntas y las resuelve todas en una sola llamada. Agrupa ahí todas las que se refieran al mismo texto.

Campos del paso

El paso tiene dos campos, y los dos son obligatorios.

Campo	Descripción
`input.state`	Los datos a evaluar: un texto, un objeto o un arreglo. Acepta plantillas `{{...}}`.
`input.questions`	Mapa de 1 a 20 preguntas. Tú eliges el nombre de cada una.

Los nombres de las preguntas se vuelven las llaves del resultado, así que usa identificadores simples: letras, números y guion bajo, empezando por letra (tema, requiereHumano, nivel_riesgo).

Campos de cada pregunta

Campo	Aplica a	Descripción
`instructions`	Todas	La pregunta, en una frase clara. Hasta 2000 caracteres.
`criteria`	`choice`	Mapa de opciones y su descripción. Obligatorio.
`criteria`	`score`	Arreglo de niveles, de menor a mayor. Obligatorio.
`criteria`	`noul`	Opcional: `{ "true": "...", "false": "..." }` para precisar qué significa cada lado.

Ejemplo con varias preguntas

{
  "name": "Clasificar el mensaje",
  "actionKey": "decision.evaluate",
  "input": {
    "state": "{{trigger.body.contact.values.<fieldId>}}",
    "questions": {
      "tema": {
        "type": "choice",
        "instructions": "¿Sobre qué trata el mensaje?",
        "criteria": {
          "facturacion": "Cobros, pagos y reembolsos",
          "soporte": "Fallas y errores del producto",
          "ventas": "Precios, planes y contrataciones",
          "otro": "Cualquier otro asunto"
        }
      },
      "urgencia": {
        "type": "score",
        "instructions": "¿Qué tan urgente es atender este mensaje?",
        "criteria": [
          "Consulta informativa, puede esperar varios días",
          "Trámite normal, se atiende esta semana",
          "Bloquea el trabajo del cliente, requiere atención hoy"
        ]
      },
      "requiereHumano": {
        "type": "noul",
        "instructions": "¿El mensaje necesita que lo atienda una persona?"
      }
    }
  }
}

Describe cada nivel de un score con una situación concreta. Entre “Trámite normal, se atiende esta semana” y “Nivel 1” hay una diferencia grande en la calidad del resultado.

Campos del resultado

{
  "tema": {
    "type": "choice",
    "choice": "soporte",
    "probabilities": {
      "facturacion": 0.18,
      "soporte": 0.76,
      "ventas": 0.04,
      "otro": 0.02
    },
    "confidence": 0.71
  },
  "urgencia": {
    "type": "score",
    "score": 1.8,
    "legend": {
      "0": "Consulta informativa, puede esperar varios días",
      "1": "Trámite normal, se atiende esta semana",
      "2": "Bloquea el trabajo del cliente, requiere atención hoy"
    },
    "probabilities": { "0": 0.02, "1": 0.16, "2": 0.82 },
    "confidence": 0.79
  },
  "requiereHumano": {
    "type": "noul",
    "noul": 0.64
  }
}

Campo	En qué preguntas	Qué es	Ejemplo de ruta
`choice`	`choice`	La opción ganadora.	`{{steps.0.output.tema.choice}}`
`score`	`score`	La posición en la escala. Puede caer entre niveles.	`{{steps.0.output.urgencia.score}}`
`noul`	`noul`	La probabilidad, de 0 a 1, de que la afirmación sea cierta.	`{{steps.0.output.requiereHumano.noul}}`
`probabilities`	`choice`, `score`	La probabilidad de cada opción o nivel. Suman 1.	`{{steps.0.output.tema.probabilities.soporte}}`
`legend`	`score`	Qué significa cada nivel.	`{{steps.0.output.urgencia.legend.2}}`
`confidence`	`choice`, `score`	Qué tan concentrada está la respuesta: `1` cuando casi toda la probabilidad cae en una sola opción, cerca de `0` cuando está repartida.	`{{steps.0.output.tema.confidence}}`

Decidir con el resultado

Los pasos se ejecutan en orden, así que este paso responde y los siguientes actúan. Cuando la acción depende de qué tan segura sea la respuesta, resuélvelo en un paso Ejecutar JavaScript:

{
  "name": "Elegir destino",
  "actionKey": "code.javascript",
  "input": {
    "tema": "{{steps.0.output.tema.choice}}",
    "certeza": "{{steps.0.output.tema.confidence}}",
    "humano": "{{steps.0.output.requiereHumano.noul}}"
  },
  "code": "output = { destino: (input.certeza < 0.6 || input.humano > 0.7) ? 'revision-humana' : input.tema };"
}

Ese 0.6 y ese 0.7 son decisiones de tu operación. Elígelos con ejemplos reales de tu tráfico: empieza por la consecuencia, porque mandar un caso a la fila equivocada cuesta distinto que enviarle algo incorrecto a un cliente. Mide cuántos casos deja pasar mal antes de fijarlos.

probabilities y confidence miden cosas distintas. La probabilidad dice qué tan probable es esa opción; la confianza dice qué tan concentrada está la respuesta entre todas las opciones. Una opción puede ganar con 0.4 mientras las otras tres se reparten el resto: gana, pero la respuesta no es concluyente. Ahí es donde la confianza baja te avisa.

Buenas prácticas

Manda solo lo que la pregunta necesita. Apunta state al campo específico en vez de pasar el objeto completo. Menos ruido produce mejores respuestas y cuesta menos.
Agrupa las preguntas del mismo texto en un solo paso. Se resuelven juntas y en una sola llamada.
Usa confidence para saber cuándo escalar a una persona en lugar de actuar sobre una respuesta repartida.
Deja las reglas deterministas en código. Si algo se resuelve con una fecha o una comparación, hazlo en un paso de JavaScript.

Errores frecuentes

Situación	Qué hacer
Una `choice` elige siempre la misma opción	Las descripciones de `criteria` se traslapan. Redáctalas de forma excluyente.
La `confidence` siempre sale baja	La pregunta es ambigua o el `state` carece de la información para responderla.
El paso se rechaza por el nombre de una pregunta	Usa solo letras, números y guion bajo, empezando por letra. Un punto en el nombre impide leer el resultado con plantillas.
Una plantilla resuelve vacío	Revisa la ruta: el resultado va anidado por pregunta, como `{{steps.0.output.tema.choice}}`.
Un `score` devuelve un decimal	Es el comportamiento esperado: el valor cae entre dos niveles cuando la respuesta está repartida. Compáralo contra un umbral.

Profundizar en el modelo

Los tipos de pregunta y los campos de respuesta usan la misma nomenclatura que TypeSafe AI, así que su documentación de primitivos y de confianza aplica tal cual a este paso. Ve ahí si quieres entender cómo se calculan las probabilidades o cómo redactar mejores criteria. La versión del modelo queda fija del lado del servidor, para que el comportamiento de tus automatizaciones no cambie sin aviso.

​El ciclo completo

​Los tres tipos de pregunta

​Campos del paso

​Campos de cada pregunta

​Ejemplo con varias preguntas

​Campos del resultado

​Decidir con el resultado

​Buenas prácticas

​Errores frecuentes

​Profundizar en el modelo

​Relacionado

El ciclo completo

Los tres tipos de pregunta

Campos del paso

Campos de cada pregunta

Ejemplo con varias preguntas

Campos del resultado

Decidir con el resultado

Buenas prácticas

Errores frecuentes

Profundizar en el modelo

Relacionado