Una respuesta final correcta puede ocultar un camino malo. El agente pudo llamar a la tool equivocada, enviar un identificador inválido, repetir una consulta o necesitar una intervención humana que nunca apareció en el informe.

Por eso, evaluar un agente significa mirar su trayectoria, no solo su última frase. Aquí, trayectoria significa la secuencia observable de acciones entre la entrada del usuario y la respuesta final. El foco está en lo que hizo el sistema: tools, argumentos, resultados, estado y decisiones para detenerse.

Este artículo complementa la guía para elegir entre un mock y un modelo real al probar agentes. Ese texto ayuda a separar las capas de prueba. Este responde otra pregunta: ¿qué debe demostrar cada ejecución cuando el agente usa tools?

Diagrama que compara la trayectoria esperada y observada de un agente hasta su respuesta final.

Decisión práctica

  • Registra la trayectoria junto con la respuesta final.
  • Exige un orden exacto solo cuando el orden forme parte del contrato.
  • Comprueba tools, argumentos, acciones prohibidas y estado final de forma determinista.
  • Usa un evaluador semántico solo para lo que una regla observable no puede decidir.

¿Qué mide la trayectoria de un agente de IA?

Una trayectoria mide el camino que siguió un agente para completar una tarea. La guía de evaluación de Google ADK separa la evaluación del uso de tools y de la trayectoria de la evaluación de la respuesta final. Esa separación importa porque una respuesta puede parecer buena aunque el proceso haya tomado pasos innecesarios o incorrectos.

Imagina un agente que debe consultar el estado de un pedido. El resultado final debe incluir el estado correcto, pero el sistema también puede exigir que use get_order, envíe el ID recibido y no llame a cancel_order. Son tres afirmaciones diferentes: resultado, argumento y límite de acción.

El registro de la trayectoria no necesita exponer el razonamiento privado del modelo. Necesita suficientes eventos operativos para comprobar el contrato. Por lo general, eso incluye la entrada, llamadas a tools, argumentos validados, resultados resumidos, cambios de estado, intentos, intervenciones y salida.

Esto también se conecta con validar argumentos y respuestas de tools en TypeScript. La validación protege cada frontera. La evaluación de trayectoria comprueba si toda la ejecución cruzó esas fronteras correctamente.

¿Cómo registrar una trayectoria sin guardar demasiados datos?

Un registro útil es pequeño, estable y suficiente para la afirmación que quieres hacer. No copies todo el prompt ni cada log de infraestructura por defecto. Usa un formato de eventos que pueda sobrevivir a un cambio de proveedor.

El ejemplo siguiente es ilustrativo. Muestra una representación posible, pero no se ejecutó en este repositorio y no depende de un SDK concreto.

type ToolEvent = {
  kind: "tool_call";
  name: string;
  args: Record<string, unknown>;
  result: "ok" | "error";
};

type AgentTrajectory = {
  caseId: string;
  events: ToolEvent[];
  finalState: string;
  humanInterventions: number;
};

caseId conecta el trace con un caso de evaluación sin poner datos personales en el informe. name y args permiten comprobar la elección y el contrato. result separa una llamada correcta de un intento que terminó con error. finalState evita depender de la redacción de la respuesta. humanInterventions muestra cuándo el resultado apareció solo después de una decisión humana.

Adapta el esquema al riesgo de la aplicación. Para un agente que cambia registros, guarda también el objetivo normalizado, la versión de la política y un identificador de idempotencia. Para un coding agent, el equivalente puede ser archivos tocados, comandos ejecutados, pruebas activadas y artefactos producidos. No incluyas secretos, tokens ni payloads completos si basta con un resumen verificable.

¿Qué afirmaciones debe tener una evaluación de trayectoria?

Empieza con afirmaciones observables. Son más fáciles de explicar, repetir y ejecutar en CI. La trayectoria esperada no necesita copiar el transcript. Puede declarar solo los límites que importan para la tarea.

Afirmación Pregunta Ejemplo de fallo
Tool permitida ¿Usó el agente una acción disponible para este caso? Llamó delete_order durante una consulta.
Argumentos ¿Recibió la tool los campos y valores esperados? Usó el ID de otro pedido.
Orden ¿Debía ocurrir un paso antes que otro? Publicó antes de la aprobación.
Acción prohibida ¿Evitó acciones que no pertenecían al caso? Hizo una consulta externa innecesaria.
Estado ¿Terminó el efecto observable en el estado esperado? Dijo “cancelado”, pero el pedido siguió activo.

La guía de Google Cloud sobre evaluación de agentes describe métricas de trayectoria para coincidencia, precisión, recall y uso de una sola tool. Los nombres cambian entre frameworks, pero la decisión es la misma: elige la métrica que corresponde al contrato en lugar de usar la más estricta por defecto.

Una comprobación del estado suele ser más importante que una lista idéntica de tools. Si dos lecturas independientes llevan al mismo estado y no ocurrió una acción prohibida, exigir un orden concreto puede rechazar una ejecución válida. En cambio, una confirmación de pago, una aprobación o una migración destructiva normalmente tienen un orden que forma parte de su seguridad.

¿Cuándo conviene exigir un orden exacto?

Usa coincidencia exacta cuando la secuencia sea una condición previa del negocio o de la seguridad. Un caso simple es authorize_user antes de read_balance. Otro es validate_payload, después request_approval, y solo entonces publish_change.

No exijas un orden exacto solo porque el primer trace que viste tenía ese orden. El modelo puede elegir dos lecturas independientes en una secuencia distinta sin cambiar el resultado ni aumentar el riesgo. En esos casos, prefiere comprobaciones de conjunto, subsecuencia o estado final.

El proyecto LangChain AgentEvals separa coincidencia estricta, coincidencia sin orden, coincidencia de subconjunto y comparación de argumentos. Esas opciones no son respuestas universales. Ayudan a expresar el contrato que ya deberías haber definido.

Una política práctica podría verse así:

const contract = {
  requiredTools: ["get_order"],
  forbiddenTools: ["cancel_order", "delete_order"],
  requiredArgs: { get_order: { id: "ord-7" } },
  order: "any",
  finalState: "order:ord-7:visible",
};

El valor de order es una decisión del contrato. Si es any, la evaluación comprueba presencia, argumentos, acciones prohibidas y estado. Si es exact, compara toda la secuencia. El formato es ilustrativo y debe adaptarse al executor real.

¿Cómo separar comprobaciones deterministas de juicio semántico?

La evaluación semántica ayuda cuando no existe una respuesta única o una regla simple. Puede comprobar si una explicación es comprensible, si una respuesta se apoya en el resultado de una tool o si una conversación abierta alcanzó su objetivo. No debe reemplazar una regla que el código puede comprobar directamente.

Usa comprobaciones deterministas para nombres de tools, argumentos, orden obligatorio, acciones prohibidas, estado final, schemas y límites de intentos. Reserva un juez semántico para claridad, completitud o equivalencia de significado. Aun así, escribe una rúbrica breve y conserva la evidencia usada por el evaluador.

La documentación de evaluación de ADK recomienda criterios separados para trayectoria y respuesta. Para CI y regresión, señala métricas de trayectoria de tools y comparación de respuestas como opciones rápidas y predecibles. Los criterios basados en rúbricas sirven cuando no tienes una respuesta de referencia confiable.

Esta separación evita dos errores. El primero es aceptar una respuesta convincente que usó la tool equivocada. El segundo es rechazar una respuesta correcta porque no coincide palabra por palabra con una frase de referencia. La evaluación debe medir el riesgo que realmente quieres controlar.

¿Cómo llevar la evaluación de trayectoria al CI?

Separa la prueba rápida del eval que depende de red, modelo o juez. La primera debe ejecutarse en cada cambio e inspeccionar traces controlados. El segundo puede ejecutarse con una agenda, después de cambiar el prompt o al comparar versiones de modelo. El artículo sobre evals de regresión para coding agents en CI entra después, cuando necesitas conservar comportamientos que ya funcionaban.

Un flujo mínimo tiene estos pasos:

  1. Crea casos con entrada, tools disponibles, estado inicial y resultado esperado.
  2. Ejecuta el agente y guarda una trayectoria saneada junto con la respuesta.
  3. Aplica comprobaciones de tools, argumentos, acciones prohibidas y estado final.
  4. Ejecuta una rúbrica semántica solo en los casos que pasan las reglas básicas.
  5. Publica un resumen con fallos, intentos e intervención humana.
  6. Convierte cada fallo importante en un caso de regresión versionado.

Un job puede llamar a un script propio, una herramienta de evaluación del proveedor o una librería como AgentEvals. Lo importante es que el contrato sea visible en el repositorio y que el informe distinga la respuesta final de la trayectoria.

{
  "case": "show-order-status",
  "required_tools": ["get_order"],
  "forbidden_tools": ["cancel_order"],
  "expected_state": "order:ord-7:visible",
  "checks": ["tool", "args", "forbidden", "state"]
}

Este archivo es solo una idea de formato. ord-7 es un valor de ejemplo, no un dato de producción. En una suite real, crea fixtures controlados y evita reutilizar identificadores entre casos que puedan cambiar el mismo estado.

Para loops que atraviesan sesiones y acumulan contexto de trabajo, el autor usa RemoteCode como su herramienta. Esto describe el contexto de producción del autor, no un benchmark ni una promesa de calidad.

¿Qué fallos puede revelar la trayectoria?

La primera señal es la tool equivocada con una respuesta correcta. Una consulta secundaria pudo devolver el mismo texto del fixture, pero el agente violó el límite que querías probar. El segundo es un argumento casi correcto: el nombre de la tool está bien, pero el ID, tenant o filtro pertenece a otro caso.

La tercera señal es la intervención silenciosa. Una persona corrige el payload, aprueba una acción o repite un paso, mientras el informe registra solo “éxito”. Cuenta esa decisión como parte de la trayectoria. Un agente que termina solo después de un rescate no equivale a uno que completó el caso por sí mismo.

El cuarto es el camino desperdiciado. El agente llega al estado correcto después de llamadas repetidas, lecturas sin efecto o intentos que una regla debería haber bloqueado. Esto no significa que toda trayectoria larga esté mal. Significa que la eficiencia y la intervención pueden ser señales separadas del resultado.

¿Cómo comprobar que la suite mide el riesgo correcto?

Revisa la suite con un caso aprobado, un argumento inválido, una tool prohibida, una respuesta de error y una ejecución que necesita intervención. No añadas ejemplos solo para aumentar la cobertura aparente. Cada caso debe representar una decisión que alguien tomaría al operar el agente.

Comprueba también lo que el informe no muestra. Si solo guarda el texto final, no puedes distinguir una trayectoria segura de otra que llegó al mismo lugar por casualidad. Si guarda el transcript completo sin redactar, puede filtrar datos que no ayudan a la evaluación.

Una revisión útil pregunta:

  • ¿Los casos definen el estado inicial y final?
  • ¿Las tools prohibidas aparecen de forma explícita?
  • ¿Los argumentos se comparan al nivel que importa, sin exigir campos irrelevantes?
  • ¿El orden exacto está vinculado a una regla de negocio o seguridad?
  • ¿El informe registra retries, fallos e intervención humana?
  • ¿El juez semántico recibe solo el contexto que necesita?
  • ¿Un fallo nuevo se convierte en un caso reproducible?

Si alguna respuesta es “no”, el problema sigue siendo el contrato de evaluación. Cambiar el modelo o aumentar la puntuación no corrige una pregunta mal definida.

Preguntas frecuentes

¿Evaluar la respuesta final es suficiente?

No cuando la trayectoria tiene riesgo. Un agente puede responder correctamente después de usar una fuente prohibida, enviar argumentos incorrectos o recibir ayuda humana. Evalúa la respuesta por el resultado visible y la trayectoria por las acciones que produjeron ese resultado.

¿Toda trayectoria necesita un orden esperado?

No. Exige orden cuando un paso depende de otro, como la autorización antes de una lectura protegida. Para lecturas independientes, comprueba tools permitidas, argumentos, acciones prohibidas y estado final sin rechazar un orden equivalente.

¿Un juez de IA reemplaza las aserciones de las pruebas?

No. Usa código para comprobar campos, tools, estado y reglas de seguridad. Un juez puede ayudar con claridad, completitud o equivalencia semántica, pero su resultado necesita una rúbrica y evidencia revisable.

¿Puedo evaluar sin usar un framework de agentes?

Sí. El concepto es un contrato sobre eventos observables, no una marca de SDK. Puedes registrar llamadas en tu propio loop y aplicar aserciones con el runner de pruebas que ya usas. Las librerías y servicios ayudan a comparar trayectorias, pero no pueden decidir qué acciones permite tu dominio.

Conclusión

Un agente no pasa solo porque su última frase parezca correcta. Pasa cuando la ejecución respeta un contrato que puedes explicar: eligió tools permitidas, envió argumentos válidos, siguió el orden necesario, evitó acciones prohibidas y terminó en el estado esperado.

Empieza con una trayectoria pequeña y saneada. Añade aserciones deterministas antes de un juez semántico. Después lleva los casos fallidos al CI y convierte los incidentes en regresiones. Tu suite medirá lo que hizo el agente, no solo la historia que contó al final.

Fuentes consultadas