Lo que cambia cuando un agente pasa del demo a producción

He construido sistemas multi-agente con roles, reglas y flujos de ejecución definidos desde 2023, y he integrado pagos en apps con transacciones reales. La distancia entre esas dos cosas es la que casi nadie mide: un agente que acierta el 95% de las veces es un demo espectacular y un producto inaceptable si el 5% restante toca dinero.

El demo miente por construcción

Un demo se ejecuta una vez, con el input que elegiste, mirando la pantalla. Producción es lo contrario en las cuatro dimensiones: inputs que no anticipaste, miles de ejecuciones, nadie mirando, y consecuencias que persisten. Ninguna de esas cuatro se arregla con un mejor prompt.

Roles, reglas y flujos explícitos

El patrón que me ha funcionado no es «un agente inteligente», es varios agentes tontos con contratos claros. Cada uno tiene un rol estrecho, reglas que no puede violar, y un flujo donde su salida es la entrada verificable del siguiente. Cuando algo falla, sabes qué eslabón falló, porque cada eslabón tiene una sola responsabilidad.

// El contrato importa más que el prompt: define qué puede tocar el agente,
// qué debe devolver, y qué hace el sistema cuando no cumple.
type AgentContract<Input, Output> = {
  role: string;                      // una sola responsabilidad
  tools: ReadonlyArray<ToolName>;    // superficie mínima, no "todas"
  validate: (raw: unknown) => Output; // el schema es el guardia, no la fe
  onInvalid: "retry" | "escalate" | "fail";
  budget: { maxTokens: number; maxRetries: number };
};

Ese validate es la pieza que separa un sistema de un juguete. Si la salida del modelo entra a tu base de datos sin pasar por un schema, no tienes un agente: tienes una inyección de datos con pasos extra.

Context engineering es la mitad del trabajo

Se habla de prompt engineering y se ignora lo que de verdad mueve la aguja: qué información ve el agente, en qué orden y con qué recencia. La mayoría de errores que he depurado no fueron de razonamiento, fueron de contexto — el agente decidió bien con información incompleta, obsoleta o contradictoria.

• Contexto mínimo suficiente: cada token irrelevante es ruido que compite con la instrucción.
• Recencia explícita: si el dato tiene fecha, dísela. Un agente no sabe que tu precio cambió ayer.
• Fuente única: dos versiones del mismo dato en el contexto es un bug garantizado, no un riesgo.
• Estado fuera del prompt: lo que debe persistir va a una base de datos, no a la ventana de contexto.

Evals, o no hay producto

Sin evaluación automatizada no puedes cambiar nada: cada ajuste de prompt es una apuesta y cada modelo nuevo es una migración a ciegas. No necesitas un framework: necesitas un set de casos con salida esperada que corra en CI y falle el build cuando la calidad baja.

Costo y latencia son requisitos, no métricas

Un agente que resuelve el caso en 40 segundos y 12 llamadas al modelo puede ser correcto y aun así inviable. Trátalos como requisitos de producto desde el diseño: presupuesto de tokens por operación, techo de latencia, y una ruta degradada para cuando el presupuesto se agota. La ruta degradada suele ser lo más valioso del sistema.

Dónde poner al humano

«Human in the loop» sin criterio es una casilla de confirmación que nadie lee. La pregunta útil es más estrecha: qué acciones son irreversibles. Ahí va el humano, y solo ahí. Todo lo reversible que necesite aprobación es fricción disfrazada de seguridad.

1. 01Reversible y de bajo impacto: el agente actúa y registra.
2. 02Reversible y de alto impacto: el agente actúa y notifica, con un deshacer real.
3. 03Irreversible: el agente propone, el humano confirma. Sin excepciones.

El checklist que uso antes de decir que está listo

• Cada agente tiene un rol, un schema de salida y un presupuesto.
• Existe un set de evals que corre en CI con casos cosechados de fallos reales.
• Hay un techo de costo y latencia por operación, con ruta degradada.
• Las acciones irreversibles pasan por confirmación humana.
• Cada ejecución deja traza: input, contexto, salida, herramientas usadas, costo.
• Sé qué hace el sistema cuando el proveedor del modelo se cae.

Ese último punto es el que más veces he visto ignorado. Un producto cuya única ruta pasa por una API de terceros hereda su disponibilidad. Si eso es aceptable, escríbelo y decide; si no, necesitas un plan B antes de lanzar, no después de la primera caída.