---
title: "Evaluaciones"
description: "Prueba un cambio en un agente de texto de Raíz con respuestas reales de WhatsApp que tu equipo corrigió, antes de que el cambio llegue a los pacientes."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

| `source` | De dónde viene |
| --- | --- |
| `correction` | Una persona de tu equipo escribió justo después de la respuesta. |
| `authored` | Tu equipo registró comentarios sobre la respuesta. |
| `sample` | Una respuesta tomada como muestra. |

[`raiz.evalCases.create`](/api/raiz/eval-cases/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.

```bash
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`](/api/raiz/eval-cases/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`](/api/raiz/eval-cases/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`](/api/raiz/eval-runs/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`.

```bash
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`](/api/raiz/eval-runs/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:

| Campo | Qué dice |
| --- | --- |
| `verdict` | `passed`: la respuesta nueva hace lo que espera tu equipo. `failed`: no lo hace, o la candidata no escribió ninguna respuesta. `error`: el caso no se pudo reproducir o juzgar, y `errorCode` dice por qué. |
| `reply` | La respuesta de la candidata tal como la habría leído el contacto. |
| `escalated`, `handedOff` | Si la candidata escaló la conversación a tu equipo o se la pasó a una persona. |
| `toolCalls` | Las herramientas que llamó la candidata, en orden. Ninguna se ejecutó. |
| `reasons` | Las razones del juez. |

## 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`](/api/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:

| Operación | Scopes |
| --- | --- |
| `raiz.evalCases.create` | `raiz:conversations:write`, y `raiz:agents:read` o `raiz:agents:write` |
| `raiz.evalCases.list`, `raiz.evalRuns.get` | `raiz:agents:read` o `raiz:agents:write`, y `raiz:conversations:read` o `raiz:conversations:write` |
| `raiz.evalCases.update`, `raiz.evalRuns.create` | `raiz:agents:write`, y `raiz:conversations:read` o `raiz:conversations:write` |

Solo `raiz.evalCases.create` se ofrece en [MCP](/developers/mcp/); las demás son solo por REST.

Source: https://docs.getarbol.com/developers/raiz/evaluations/index.mdx