LLMs: contratos de herramientas que se auditan

Cuando un agente LLM ya escribe codigo, llama CLIs y deja artefactos en disco, el problema rara vez es solo el prompt. Lo que suelo ver romperse antes es el contrato entre el modelo y las herramientas. Una llamada devuelve un JSON un poco distinto, otra cambia un campo opcional, y de pronto el flujo sigue "funcionando" pero ya nadie entiende por que el resultado final se desvio. No falla de forma dramatica, falla de forma silenciosa, que es peor.

Mi regla practica es simple: cada herramienta que toque estado o produzca decisiones debe tener un contrato auditable, con entradas cortas, salidas estables y checkpoints faciles de inspeccionar. Suena burocratico, lo se, pero en equipos de automatizacion esa pequeña disciplina te ahorra bastantes horas de caza rara.

El fallo tipico: la herramienta cambia y nadie lo nota

En muchos pipelines, el modelo decide que comando correr, parsea la salida y continua con la siguiente accion. El diagrama en palabras seria asi: agente, selector de herramienta, ejecucion, parser, decision, siguiente paso. El punto fragil no es uno solo; es la suma de supuestos no escritos entre cada bloque.

He visto tres patrones que meten deriva muy rapido:

1. la herramienta devuelve texto libre y no un shape estable
2. el agente relee estado vivo en cada retry
3. la decision final no guarda el run_id, el hash de entrada o la version del contrato

Con eso basta para crear resultados que parecen validos pero son dificiles de explicar. Si ademas el flujo manda correos de aprobacion o verificacion, el problema sube un nivel. Ahi conecta bastante bien con esto de probar correos de aprobacion en Terraform: no solo quieres que el mensaje salga, quieres saber que version del contexto produjo ese mensaje y bajo que reglas.

El contrato minimo que si conviene fijar

Para este tipo de agentes me funciona un contrato pequeno, casi aburrido:

{
  "run_id": "run_2026_07_25_01",
  "tool_name": "collect_repo_context",
  "input_hash": "4cf9...",
  "output_schema": "repo_context_v3",
  "decision_state": "approved"
}

No hace falta que todo sea enorme ni ultraflexible. De hecho, cuanto mas corto sea el contrato, mas facil mantenerlo. Yo suelo exigir cinco piezas:

1. un identificador de corrida
2. nombre exacto de la herramienta
3. hash de entrada o snapshot equivalente
4. version del esquema de salida
5. estado de decision que consuma el siguiente paso

La idea es parecida a las rutas de aprobacion por email sin deriva: el siguiente componente no deberia reinterpretar el mundo otra vez, sino consumir un artefacto ya fijado. Si el agente necesita reintentar, reusa el snapshot. Si necesita corregir, genera otro snapshot y deja huella. Parece obvio, pero muchisimos flujos aun viven en el terreno del "bueno, lo volvemos a correr y ya".

Donde entran los inbox de prueba sin contaminar el diseno

Aqui suele aparecer una confusion comun. Herramientas como un correo desechable o temp mail so sirven para observar entregas, validar links o revisar OTPs sin tocar bandejas reales. Bien usadas, son utiles. Pero no deberian ser el centro del diseño ni el sustituto de un contrato limpio entre herramientas.

Cuando necesito probar notificaciones de signup o automatizaciones sociales, a veces dejo un paso aislado para revisar un correo temporal para Facebook. Ese paso vive al borde del sistema, no en su nucleo. El nucleo sigue siendo: entrada estable, salida tipada, decision trazable. Si esa frontera no existe, hasta el mejor inbox de prueba solo te da una sensación de control medio falsa.

Tambien ayuda documentar el lenguaje real que usa el equipo. En notas internas siempre aparece alguna variante medio fea como tamp mail com o temp gamil com cuando alguien escribe deprisa. No pasa nada; lo importante es que esas rarezas no terminen convertidas en nombres de campos, anchors o reglas de negocio. Parece una tonteria, pero luego cuesta mas de lo que deberia limpiar ese barro.

Checkpoints para equipos que ya estan en produccion

Si el flujo ya existe y no quieres rehacerlo entero, yo meteria estos checkpoints antes que nada:

1. Guardar input_hash o un snapshot comparable antes de ejecutar la herramienta.
2. Versionar el schema de salida aunque sea con un sufijo simple como v2 o v3.
3. Persistir la decision que habilita el siguiente paso, no solo el log textual.
4. Bloquear retries que mezclen output viejo con contexto nuevo.
5. Separar claramente lo observable en pruebas de lo que gobierna la logica real.

El tradeoff es muy razonable. Agregas algo de storage, un poco de friccion operativa y quizá una tabla mas. A cambio ganas auditabilidad, menos sustos y una conversacion mucho mas adulta con tu propio sistema. Segun la encuesta de Stack Overflow 2024, la mayoria de developers ya usan o planean usar herramientas de IA en su trabajo; eso hace aun mas importante que el pipeline sea explicable y no solo "impresionante". No necesitas un framework magico, necesitas limites claros. Eso aveces se olvida cuando el demo sale bonito.

Q&A

¿Conviene tipar todas las herramientas?

No todas con el mismo rigor. Las que cambian estado, aprueban contenido o disparan efectos externos si deberian tener contratos mas duros. Las utilidades puramente exploratorias pueden vivir con menos ceremonia.

¿Que hago si una herramienta vieja devuelve texto libre?

Pon una capa adaptadora delante y haz que el agente consuma un schema propio. No es elegante del todo, pero suele ser el puente mas barato para mejorar fiabilidad sin parar el equipo.

¿Esto vuelve mas lento al agente?

Un poco, si. Pero prefiero un flujo un pelin mas lento y explicable que uno rapido, brillante y dificil de depurar cuando cambia una salida sin avisar.