Qué es un agente, de verdad: modelo + harness

La primera vez que construí un "agente" era un prompt de 800 palabras con instrucciones numeradas. Funcionó sorprendentemente bien durante dos semanas. Después empezó a fallar: olvidaba pasos, repetía acciones, se inventaba resultados. Pasé días reescribiendo el prompt antes de entender el problema. Lo que faltaba no estaba en el prompt.

Lo que faltaba era todo lo demás: el loop, las tools, el estado, los permisos, la forma de saber si había funcionado. Eso tiene nombre: harness. Y entenderlo es la diferencia entre hacer demos y construir sistemas.

La definición corta

Un agente es un modelo que usa tools en un loop hasta cumplir un objetivo. Nada más y nada menos.

"Agents are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks. They are typically just LLMs using tools based on environmental feedback in a loop." - Source: Building effective agents - Anthropic

Esa frase contiene los tres ingredientes y ninguno sobra:

Modelo: el que decide.
Tools: lo que puede hacer (leer, escribir, consultar, ejecutar).
Loop: la repetición con feedback del entorno y una condición de parada.

Si falta el loop, tienes un chatbot. Si faltan las tools, tienes un generador de texto. Si falta la condición de parada, tienes una factura creciendo.

Workflow vs agente (la distinción que te ahorra dinero)

Antes de escribir un agente, la pregunta correcta no es "¿qué framework uso?" sino "¿esto necesita un agente?". Anthropic separa dos cosas que se mezclan todo el tiempo:

Workflows: el LLM y las tools siguen caminos definidos por tu código. Tú sabes los pasos.
Agentes: el LLM decide sus propios pasos y qué tools usar.

Los workflows son predecibles y baratos; los agentes son flexibles y caros. Para un proceso que ya conoces (extraer datos de una factura, responder según categoría, resumir y traducir), un workflow gana casi siempre. El agente aparece cuando no puedes predecir cuántos pasos hacen falta: arreglar un bug que toca archivos que no conoces, investigar en varias fuentes, operar un flujo abierto.

"Agentic systems often trade latency and cost for better task performance... For many applications, optimizing single LLM calls with retrieval and in-context examples is usually enough." - Source: Building effective agents - Anthropic

El loop, escrito sin frameworks

Esto es un agente funcional. No hay magia escondida en una librería:

// agent-loop.ts
// El corazón de cualquier agente: decidir -> ejecutar -> observar -> repetir.
const MAX_STEPS = 12;

async function runAgent(task: string, tools: Tool[]) {
  const messages = [{ role: "user", content: task }];

  for (let step = 0; step < MAX_STEPS; step++) {
    const res = await model.chat({
      messages,
      tools: tools.map(toSchema), // el modelo decide, no ejecuta
    });

    messages.push(res.message); // lo que decidió

    const call = res.message.toolCall;
    if (!call) return res.message.content; // no pidió tool: terminó

    const result = await execute(tools, call); // aquí ejecuta TU código
    messages.push({ role: "tool", name: call.name, content: result }); // feedback
  }

  return "Máximo de pasos alcanzado sin resolver la tarea";
}

Léelo otra vez. Lo único que hace es: preguntar, ejecutar lo que le pidan, devolver el resultado y repetir hasta que el modelo no pida nada o se acabe el presupuesto. Todas las piezas interesantes están fuera del modelo: el MAX_STEPS, el manejo de errores, el tamaño de messages cuando crece, y qué pasa si una tool falla.

El harness: donde vive el 80% del trabajo

El harness es todo lo que rodea al modelo y lo convierte en agente. Si el modelo es el motor, el harness es el coche: chasis, frenos, dirección, tablero.

Las piezas que vas a tocar de verdad:

Diseño de tools: nombres, parámetros, errores. Anthropic gastó más tiempo optimizando tools que el prompt en su agente para SWE-bench: hicieron obligatorio el uso de rutas absolutas porque el modelo se equivocaba con las relativas.
Contexto: qué ve el modelo en cada paso, y qué se recorta cuando la ventana se llena. → Context engineering práctico
Estado: qué persiste entre pasos y entre sesiones.
Permisos y guardrails: qué puede hacer sin preguntar y qué no. → Guardrails: permisos, sandbox y clasificadores
Evals: cómo sabes si mejoró. → Evals: los 3 tipos
Observabilidad: la traza de cada paso, para saber qué falló cuando falle.

Los frameworks modernos ya traen parte de esto: el ToolLoopAgent del AI SDK maneja el loop, el contexto y las condiciones de parada por ti; ADK gestiona sesiones, memoria y compresión como parte del framework. Te ahorran el boilerplate, pero no te ahorran entenderlo: cuando algo falla, la respuesta está en el harness. Tienes el desglose completo en Harness Engineering: las 9 piezas.

Un chat no es un agente

	Chat	Agente
Pasos	Uno	Muchos, dinámicos
Decide	Tú (qué preguntar)	El modelo (qué hacer)
Actúa	No	Sí, con tools
Termina	Cuando tú paras	Con condición de parada
Falla	Respuesta mala	Acción mala (más caro)
Necesita	Buen prompt	Harness completo

La última fila es la que importa: cuando un agente falla, no solo te da una respuesta mala, hace algo. Por eso los permisos y las evals no son opcionales, y por eso "agente" no debería ser el default.

Cuándo NO construir un agente

Si puedes enumerar los pasos → workflow.
Si una sola llamada con buen contexto resuelve → una llamada.
Si no tienes forma de verificar el resultado → primero la verificación, después la autonomía.
Si no vas a medir el costo ni la latencia → vas a aprender con la factura.

Mi regla: un agente se gana su autonomía cuando el camino no se puede predecir y existen señales para saber si va bien (tests, validaciones, resultados de tools). Si falta cualquiera de las dos, empiezo por lo simple.

Lo que haría esta semana

Escribe el loop a mano una vez, aunque luego uses un framework. Son 20 líneas y te cambia cómo lees la documentación.
Empieza por un workflow y conviértelo en agente solo cuando los caminos fijos se queden cortos.
Diseña las tools como API pública: nombres claros, parámetros imposibles de confundir, errores útiles.
Pon una condición de parada desde el primer día: máximo de pasos y de presupuesto.
Guarda la traza de cada corrida. Sin trazas, depurar un agente es adivinar.

Si quieres el mapa completo de piezas, vocabulario y frameworks para armar todo esto, lo estoy dejando en la guía Agentes: de cero a producción.

¿Ya tienes un agente en producción, o tu "agente" es todavía un workflow con nombre ambicioso? Cuéntame en los comentarios: esa distinción da para mucho.