AgentesConcepto 02 de 04

Arquitectura de un agente

5 min de lectura Ver en la órbita

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.

objetivocontextopide acciónejecutaresultadorespuestarespuestaUsuarioHarnessModeloHerramienta
GUÍA

Arma el envío: las instrucciones, la lista de herramientas y la pregunta.

1/6

Las dos partes

Agente = Modelo + Harness.

ParteQué aportaEjemplos
ModeloRazona y decide el siguiente pasoClaude, GPT, Gemini
HarnessEl ciclo, las herramientas, el contexto, los límites y la configuraciónClaude 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

PiezaEn inglésQué esEn el ejemplo
Instruccionessystem promptEl texto fijo con las reglas. Aquí entra la configuración.«Eres un asistente útil»
HerramientastoolsLo que el agente puede hacer: nombre, descripción, parámetros y la función realget_weather(city)
ContextocontextEl historial de mensajes. El modelo no tiene memoria: se le reenvía completo en cada vuelta.Pregunta, pedido y resultado
Cicloagent loopLlamar al modelo, ejecutar lo que pide y repetirDos vueltas
Límitespermissions, guardrailsLos permisos y el tope de vueltasLa 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.