Crear casos con la API

Benchmarks está en vista previa y se habilita para las organizaciones de forma gradual. Los endpoints y herramientas de esta página están disponibles cuando Benchmarks está habilitado para tu organización; hasta entonces responden 403 not_entitled.

Todo lo que hace el menú Agregar casos del panel lo puedes hacer con la API REST o con MCP: escribir casos a mano, convertir conversaciones o trazas de producción en casos de forma masiva, y adjuntar expectativas de llamadas a herramientas y ajustes de jueces. Ambas superficies usan el mismo servicio que el panel, así que un caso creado por API es idéntico a uno creado en la interfaz.

Qué es un caso

Un caso es una entrada más su resultado esperado. Cada caso tiene un caseType:

`caseType`	Benchmark	Entrada	Resultado esperado
`turn`	LLM	La conversación hasta ese punto (mensajes, llamadas a herramientas anteriores y sus resultados), el prompt contra el que se ejecuta y las variables de la llamada. El candidato produce una generación: una respuesta, llamadas a herramientas o ambas.	Una respuesta de referencia, indicaciones de lo que debió decir en su lugar y/o una expectativa de llamadas a herramientas.
`conversation`	LLM	Un llamante simulado (persona, objetivo, frase inicial), un límite de turnos y simulaciones de herramientas. El candidato habla con el llamante hasta que la conversación termina. Las herramientas se simulan, nunca se ejecutan.	Notas de rúbrica, si se alcanzó el objetivo, recorrido de nodos y herramientas que deben o no deben llamarse.
`audio`	STT	Un clip de audio.	La transcripción de referencia, más términos clave opcionales que deben transcribirse exactamente.

Un caso turn no es dueño de un prompt. Apunta a una versión del agente (prompt.agentVersionId), así que el mismo caso puede reproducirse contra varias revisiones de prompt y modelos.

Autenticación

Usa una clave de API de la organización como token bearer. La misma clave sirve para REST y para MCP. Crear y editar casos es una escritura: la clave debe pertenecer a un propietario o administrador de la organización; si no, la solicitud se rechaza con 403.

export ZELTO_API_KEY="zk_..."
export BENCHMARK_ID="..."   # de GET /v1/benchmarks o de la URL del benchmark

Los casos solo pueden referirse a agentes asignados al benchmark. Para agregar un caso de otro agente, asigna primero ese agente al benchmark.

Crear casos

POST /v1/benchmarks/{id}/cases crea hasta 100 casos por solicitud y los devuelve en data.

curl -X POST "https://api.zelto.ai/v1/benchmarks/$BENCHMARK_ID/cases" \
  -H "Authorization: Bearer $ZELTO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-2026-10-31-batch-1" \
  -d @cases.json

cases.json

{
  "cases": [
    {
      "caseType": "turn",
      "input": {
        "prompt": { "agentVersionId": "6f1c2a9e-..." },
        "variables": { "customer_name": "Jordan Reyes", "balance": "$240.00" },
        "messages": [
          { "role": "assistant", "content": "Hola, habla Ana de Acme. ¿Hablo con Jordan?" },
          { "role": "user", "content": "Sí. Este mes no puedo pagar el saldo completo." }
        ]
      },
      "expected": {
        "replyExpectation": {
          "check": "different",
          "text": "Ofrecer un plan de pagos antes de mencionar recargos por mora.",
          "idealReply": "Entiendo. Podemos dividir los $240 en tres pagos mensuales. ¿Le sirve?"
        },
        "mustNotContain": ["recargo"]
      },
      "tags": ["payment-plan", "hardship"]
    }
  ]
}

Respuesta (201)

{
  "data": [
    {
      "id": "3f9a6c1e-...",
      "version": 1,
      "status": "ready",
      "source": "api",
      "sourceConversationId": null,
      "input": { "...": "..." },
      "expected": { "...": "..." },
      "groupId": null,
      "tags": ["payment-plan", "hardship"],
      "autoTags": ["source:api"]
    }
  ]
}

Envía un encabezado Idempotency-Key en la creación por lotes para que una solicitud reintentada devuelva los casos que creó la primera vez en lugar de crear duplicados.

Campos del caso

Campo	Aplica a	Descripción
`caseType`	todos los casos LLM	`turn` o `conversation`. Los casos STT lo omiten y se devuelven como `audio`.
`input.prompt`	`turn`, `conversation`	`{ "agentVersionId": "<uuid>" }`: el prompt contra el que se ejecuta el caso cuando un candidato usa el prompt propio del caso.
`input.messages`	`turn`	El historial antes del paso evaluado. Cada mensaje tiene un `role` (`user`, `assistant` o `tool`) y `content`; un mensaje de herramienta lleva `toolCall: { name, arguments, result }`.
`input.variables`	`turn`, `conversation`	Valores para los marcadores `{{variable}}` del prompt. Si el prompt necesita una variable que el caso no aporta, ese resultado falla de forma explícita en lugar de enviar el marcador sin reemplazar.
`input.activeNodeId`	`turn`	Para agentes basados en nodos: el nodo en el que está la conversación en este paso.
`input.persona`	`conversation`	`{ role, goal, traits?, knowledge?, openingLine?, firstSpeaker? }` del llamante simulado. `firstSpeaker` es `agent` o `caller`.
`input.maxTurns`	`conversation`	Límite de turnos, hasta 30 (12 por defecto).
`input.toolMocks`	`conversation`	Resultados predefinidos para llamadas a herramientas: `{ tool, match?, response, once? }`. `match` usa los comparadores de argumentos.
`input.onUnmatchedTool`	`conversation`	`error` (por defecto) hace fallar el resultado cuando el agente llama a una herramienta sin simulación que coincida; `generic_mock` devuelve `{"ok": true}`.
`input.startNodeId`, `input.prefix`	`conversation`	Nodo inicial opcional y mensajes opcionales desde los que empezar (por ejemplo, los primeros turnos de una llamada real).
`expected.referenceAnswer`	`turn`	La respuesta de referencia.
`expected.replyExpectation`	`turn`	Cómo se califica la respuesta: `check` es `reference` (comparar con la respuesta de referencia), `different` (se califica contra `text`, lo que el agente debió hacer, con un `idealReply` opcional) o `none` (los jueces de respuesta no aplican a este caso).
`expected.toolExpectation`	`turn`	Qué llamadas a herramientas debe o no debe hacer el paso. Consulta Expectativas de llamadas a herramientas.
`expected.rubricNotes`	LLM	Indicaciones específicas del caso para los jueces LLM.
`expected.mustContain`, `expected.mustNotContain`	`turn`	Frases que la respuesta debe incluir o evitar.
`expected.expectedTransition`	`turn`	Para agentes basados en nodos: `{ "toNodeId": "..." }` o `{ "stay": true }`.
`expected.goalReached`, `pathIncludes`, `pathExcludes`, `toolCalled`, `toolNotCalled`	`conversation`	Verificaciones del resultado de la conversación.
`skippedJudgeIds`	todos	Jueces que se omiten en este caso. Consulta Omitir o ajustar un juez.
`judgeParamOverrides`	todos	Valores por caso para los parámetros de un juez.
`variableOverrides`	casos de producción	Reemplaza una variable capturada en este caso: `{ "<name>": { "value": "...", "kind": "edited" \| "placeholder" } }`. Solo se aceptan nombres que el caso capturó.
`groupId`	todos	El grupo al que pertenece el caso (como máximo uno).
`tags`	todos	Etiquetas libres para segmentar resultados. Nunca afectan la puntuación.

Un caso turn debe verificar al menos algo: una expectativa de respuesta distinta de none, o una expectativa de herramientas.

Expectativas de llamadas a herramientas

toolExpectation verifica si el paso llamó a la herramienta correcta y si la llamada tiene la forma correcta. Elige una de tres formas:

`expect`	Pasa cuando
`call`	El paso hace las `calls` indicadas (en orden si `ordered` es `true`) y ninguna de las `forbiddenTools`.
`no_call`	El paso responde directamente y no llama a ninguna herramienta.
`any`	El paso puede llamar herramientas o no, pero nunca una de las `forbiddenTools`.

Este caso espera que se cree un plan de pagos de tres cuotas, en la moneda del cliente, y nunca un reembolso:

{
  "expected": {
    "replyExpectation": { "check": "none" },
    "toolExpectation": {
      "expect": "call",
      "ordered": true,
      "calls": [
        {
          "tool": "create_payment_plan",
          "arguments": {
            "installments": { "op": "equals", "value": 3 },
            "currency": { "op": "one_of", "values": ["USD", "usd"] },
            "first_payment_date": { "op": "semantic", "description": "una fecha dentro de los próximos 7 días" },
            "notes": { "op": "ignore" }
          }
        }
      ],
      "forbiddenTools": ["issue_refund"],
      "noExtraArguments": false
    }
  }
}

Solo se verifican los argumentos que indicas; usa noExtraArguments: true para que fallen las llamadas que envían cualquier otro argumento. Cuando un paso habla y además llama herramientas, replyAt (con ordered: true) fija dónde va la respuesta entre las llamadas: 0 significa antes de todas. Cada tool indicada debe existir en el prompt del caso.

Comparadores de argumentos

`op`	Pasa cuando
`equals`	El valor es igual en profundidad a `value`.
`one_of`	El valor es igual a uno de `values`.
`regex`	El valor coincide con `pattern` (sintaxis RE2).
`number_range`	El número está entre `min` y `max` (ambos opcionales).
`present`	Cualquier valor no nulo.
`semantic`	Un LLM juzga que el valor se ajusta a `description`, por ejemplo “significa el próximo viernes”. Es el único comparador con costo de juez.
`ignore`	Nunca se verifica.

Además de los comparadores, los argumentos de cada llamada deben validar contra el JSON schema de la herramienta: "amount": "240" falla en un argumento { "type": "number" }.

Omitir o ajustar un juez para un caso

Los jueces se definen en el benchmark. Obtén sus ids con GET /v1/benchmarks/{id} (validators[]); la API llama a los jueces “validators”.

skippedJudgeIds excluye este caso de jueces que no tienen sentido para él, como una rúbrica de tono en un paso que solo llama herramientas. Los jueces obligatorios no se pueden omitir, y al menos un juez debe seguir ejecutándose.
judgeParamOverrides cambia los parámetros de un juez solo para este caso. Un juez con la etiqueta “Respuesta de menos de palabras” y un valor por defecto de 60 puede ajustarse a 10 para un caso:

{
  "skippedJudgeIds": ["<tone-judge-id>"],
  "judgeParamOverrides": {
    "<length-judge-id>": { "maxWords": 10 }
  }
}

Cada id de juez y clave de parámetro debe existir en el benchmark, y los valores deben coincidir con el tipo del parámetro y respetar su min / max. Un ajuste para un juez que también omites se descarta.

Casos de conversación

{
  "caseType": "conversation",
  "input": {
    "prompt": { "agentVersionId": "6f1c2a9e-..." },
    "persona": {
      "role": "Cliente que se atrasó en dos pagos",
      "goal": "Conseguir dividir el saldo en pagos más pequeños",
      "traits": "Amable pero firme; cuelga si lo presionan",
      "firstSpeaker": "agent"
    },
    "maxTurns": 12,
    "variables": { "customer_name": "Jordan Reyes", "balance": "$240.00" },
    "toolMocks": [
      { "tool": "get_balance", "response": { "balance": 240, "currency": "USD" } },
      {
        "tool": "create_payment_plan",
        "match": { "installments": { "op": "number_range", "min": 2, "max": 6 } },
        "response": { "ok": true, "planId": "pp_123" }
      }
    ],
    "onUnmatchedTool": "error"
  },
  "expected": {
    "rubricNotes": "El agente ofrece un plan antes de mencionar recargos y confirma la fecha del primer pago.",
    "goalReached": true,
    "toolNotCalled": { "tool": "issue_refund", "arguments": {} }
  }
}

Casos de audio (STT)

En un benchmark STT, cada caso es { audio, referenceTranscript, keyTerms?, tags? }. El audio nunca pasa por el cuerpo de la solicitud, salvo clips cortos:

Prepara el archivo con POST /v1/recording-uploads y luego haz PUT de los bytes a la uploadUrl devuelta.
Crea el caso con "audio": { "uploadId": "<id>" }.

También puedes enviar "audio": { "url": "https://..." } (Zelto lo descarga; el caso queda preparing hasta que termina la descarga) o, para clips de hasta 3 MB, "audio": { "base64": "...", "contentType": "audio/wav" }.

{
  "cases": [
    {
      "audio": { "uploadId": "<upload-id>" },
      "referenceTranscript": "Mi número de cuenta es 4 4 7 1 9 y quiero cancelar.",
      "keyTerms": ["44719"],
      "tags": ["noisy", "lang:es"]
    }
  ]
}

Agregar casos desde llamadas de producción

POST /v1/benchmarks/{id}/cases/from-conversations convierte hasta 100 conversaciones en casos en una sola solicitud, con el mismo mapeo que Desde llamadas de producción en el panel. Cada caso registra la versión del agente de la llamada, los valores de variables capturados de la llamada, el nodo activo (en agentes basados en nodos) y la transcripción previa al turno evaluado.

curl -X POST "https://api.zelto.ai/v1/benchmarks/$BENCHMARK_ID/cases/from-conversations" \
  -H "Authorization: Bearer $ZELTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationIds": ["0b6e...", "1c7f...", "2d80..."],
    "turn": "last_assistant"
  }'

Campo	Descripción
`conversationIds`	Hasta 100 ids de conversación. Encuéntralos con `GET /v1/conversations`. Cada llamada debe pertenecer a un agente asignado al benchmark.
`turn`	LLM: `last_assistant` (por defecto) o un número de turno.
`as`	LLM: `turn` (por defecto) o `conversation`. `conversation` redacta una persona, un objetivo y simulaciones de herramientas a partir de cada llamada y los devuelve como casos `draft` para que los revises.
`trim`	STT: `{ "startSeconds": 12, "endSeconds": 31 }` para recortar la grabación a una sola intervención. La grabación se copia al benchmark al crear el caso, y la referencia se rellena con la transcripción de la llamada y se marca como no verificada.

Las variables capturadas aparecen enmascaradas en la respuesta. Los casos cuyo nodo no se pudo resolver vuelven como draft. Usa PATCH /v1/benchmarks/{id}/cases/{caseId} para afinar cualquier caso después: cambiar su resultado esperado, agregar una expectativa de herramientas, reemplazar una variable capturada con variableOverrides, o enviar "status": "ready" para aceptar un borrador.

Agregar casos desde trazas

POST /v1/benchmarks/{id}/cases/from-traces crea hasta 100 casos a partir de trazas, igual que Agregar al benchmark en una traza o un span.

curl -X POST "https://api.zelto.ai/v1/benchmarks/$BENCHMARK_ID/cases/from-traces" \
  -H "Authorization: Bearer $ZELTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "traceId": "4bf92f3577b34da6a3ce929d0e0e4736", "spanId": "00f067aa0ba902b7" },
      { "traceId": "a1b2c3d4e5f60718293a4b5c6d7e8f90" }
    ]
  }'

Con un spanId (un span de LLM o de herramienta), el caso prueba esa única llamada al LLM: los mensajes de entrada del span se convierten en el historial, y su salida en el paso esperado.
Sin spanId, se usa la conversación vinculada de la traza, como from-conversations con turn: "last_assistant".

Cada caso creado informa turnSource: span_messages cuando el historial vino del span, o transcript cuando vino de la llamada vinculada. Una traza sin llamada vinculada necesita un span que haya registrado sus mensajes; si no, ese elemento falla con 422 no_turn_source.

Con MCP

El servidor MCP de Zelto expone las mismas operaciones como herramientas, así que puedes pedirle a Claude, Cursor o cualquier cliente MCP que construya un benchmark por ti:

Herramienta	Qué hace	Límite por llamada
`add_benchmark_cases`	Crea casos `turn` o `conversation` (misma forma que `POST …/cases`, más `groupId` y `tags`).	50
`add_benchmark_cases_from_conversations`	Convierte llamadas de producción en casos.	50
`add_benchmark_cases_from_traces`	Convierte trazas o spans en casos (elementos `{ traceId, spanId? }`).	50
`create_benchmark_audio_upload`	Obtiene una URL de carga prefirmada (y una línea `curl -T` lista) para un caso de audio.	—
`update_benchmark_case`, `retire_benchmark_case`	Edita un caso (una nueva revisión en el borrador) o lo retira.	—
`list_benchmarks`, `get_benchmark`, `list_benchmark_cases`	Encuentra benchmarks, sus jueces y los casos existentes.	—
`publish_benchmark_version`	Publica el borrador.	—

Un prompt de ejemplo:

En Zelto, busca el benchmark "Collections next-turn" y agrega un caso por
cada una de las últimas 30 llamadas fallidas del agente Collections, usando el
último turno del asistente. En las llamadas donde el agente debió ofrecer un plan
de pagos, espera una llamada a create_payment_plan con entre 2 y 6 cuotas, y
nunca issue_refund. Etiquétalos "payment-plan". Muéstrame el borrador antes de
publicar.

El cliente llama a list_benchmarks, list_conversations, add_benchmark_cases_from_conversations y luego a update_benchmark_case para las expectativas de herramientas.

Dónde quedan los casos nuevos

Los casos nuevos y editados van al borrador del benchmark, la copia de trabajo que el panel muestra como “Cambios en borrador”. Las ejecuciones usan por defecto la última versión publicada, así que los casos nuevos entran en una ejecución solo después de publicar:

curl -X POST "https://api.zelto.ai/v1/benchmarks/$BENCHMARK_ID/versions" \
  -H "Authorization: Bearer $ZELTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Agregar 30 casos de plan de pagos de llamadas de octubre" }'

Publicar excluye los casos que siguen en estado draft y te avisa de ellos. Los propietarios y administradores también pueden ejecutar el borrador directamente; esa ejecución se marca como “ejecución de borrador”. Los casos nunca se eliminan: editar uno crea una nueva revisión, y retirarlo lo quita de la siguiente versión mientras las ejecuciones anteriores conservan sus resultados.

Errores

Los errores son JSON: { "error": "<code>", "details": ... }.

Estado	Cuándo
`400`	El cuerpo no es válido. `details` enumera los problemas, por ejemplo: una herramienta de una expectativa que no está en el prompt del caso, `expect: "call"` sin llamadas, una regex inválida, un caso sin nada que verificar, un juez desconocido u obligatorio en `skippedJudgeIds` (u omitir todos los jueces), un parámetro desconocido o un valor fuera de rango en `judgeParamOverrides`, un nombre en `variableOverrides` que el caso no capturó, más casos que el límite por solicitud, o un caso o conversación cuyo agente no está asignado al benchmark (`agent_not_assigned`; asigna primero el agente).
`403`	El dueño de la clave no es propietario ni administrador de la organización, o Benchmarks no está habilitado para tu organización (`not_entitled`).
`404`	El benchmark, la conversación, la traza o la versión del agente no está en tu organización.
`409`	Un conflicto con el estado actual del benchmark, por ejemplo publicar sin cambios en el borrador (`no_draft_changes`).
`422 no_turn_source`	Una traza sin llamada vinculada y sin mensajes de span con los que construir un caso.

Por MCP, los mismos rechazos llegan como resultados de herramienta con isError: true; consulta Resultados de error.

Contenido relacionado

Benchmarks: casos, jueces y versiones.
Versiones de agentes: a qué apunta prompt.agentVersionId.
MCP: conectar un cliente y autenticarse.

Primeros pasos

Conceptos principales

Integraciones

Guías

Cuenta y configuración

Legal

Crear casos con la API

Qué es un caso

Autenticación

Crear casos

Campos del caso

Expectativas de llamadas a herramientas

Comparadores de argumentos

Omitir o ajustar un juez para un caso

Casos de conversación

Casos de audio (STT)

Agregar casos desde llamadas de producción

Agregar casos desde trazas

Con MCP

Dónde quedan los casos nuevos

Errores

Contenido relacionado

​Qué es un caso

​Autenticación

​Crear casos

​Campos del caso

​Expectativas de llamadas a herramientas

​Comparadores de argumentos

​Omitir o ajustar un juez para un caso

​Casos de conversación

​Casos de audio (STT)

​Agregar casos desde llamadas de producción

​Agregar casos desde trazas

​Con MCP

​Dónde quedan los casos nuevos

​Errores

​Contenido relacionado

Qué es un caso

Autenticación

Crear casos

Campos del caso

Expectativas de llamadas a herramientas

Comparadores de argumentos

Omitir o ajustar un juez para un caso

Casos de conversación

Casos de audio (STT)

Agregar casos desde llamadas de producción

Agregar casos desde trazas

Con MCP

Dónde quedan los casos nuevos

Errores

Contenido relacionado