Notas prácticas: Evaluaciones: Un curso rápido para agentes y habilidades
Guía paso a paso operativa de las notas prácticas: Evaluaciones: un curso intensivo para agentes y Habilidades: contratos, verificaciones y espacios de código integrable para los equipos que implementan este patrón.
Las notas siguientes reconstruyen un camino práctico para trabajar con “Evals: A Crash Course for Agents and Skills”. Se da énfasis en los contratos, las verificaciones y los marcadores de posición para código, en lugar de en un enfoque motivacional. Al avanzar por la etapa de descripción general, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación ayuda a mantener honestas las futuras modificaciones en el código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben encontrarse en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema.
El modelo mental
La etapa del modelo mental funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación juntos. Las reintentos, los controles humanos y el manejo de correos no entregados forman parte del producto, no son mejoras posteriores. Asigne un presupuesto de tokens por turno y por sesión. Las herramientas agenciales amplían el contexto de manera excesiva; los límites máximos evitan que las demostraciones se conviertan en facturas inesperadas.
Las capas de evaluación
La etapa de capas de evaluación funciona mejor cuando se trata como una superficie medible. Capture un transcripte exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una sola responsabilidad y no a un proceso complicado. Mantenga el estado del grafo simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
Las habilidades requieren dos conjuntos de evaluación
The Skills need two eval stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y rompen la continuidad después de las interrupciones. The Skills need two eval stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo.
- prompt: "Patch the vulnerable npm dependencies"
expected_skill: cve-remediation
- prompt: "Review authentication input validation"
forbidden_skill: cve-remediation
Qué aspecto tiene un buen caso de evaluación
En la etapa de evaluación, es fundamental definir las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las intentonas repetidas, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Implemente la aprobación humana en aquellos casos que impliquen gastos o cambios en los datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial.
{
"id": "fix-null-condition",
"prompt": "Fix saving rules with a null condition",
"fixture": "repos/null-condition",
"setup": ["npm install"],
"checks": [
"npm test -- null-condition.test.js",
"git diff --check"
],
"rubric": [
"Fixes the root cause",
"Preserves existing behavior",
"Adds a regression test",
"Avoids unrelated changes"
],
"forbidden": [
"deleting existing tests",
"hard-coded fixture-specific output"
]
}
Evaluadores: utilice el más potente disponible
Para los evaluadores, utilicen la etapa más avanzada y definan las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Prefieran unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Incluyan la aprobación humana en aquellas tareas que implican gastos o modificaciones en datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
Métricas importantes
En la fase de “Métricas que importan”, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Trate esta fase como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Incluya la aprobación humana en aquellos casos que impliquen gastos o cambios en datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial. En la fase de “Métricas que importan”, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema.
Creación de un buen conjunto de datos
Al trabajar en la fase de creación de un buen conjunto de datos, primero escribe el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documenta tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no de mejoras posteriores. Haz un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior.
Un bucle práctico
Al trabajar en la etapa de bucle práctico, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Haga una verificación después de los pasos costosos. El sistema de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Errores comunes
Al trabajar en la etapa de errores comunes, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Considere esta etapa como un contrato entre los datos de entrada y las salidas validadas. Asigne nombres a los artefactos, defina comprobaciones de éxito y evite completaciones parciales silenciosas. Haga puntos de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior. Al trabajar en la etapa de errores comunes, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo.
Métricas de enrutamiento, puestas en práctica
Las métricas de enrutamiento funcionan mejor cuando se tratan como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Mantenga el estado de los gráficos simple y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación después de las interrupciones.
El mejor punto de partida
El mejor lugar para desarrollar proyectos funciona de manera óptima cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe apuntar a una sola responsabilidad y no a un proceso complicado. Mantenga el estado de los gráficos simple y tipado adecuadamente; los bloques anidados ocultan qué nodo escribió qué campo y causan problemas al reanudar después de interrupciones.
Un marco de evaluación real y mínimo que puede copiar
La etapa de evaluación realmente mínima funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace completaciones parciales silenciosas. Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso. La etapa de evaluación realmente mínima funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo.
evals/
cases/
skills/security-review.trigger.json
agents/fix-null-condition.json
graders.py
metrics.py
runner.py
run.py # CLI entry1. Case files. A skill trigger case is just positives and negatives. An agent case is a prompt plus graders and a run count.
// cases/skills/security-review.trigger.json
{
"skill": "security-review",
"positives": [
"Audit this endpoint for SQL injection",
"Check the login flow for auth bypasses",
"Is this file-upload handler safe?"
],
"negatives": [
"Upgrade React dependencies",
"Rename this variable across the repo",
"Add a loading spinner to the form"
]
}
// cases/agents/fix-null-condition.json
{
"id": "fix-null-condition",
"prompt": "Fix saving rules with a null condition",
"fixture": "fixtures/null-condition",
"setup": ["npm ci"],
"runs": 5,
"graders": [
{ "type": "shell", "cmd": "npm test -- null-condition", "critical": true },
{ "type": "shell", "cmd": "git diff --check" },
{ "type": "forbidden", "pattern": "it\\.skip|xit\\(", "message": "must not disable tests" }
]
}
# graders.py
import re, subprocess
def shell(step, ctx):
r = subprocess.run(step["cmd"], cwd=ctx.workdir, shell=True,
capture_output=True, text=True)
ok = r.returncode == 0
return {"pass": ok, "score": 1 if ok else 0, "detail": r.stdout[-400:]}
def forbidden(step, ctx):
bad = re.search(step["pattern"], ctx.diff) is not None
return {"pass": not bad, "score": 0 if bad else 1,
"detail": step["message"] if bad else ""}
def judge(step, ctx):
v = ctx.llm.rate(step["rubric"], ctx.artifact) # 0..1, blinded
return {"pass": v >= step.get("threshold", 0.7), "score": v}
GRADERS = {"shell": shell, "forbidden": forbidden, "judge": judge}3. Metrics. Success rate, pass@k, pass^k, and the routing confusion matrix — exactly the numbers from earlier.
# metrics.py
def success_rate(rs):
return sum(1 for r in rs if r["pass"]) / len(rs)
def pass_at_k(rs):
return 1 if any(r["pass"] for r in rs) else 0
def pass_hat_k(rs):
return 1 if all(r["pass"] for r in rs) else 0
def routing(positives, negatives, fired):
tp = sum(1 for p in positives if fired(p))
fp = sum(1 for n in negatives if fired(n))
fn = len(positives) - tp
tn = len(negatives) - fp
return {"tp": tp, "fp": fp, "fn": fn, "tn": tn,
"precision": tp / (tp + fp or 1),
"recall": tp / (tp + fn or 1)}4. The runner. One function per suite. The agent runner repeats each case so pass^k is meaningful; the skill runner just asks the router which skills fire.
# runner.py
import json
from graders import GRADERS
from metrics import success_rate, pass_at_k, pass_hat_k, routing
def run_agent_case(agent, path):
c = json.load(open(path))
runs = []
for _ in range(c.get("runs", 3)):
ctx = agent.run(c["prompt"], fixture=c["fixture"], setup=c["setup"])
ok = True
for step in c["graders"]:
g = GRADERS[step["type"]](step, ctx)
if step.get("critical") and not g["pass"]:
ok = False
runs.append({"pass": ok})
return {"id": c["id"], "success": success_rate(runs),
"pass_at_k": pass_at_k(runs), "pass_hat_k": pass_hat_k(runs)}
def run_skill_trigger(router, path):
c = json.load(open(path))
fired = lambda prompt: c["skill"] in router.route(prompt)
return {"skill": c["skill"], **routing(c["positives"], c["negatives"], fired)}5. Run it. The CLI just dispatches on the case type and prints the metrics.
$ python run.py cases/agents/fix-null-condition.json
fix-null-condition success=0.80 pass@5=1.00 pass^5=0.20
$ python run.py cases/skills/security-review.trigger.json
security-review precision=0.86 recall=1.00 (tp=6 fp=1 fn=0 tn=5)
No construya desde cero si no es necesario
En lugar de crear algo desde cero, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las intentonas, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Asegúrese de que haya aprobación humana en aquellos casos en los que se gastan fondos o se modifican datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial.
Evaluaciones generales de LLM y prompts
En la fase de evaluación de prompts generales para LLM, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Prefiera salidas estructuradas con validación de esquema en lugar de texto libre cuando el paso siguiente sea código o una llamada a una herramienta.
Rastreo, conjuntos de datos y plataformas con LLM como juez
En la etapa de las plataformas LLM-as-judge para los conjuntos de datos de rastreo, se deben definir las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Prefiera resultados estructurados con validación de esquema sobre texto en formato libre cuando el siguiente paso sea código o una llamada a una herramienta. En la etapa de las plataformas LLM-as-judge para los conjuntos de datos de rastreo, se deben definir las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar que los operadores puedan auditar sin tener que leer todo el contenido.
todo el gráfico.Arneses y pruebas de rendimiento específicos para el agente
Al trabajar en la fase de pruebas con arneses específicos para el agente, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar bucles de agente sin ese registro desperdicia horas.
Cómo elegir
Al trabajar en la etapa de “Cómo elegir”, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiera unidades pequeñas y verificables a scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Haga una verificación después de los pasos costosos. El sistema de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Lista de verificación operativa
En la etapa de la lista de verificación operativa, defina los datos de entrada, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de verificación conocido sin tener que adivinar el estado oculto.
Registre los tiempos de ejecución y el costo de tokens o consultas junto con los resultados funcionales. Ver la información sobre costos desde el principio evita facturas inesperadas cuando se pasa de entornos de demostración a entornos compartidos.
Coloque la aprobación humana en aquellos puntos donde se gastan fondos o se modifican datos de producción. La configuración en tiempo de compilación no equivale a una solución completa para el negocio.
Supervise los costos y la latencia junto con la calidad. Una respuesta ligeramente peor que cueste 10 veces menos podría ser la mejor opción para producción.
Fije las versiones de dependencias y registre el resumen de la imagen que ejecutó la demostración. La reproducibilidad es mejor que el conocimiento basado en prácticas internas.
Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando falla un paso, el error debe apuntar a una única responsabilidad y no a un proceso complicado.
Antes de promocionar el stack, congele las versiones, capture una transcripción de referencia para la ruta crítica y confirme los pasos de reversión. Los entornos compartidos requieren límites de velocidad, verificaciones de tenencia y un responsable claro para la rotación de secretos. Prefiera una fiabilidad sencilla a demostraciones ingeniosas pero puntuales.
Nota por lotes para ce69f1512f25: mantenga las claves del proveedor fuera del repositorio, establezca un límite para tokens por sesión y almacene las transcripciones junto a los fixtures de evaluación para que los cambios posteriores en el modelo sigan siendo comparables.
Lecturas relacionadas
- Notas prácticas: Desarrollo con Eval: Un enfoque de ingeniería de software — Guía detallada de Notas prácticas: Desarrollo con Eval: Un enfoque de ingeniería de software: contratos, verificaciones y espacios para código reutilizable para equipos que implementan este patrón.