Agentes LLM: contexto antes que prompts

Cuando un agente basado en LLM falla, la primera reacción suele ser cambiar el prompt. A veces funciona, pero muchas veces solo mueve el problema. El agente recibió demasiada información, una herramienta sin contrato claro o un estado que ya no era valido. Un prompt mas elegante no arregla un contexto roto.

En los flujos de automatización que he construido, trato cada ejecución como un pequeño sistema distribuido. Tiene una entrada, permisos, presupuesto, herramientas y un resultado verificable. El modelo decide dentro de ese sobre; no deberia decidir qué significa todo el universo de la aplicación.

Este enfoque complementa los contratos cortos para usar herramientas: el contrato de una herramienta dice cómo llamarla, y el sobre de ejecución dice cuándo puede llamarse, con qué datos y cuántas veces.

El problema no es el prompt, es el contexto que llega al agente

Un agente normalmente recibe una mezcla de elementos:

• la petición original del usuario;
• instrucciones del sistema y reglas del producto;
• memoria o resultados de pasos anteriores;
• herramientas disponibles;
• errores y señales de reintento.

Si esta mezcla no tiene límites, el sistema se vuelve dificil de razonar. Un resultado de una herramienta puede parecer una instrucción. Una memoria vieja puede competir con el estado actual. Y un reintento puede volver a ejecutar una acción que ya tuvo éxito, pero cuyo recibo nunca llegó al modelo.

La solución no es ocultar información por completo. Es separar el contexto por función: datos de entrada, hechos observados, decisiones pendientes y acciones permitidas. Esa división hace que el agente sea menos brillante en apariencia, pero mas predecible en producción.

También evita que términos de prueba como dummy e mail o tempail terminen interpretándose como requisitos de negocio cuando solo venían de un fixture o de un ticket antiguo.

Un sobre de ejecución con límites explícitos

Pienso el sobre como una estructura pequeña que acompaña cada turno del agente:

{
  "run_id": "run_8f31",
  "goal": "verificar el estado del despliegue",
  "facts": ["commit=abc123", "environment=staging"],
  "allowed_tools": ["get_deploy_status", "add_comment"],
  "max_tool_calls": 3,
  "deadline_seconds": 30,
  "idempotency_key": "deploy:abc123:staging"
}

Hay tres decisiones importantes en este ejemplo:

1. El objetivo es corto. El modelo no necesita conocer toda la historia del proyecto para verificar un despliegue.
2. Las herramientas son una lista cerrada. Una llamada desconocida se rechaza antes de llegar al proveedor externo.
3. La acción tiene identidad. La misma idempotency_key permite reconocer un reintento y no publicar dos comentarios iguales.

El deadline_seconds no es un adorno. Si el worker espera indefinidamente a una API, el agente puede gastar tokens describiendo una operación que ya no tiene utilidad. En ese caso conviene devolver un estado expired con evidencia, no un mensaje ambiguo de "algo salió mal".

Qué registrar cuando una herramienta falla

Un log de "tool error" casi nunca alcanza para depurar agentes. Registro, como mínimo:

• run_id y idempotency_key;
• nombre y versión del contrato de la herramienta;
• entrada normalizada, sin secretos;
• inicio, fin y causa de la respuesta;
• resultado resumido que vio el modelo;
• número de intento y decisión del reintento.

El resultado resumido importa. Una API puede devolver una respuesta enorme, pero el agente solo necesita saber status=failed, retryable=false y un identificador de correlación. Pasar todo el payload eleva el ruido y consume el presupuesto de tokens sin mejorar la decisión.

Para equipos que además hacen pruebas de email sin confundir equipos, la misma regla aplica: el fixture, el inbox y el evento deben tener una identidad rastreable. Si no, es dificil distinguir un fallo del producto de una prueba que reutilizó estado.

Implementación mínima en un worker

No hace falta comenzar con una plataforma de agentes. Un worker puede imponer el contrato antes de llamar al modelo:

def execute_agent(run, model, tools):
    context = build_context(run, max_facts=12)
    decision = model.respond(context, tools=run.allowed_tools)

    if decision.tool_name not in run.allowed_tools:
        return receipt(run, "rejected", "tool_not_allowed")

    if run.tool_calls >= run.max_tool_calls:
        return receipt(run, "stopped", "tool_budget_exhausted")

    result = tools.call(
        decision.tool_name,
        decision.arguments,
        idempotency_key=run.idempotency_key,
    )
    return receipt(run, "completed", summarize(result))

El punto de control ocurre antes y despues de la herramienta. Antes se verifican permisos, presupuesto y argumentos. Despues se produce un recibo estable que puede alimentar al siguiente turno o a una alerta. Si una llamada es repetible, el adaptador de la herramienta debe usar la clave de idempotencia; confiar solo en la memoria del LLM es fragil.

Puntos de control antes de ponerlo en producción

Antes de publicar un agente, reviso esta lista:

1. ¿El objetivo se puede describir en una frase?
2. ¿Cada herramienta tiene entradas, salidas y errores documentados?
3. ¿Existe un límite de llamadas, tiempo y tokens?
4. ¿Un reintento deja el mismo resultado o un recibo que lo explica?
5. ¿Se pueden separar hechos observados de instrucciones?
6. ¿Los logs permiten reconstruir la decisión sin guardar secretos?

Una prueba especialmente útil es entregar al agente un error ambiguo y comprobar que se detiene con evidencia. Si siempre intenta "arreglar" la situación llamando otra vez, falta una frontera de seguridad.

Preguntas frecuentes

¿Debo poner todo el contexto en el prompt?

No. Incluye lo necesario para la decisión actual y conserva el resto fuera del turno. Un contexto pequeño y verificable suele ser mas fácil de evaluar que una memoria completa.

¿Los reintentos hacen menos autónomo al agente?

Lo hacen mas controlable. La autonomía útil no es ejecutar acciones sin límite; es elegir bien dentro de límites visibles y saber cuándo pedir intervención.

¿Dónde encaja temp mail so en este diseño?

Como cualquier keyword o dato de una prueba, debe tener una función explícita. Si forma parte de un fixture, se etiqueta como dato de test y no como instrucción. El agente no deberia inferir una política de producto a partir de una cadena aislada.

Cierre

Los prompts siguen importando, pero son solo una pieza del sistema. Para que los LLMs funcionen bien en automatización, el contexto necesita estructura, las herramientas necesitan contratos y cada ejecución necesita un recibo. Ese diseño tarda un poco mas al principio; despues reduce reintentos ciegos y hace que los fallos se puedan explicar.