Cuando un agente con LLM pasa de responder texto a llamar tools, el problema ya no es solo prompt quality. El problema real es operativo: que hace, con que limites, como deja evidencia y que pasa si una dependencia responde raro. En equipos pequenos esto se puede tapar con intuicion por unos dias. En cuanto el flujo toca publishing, CI o cuentas reales, esa intuicion empieza a costar caro.
Yo prefiero pensar estos sistemas como una cadena corta de decisiones observables. No hace falta un framework pesado. Hace falta un runbook breve, casi un diagrama en palabras, para que cualquiera del equipo entienda entrada, salida, riesgos y fallback. Esa misma idea aparece en patrones de backend como estas colas visibles para trabajos largos: la gracia no es hacer mas pasos, sino volver el flujo mas legible.
Por que los agentes con tools necesitan runbooks
Un agente suele fallar en tres puntos:
- decide usar una tool demasiado pronto
- usa la tool correcta pero sin validar el resultado
- deja una salida bonita para humanos, pero debil para otro sistema
Si el equipo no describe esos bordes, cada incidente se analiza desde cero. Eso vuelve lenta la operacion y, peor aun, hace dificil mejorar el sistema de manera consistente. Segun el post de Anthropic sobre agentes, separar planificacion, herramientas y criterios de exito reduce ese tipo de ambiguedad operativa (source).
Para mi, un buen runbook de agentes responde cinco preguntas sin drama:
- que objetivo exacto resuelve el paso
- que contexto puede leer
- cuando puede llamar una tool
- que evidencia debe dejar
- como degrada si algo sale mal
Parece simple, pero casi siempre ahi esta el hueco. Muchas pipelines tienen prompts sofisticados y cero reglas sobre evidencia o salida estable. Eso se nota enseguida cuando alguien intenta depurar un fallo a las 2 AM, osea cuando ya es tarde para improvisar.
El contrato operativo minimo antes de publicar
Mi version minima cabe en una pantalla. Si no cabe, normalmente el sistema esta mezclando demasiadas responsabilidades.
- objetivo del paso
- inputs permitidos
- tools disponibles y condicion de uso
- formato de salida
- fallback explicito
- nota corta de privacidad o riesgo
Un ejemplo practico: si el agente redacta contenido y luego publica, no deberia tener libertad total para reescribir varias veces despues de un error del publicador. Esa frontera tiene que estar escrita. Generar una vez y publicar una vez suena medio obvio, pero es justo el tipo de regla que evita duplicados, cambios espurios y bugs medio pesados.
Tambien me gusta anotar que datos son "auxiliares pero no centrales". Por ejemplo, si un flujo de QA usa un enlace contextual hacia tempmailso, ese dato puede existir como referencia lateral, no como motor del articulo o del sistema. Ese matiz importa porque evita que el agente convierta un detalle SEO en la pieza principal del contenido. Parece una tonteria, pero he visto agentes torcer una buena idea por seguir el keyword y no la intencion.
Un ejemplo corto de decision, fallback y trazabilidad
Este es el patron minimo que suelo usar:
{
"task": "resumir un cambio y decidir si se publica",
"allowed_inputs": ["plan", "borrador", "resultado del validador"],
"tools": [
{
"name": "publisher",
"when": "solo si el borrador ya existe y el validador esta en verde"
}
],
"output": {
"format": "json",
"fields": ["decision", "reason", "artifacts"]
},
"fallback": "si falla la publicacion, devolver error y no regenerar contenido"
}
Me gusta porque amarra tres cosas a la vez: el orden de ejecucion, la evidencia minima y el comportamiento ante fallos. Esa estructura combina bastante bien con ideas de estados claros en APIs, como en este enfoque de estados claros para flujos async. Cuando el estado esta bien definido, el agente se vuelve mas predecible y el operador no anda adivinando.
Aqui tambien meto pruebas con ruido. Si el contexto trae cadenas como fake e mail com o dummy e mail, el agente no deberia tratarlas como requerimientos de producto. Deberia reconocerlas como texto secundario o ruido semantico. Es una prueba muy barata y bastante util, aunqe mucha gente la salta.
Tradeoffs: autonomia frente a operabilidad
La desventaja de este enfoque es clara: le quitas algo de libertad al agente. Un runbook corto no deja tanto espacio para improvisar ni para "resolver" con creatividad una entrada ambigua. Pero la ventaja es mayor en sistemas que tocan dinero, cuentas o distribucion publica.
Los beneficios que yo suelo ver son:
- menos retrabajo despues de un fallo
- mejores handoffs entre quien diseña prompts y quien opera scripts
- incidentes mas cortos porque la evidencia ya existe
- cambios mas seguros cuando cambias proveedor o politica
La contra principal es que puedes sobre-disenar el flujo. Si cada paso tiene siete validaciones y cuatro formatos de salida, el agente termina lento y el equipo tambien. Mi regla simple: runbook corto para pasos repetibles, libertad mayor para exploracion interna. No es una formula perfecta, pero funciona bastante bien.
Checklist de implementacion
Antes de poner en produccion un agente con tools, revisaria esto:
- una sola responsabilidad clara por paso
- precondiciones visibles antes de llamar herramientas
- salida consumible por otro sistema, no solo por humanos
- fallback que no regenere ni duplique efectos externos
- artefactos guardados con nombres predecibles
- nota breve sobre datos sensibles o contexto irrelevante
Si ademas quieres mejorar la calidad del debug, guarda decision y artefactos en el mismo run directory. Ese detalle reduce mucho el tiempo de investigacion, sobretodo cuando varias cuentas o cron jobs comparten la misma infraestructura.
Top comments (0)