Evaluaciones

Una evaluación revisa un cambio en un agente antes de que lo vean los pacientes. Cuando tu equipo dice que una de las respuestas de WhatsApp del agente estuvo mal, incompleta o podría ser más sencilla, esa respuesta se convierte en un caso de evaluación. Antes de que cambies las instrucciones, las skills o el modelo del agente, Raíz puede volver a reproducir con la nueva versión los casos que conservaste, sin enviarle nada a nadie y sin ejecutar ninguna herramienta, y un modelo juez dice si cada respuesta nueva hace lo que espera tu equipo. Las evaluaciones cubren los agentes de texto.

Casos de evaluación

Un caso es una respuesta de WhatsApp completada de un agente (replyMessageId en conversationId) y, cuando se registró, la versión del agente que la escribió (agentVersionId). Su source dice de dónde viene:

raiz.evalCases.create registra los comentarios de tu equipo sobre una respuesta. Recibe el conversationId y el replyMessageId del agente, un feedbackKind (incorrect, incomplete o simpler), una expectation, que dice lo que el agente debió hacer en forma de una rúbrica corta, y una preferredResponse: la respuesta o el procedimiento que prefiere tu equipo. No escribas datos personales del contacto en la expectativa. Registrar comentarios no contacta a nadie ni cambia ninguna instrucción en vivo, y repetirlo devuelve el caso existente.

curl https://api.getarbol.com/v1/raiz/eval-cases \
  --request POST \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "conversationId": "cnv_01jd8x8d5e6f7g8h9j0k1m2n3p",
    "replyMessageId": "msg_01jd8xek1m2n3p4q5r6s7t8v9w",
    "feedbackKind": "incomplete",
    "expectation": "Ofrecer el siguiente cupo disponible en otra sede cuando la sede solicitada no tiene ninguno.",
    "preferredResponse": "La sede Norte no tiene citas esta semana. Puedo agendarte en la sede Sur el jueves a las 9:00. ¿Te sirve?"
  }'

Revisar los casos

Un caso empieza en open. raiz.evalCases.update lo revisa: kept significa que toda versión candidata debe resolverlo, y dismissed significa que no es un caso, como cuando una persona solo continuó después de un traspaso. La revisión también puede reescribir la expectation, la preferredResponse y el feedbackKind, con expectedVersion. raiz.evalCases.list lista los casos, del más reciente al más antiguo, por agentId, status, source y replyMessageId; lee la conversación misma para juzgar uno.

Ejecuciones de evaluación

raiz.evalRuns.create mide una versión candidata de un agente de texto con sus casos conservados: sus 50 más recientes, o los de caseIds (hasta 50). El candidate contiene lo que cambia en lo que lee el modelo, instructions, skills, integrationSkills, model y reasoningEffort, y todo lo que omitas se queda como lo tiene el agente en vivo. Una ejecución llama a modelos de pago, así que necesita "confirmCost": true.

curl https://api.getarbol.com/v1/raiz/eval-runs \
  --request POST \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agentId": "agt_01jd8x5k2m7q9r3t6v8w0y4z1b",
    "candidate": { "model": "arbolito/balanced" },
    "confirmCost": true
  }'

En cada caso, el agente vuelve a escribir su respuesta con la candidata. No se ejecuta ninguna herramienta de integración, ya que cada una responde lo que respondió en la conversación original, y no se envía nada. Luego un modelo juez compara la respuesta nueva con lo que espera tu equipo. Un agente sin ningún caso conservado para reproducir, o un caso de caseIds que no es uno de sus casos conservados, responde 409 EVAL_CASES_UNAVAILABLE.

Leer los resultados

Sigue la ejecución con raiz.evalRuns.get. Su status es queued, luego running mientras se reproducen los casos, luego completed una vez que cada caso tiene un resultado, o failed si no pudo continuar. passed, failed y errors cuentan los casos, y cada uno de sus results, que aparecen a medida que se juzgan, tiene:

Exigir una ejecución aprobada

Con settings.evalGate en un agente de texto, una actualización que cambia lo que lee su modelo (instructions, skills, integrationSkills, model o reasoningEffort) debe enviar evalRunId: una ejecución completada de exactamente ese contenido en la que pasaron todos los casos. Si no, raiz.agents.update responde 409 EVAL_GATE_UNMET. El contentSha256 de una ejecución es lo que la validación compara con la actualización.

Propuestas a partir de comentarios

En lugar de una candidata, una ejecución puede recibir feedbackCaseId, una corrección conservada. Raíz prepara una guía a partir de ella, que devuelve como proposal y como las proposedInstructions completas, y la prueba con los casos conservados más recientes del agente, incluyendo siempre ese. No combines feedbackCaseId con candidate ni con caseIds; confirmCost sigue siendo obligatorio. No se publica nada: revisa las instrucciones propuestas y luego envíalas a raiz.agents.update con el id de la ejecución como evalRunId y la expectedVersion del agente.

Permisos

Las evaluaciones necesitan un permiso (scope) de agentes y uno de conversaciones:

Solo raiz.evalCases.create se ofrece en MCP; las demás son solo por REST.