Arquitectura de un agente
Un agente se arma con dos partes: un modelo que decide qué hacer y un harness que lo hace. El harness es todo lo que no es el modelo.
El modelo solo lee y escribe texto; nunca ejecuta nada por su cuenta. El harness le envía el contexto, ejecuta cada acción que el modelo pide y le devuelve el resultado, hasta que el modelo responde sin pedir nada más.
Arma el envío: las instrucciones, la lista de herramientas y la pregunta.
Las dos partes
Agente = Modelo + Harness.
| Parte | Qué aporta | Ejemplos |
|---|---|---|
| Modelo | Razona y decide el siguiente paso | Claude, GPT, Gemini |
| Harness | El ciclo, las herramientas, el contexto, los límites y la configuración | Claude Code, Kiro, Cursor, OpenCode |
Un mismo modelo se comporta distinto en cada producto, porque cambian las herramientas, los límites y las instrucciones que lo rodean.
Dentro del harness, la configuración es lo que se ajusta sin tocar el programa: CLAUDE.md en Claude Code o los steering files en Kiro. Gentle AI es una herramienta que escribe esa configuración en agentes ya instalados.
El término «harness» todavía no tiene una definición única: cada autor traza el borde en un lugar distinto. En otros textos aparece como «el sistema» o scaffold.
Las piezas del harness
| Pieza | En inglés | Qué es | En el ejemplo |
|---|---|---|---|
| Instrucciones | system prompt | El texto fijo con las reglas. Aquí entra la configuración. | «Eres un asistente útil» |
| Herramientas | tools | Lo que el agente puede hacer: nombre, descripción, parámetros y la función real | get_weather(city) |
| Contexto | context | El historial de mensajes. El modelo no tiene memoria: se le reenvía completo en cada vuelta. | Pregunta, pedido y resultado |
| Ciclo | agent loop | Llamar al modelo, ejecutar lo que pide y repetir | Dos vueltas |
| Límites | permissions, guardrails | Los permisos y el tope de vueltas | La verificación del paso 3 |
Otros términos que aparecen en inglés: una vuelta es un turn, el pedido de una herramienta es un tool call y su resultado es un tool result.
Las cuatro primeras están en cualquier agente, incluso en el más pequeño. Los límites los agregan los productos reales, y son los «límites establecidos» de la definición del concepto anterior.
Cuándo se detiene el ciclo
El ciclo se detiene por dos motivos:
- Objetivo cumplido: el modelo responde sin pedir herramientas.
- Tope de vueltas (max turns): el harness corta aunque el modelo no haya terminado.
El tope existe por costo. Cada vuelta es un pedido que se paga, y sin tope un agente que no encuentra la solución sigue dando vueltas. Algunos harness suman un tope de gasto en dinero.
Al llegar al tope, el harness decide qué hacer: devolver un error, como en el esqueleto de abajo, o pasar el caso a una persona.
El mismo patrón aparece en herramientas low-code. En n8n, el nodo AI Agent se arma conectándole un modelo, herramientas y, de forma opcional, memoria; su opción «Max Iterations» vale 10 por defecto.
El esqueleto
Un agente completo cabe en una pantalla. call_model es la única línea que habla con el modelo; el resto es código común.
SYSTEM = "Eres un asistente útil." # instrucciones
TOOLS = { # herramientas
"get_weather": {
"description": "Devuelve el clima actual de una ciudad",
"params": {"city": "string"},
"run": get_weather, # la función real
},
}
MAX_TURNS = 20 # límite: tope de vueltas
def agent(user_request):
messages = [user_message(user_request)] # contexto
for _ in range(MAX_TURNS): # ciclo
reply = call_model(SYSTEM, TOOLS, messages) # el modelo decide
messages.append(reply)
if reply.stop_reason != "tool_use": # no pidió herramientas
return reply.text # fin del ciclo
results = [run_tool(call) for call in reply.tool_calls]
messages.append(user_message(results)) # todos los resultados juntos
raise MaxTurnsExceeded() # tope alcanzado: error o derivar a una persona
def run_tool(call):
if not is_allowed(call): # límite: permisos
return tool_error(call, "Permiso denegado")
try:
output = TOOLS[call.name]["run"](**call.args)
return tool_result(call, output)
except Exception as error: # un error también es un resultado
return tool_error(call, str(error))Tres detalles que suelen fallar al escribirlo por primera vez:
- Cada pedido recibe su resultado. Los resultados de una misma vuelta vuelven juntos, en un solo mensaje.
- Un error también es un resultado. Una herramienta que falla o un permiso denegado se devuelven al modelo, que los lee y prueba otro camino.
- El modelo avisa por qué se detuvo. Aquí solo se distingue «pidió una herramienta» del resto. Un harness real también trata los otros motivos, como una respuesta cortada por longitud o un rechazo.