Arquitectura agéntica: bucles, coordinador, subagentes…

Escenario Multi-Agent Research System. Tu sistema investiga un tema y entrega un informe con citas. Un coordinador reparte el trabajo entre cuatro subagentes: uno busca en la web, otro analiza documentos, otro sintetiza y otro redacta. Lo pruebas con «el impacto de la IA en la cadena de suministro» y el informe sale impecable… pero solo habla de almacenes. Ni una línea sobre compras, transporte o planificación de la demanda.

Cada subagente hizo bien su trabajo. El fallo estaba antes: en cómo el coordinador partió el tema. Este tipo de diagnóstico es el corazón del dominio 1, Agentic Architecture & Orchestration, el que más pesa del examen (27 %, unas 16 preguntas de 60). Vamos por sus siete task statements: el bucle agéntico, el patrón coordinador-subagentes, cómo se lanzan y alimentan los subagentes, el cumplimiento garantizado, los hooks, la descomposición de tareas y las sesiones.

El bucle agéntico: quién decide cuándo parar (1.1)

Todo agente con Claude es, por dentro, el mismo bucle. Recórrelo:

Paso a pasoEl bucle agéntico paso a paso

Tu código llama a la Messages API con el historial de la conversación y la lista de herramientas disponibles.

1 de 5

En código, con el SDK de Python de la API, el esqueleto es este:

while True:
    resp = client.messages.create(
        model="claude-opus-5-5", max_tokens=4096,
        tools=tools, messages=messages,
    )
    messages.append({"role": "assistant", "content": resp.content})
    if resp.stop_reason != "tool_use":   # end_turn (u otro motivo de parada)
        break
    resultados = [
        {"type": "tool_result", "tool_use_id": b.id, "content": ejecutar(b.name, b.input)}
        for b in resp.content if b.type == "tool_use"
    ]
    messages.append({"role": "user", "content": resultados})

Lo que el examen quiere que distingas es decisión guiada por el modelo (Claude elige la siguiente herramienta según lo que ha descubierto) frente a árboles de decisión o secuencias prefijadas. Y quiere que reconozcas tres antipatrones de parada:

Coordinador y subagentes: hub-and-spoke (1.2)

En un sistema multiagente, el patrón que da por bueno la guía es hub-and-spoke: un coordinador en el centro que gestiona toda la comunicación, los errores y el enrutado de información. Los subagentes no hablan entre sí.

EsquemaHub-and-spoke en el sistema de investigación

Pasa por encima o toca un módulo

Todo pasa por el centro: así hay observabilidad, un manejo de errores coherente y control sobre qué información llega a cada subagente.

Responsabilidades del coordinador que salen en el examen:

Descomponer bien. Si parte «cadena de suministro» solo en temas de almacén, la cobertura será incompleta aunque los subagentes sean perfectos. Es el caso del gancho.
Elegir qué subagentes invocar según la complejidad de la consulta, en vez de pasar siempre por todo el pipeline.
Repartir el alcance sin duplicar: subtemas o tipos de fuente distintos para cada subagente.
Refinar en bucle: evaluar la síntesis, detectar huecos, volver a delegar búsquedas concretas y resintetizar hasta que la cobertura sea suficiente.

Lanzar subagentes y pasarles contexto (1.3)

Aquí hay un matiz de nombres que conviene tener claro. La guía del examen habla del Task tool y dice que el coordinador necesita "Task" en allowedTools para poder lanzar subagentes. En la documentación actual de Claude Code y del Agent SDK, esa herramienta se llama Agent: se renombró en la versión 2.1.63 y Task sigue funcionando como alias. Es el mismo mecanismo: si el examen dice Task, piensa en la herramienta con la que el coordinador lanza subagentes.

Lo importante no es el nombre, sino cómo se comporta:

Los subagentes empiezan con un contexto limpio. No heredan la conversación del coordinador ni comparten memoria entre invocaciones. Lo único que les llega del padre es el prompt de la llamada. Si el subagente de síntesis necesita los resultados de búsqueda y el análisis de documentos, tienen que ir completos en su prompt.
Separa contenido y metadatos. Pasa los hallazgos en un formato estructurado (afirmación, fragmento, URL o documento, página, fecha) para que la atribución sobreviva a los traspasos.
Paralelo es en una sola respuesta. Para lanzar subagentes en paralelo, el coordinador emite varias llamadas a la herramienta en la misma respuesta, no una por turno.
Define objetivos, no recetas. El prompt del coordinador funciona mejor si fija metas y criterios de calidad que si dicta pasos: deja margen a los subagentes para adaptarse.

En el Agent SDK, cada tipo de subagente se declara con un AgentDefinition: una descripción (que Claude usa para decidir cuándo delegar), un prompt de sistema propio y, opcionalmente, una lista restringida de herramientas y un modelo.

Pregunta de examen

El subagente de síntesis produce informes sin citas, aunque el de búsqueda sí encontró las URL. En los logs ves que el coordinador le pasa a síntesis un resumen en prosa de lo encontrado. ¿Cuál es la causa más probable?

Garantías: hooks y requisitos previos (1.4 y 1.5)

Cambiamos al escenario Customer Support Resolution Agent. Hay reglas que no pueden fallar nunca: verificar la identidad antes de tocar dinero, no reembolsar por encima de cierto importe sin una persona. La guía es tajante: las instrucciones en el prompt tienen una tasa de fallo distinta de cero. Cuando el cumplimiento tiene que ser determinista, se programa.

Frente a frenteGuiar con el prompt o garantizar con código

Guía en el prompt

probabilística

Instrucciones y ejemplos en el prompt del sistema
Suficiente para estilo, tono y preferencias
Barata y rápida de cambiar
Puede fallar en un porcentaje pequeño de casos

Control programático

determinista

Hooks que interceptan llamadas o resultados, y requisitos previos que bloquean
Necesario para identidad, dinero y cumplimiento
Bloquea `process_refund` hasta que `get_customer` devuelva un cliente verificado
Redirige lo que viola la política, por ejemplo a `escalate_to_human`

Pista de examen: si el enunciado dice «garantizar», «siempre» o hay consecuencias financieras, la respuesta es programática.

En el Agent SDK esto se hace con hooks, funciones que el SDK llama en momentos del ciclo del agente. Los dos que cita la guía:

PreToolUse intercepta una llamada antes de ejecutarse. Puede devolver una decisión de permiso (allow, deny, ask) con su motivo. Es el sitio para bloquear un reembolso de más de 500 $ y mandar el caso a una persona.
PostToolUse actúa después, sobre el resultado. Sirve para normalizar datos heterogéneos antes de que los vea el modelo: un servidor MCP devuelve fechas en Unix, otro en ISO 8601, un tercero códigos de estado numéricos. El hook los unifica y Claude razona sobre un formato único.

async def limite_reembolso(input_data, tool_use_id, context):
    if input_data["tool_input"].get("importe", 0) > 500:
        return {"hookSpecificOutput": {
            "hookEventName": input_data["hook_event_name"],
            "permissionDecision": "deny",
            "permissionDecisionReason": "Más de 500: escalar a una persona",
        }}
    return {}

options = ClaudeAgentOptions(hooks={
    "PreToolUse": [HookMatcher(matcher="mcp__soporte__process_refund", hooks=[limite_reembolso])]
})

Si trabajas con SAP, es la misma lógica que las autorizaciones y los workflows de aprobación: nadie confía en que el usuario «se acuerde» de no contabilizar por encima de su límite; el sistema lo impide.

El otro lado del 1.4 es el traspaso a humanos. La persona que recibe el caso no ve la conversación. El agente debe entregar un resumen estructurado: identificador del cliente, causa raíz, importe, qué se ha intentado y acción recomendada. Y si el cliente trae varias peticiones en un mensaje, el agente las separa, investiga cada una (en paralelo si puede) y responde con una solución unificada.

Descomponer tareas y gestionar sesiones (1.6 y 1.7)

Dos formas de trocear el trabajo, y el examen quiere que sepas cuál toca:

Encadenado fijo (prompt chaining): pasos predecibles en orden. Ejemplo típico: revisar una pull request grande archivo por archivo para problemas locales y luego hacer una pasada de integración entre archivos. Evita la dilución de atención de meterlo todo en un único análisis.
Descomposición dinámica: cuando la tarea es abierta y lo que descubres cambia el plan. «Añade tests a este sistema heredado» se aborda mapeando primero la estructura, localizando lo de más impacto y creando un plan priorizado que se ajusta según aparecen dependencias.

Y para trabajos que duran más de una sesión:

Reanudar con nombre: en Claude Code, claude --resume <nombre> retoma una sesión concreta (el nombre se pone con --name o /rename). Útil cuando el contexto previo sigue siendo válido. Si has cambiado archivos desde entonces, díselo al agente para que reanalice solo esos.
Bifurcar: fork_session en el Agent SDK (o --fork-session en la CLI junto a --resume) crea una rama independiente desde un análisis común. Sirve para comparar dos estrategias de refactorización sin que una contamine a la otra.
Empezar de cero con resumen: si los resultados de herramientas guardados están desfasados, es más fiable abrir una sesión nueva e inyectar un resumen estructurado que reanudar con información vieja.

Para el examen

En el examenDominio 1 en una ficha

Dominio · Dominio 1 · Agentic Architecture & Orchestration (27 %)

Lo que tienes que dominar

El bucle sigue con stop_reason igual a tool_use y termina con end_turn; los resultados de herramientas se añaden al historial.
Hub-and-spoke: todo pasa por el coordinador (observabilidad, errores, flujo de información).
Los subagentes no heredan contexto: lo que necesiten va completo en su prompt, con metadatos estructurados.
Subagentes en paralelo: varias llamadas en una sola respuesta del coordinador. Task en la guía, Agent en la doc actual.
Reglas críticas con hooks o requisitos previos: PreToolUse para bloquear, PostToolUse para normalizar.
Encadenado fijo para revisiones predecibles; descomposición dinámica para investigaciones abiertas.
--resume si el contexto sigue valiendo; sesión nueva con resumen si está desfasado; fork_session para explorar alternativas.

Donde se suele fallar

Culpar a los subagentes cuando el coordinador descompuso mal el tema.
Parar el bucle leyendo el texto de Claude o con un tope de iteraciones como criterio principal.
Confiar en el prompt para reglas con dinero o identidad.
Suponer que el subagente «ya sabe» lo que vio el coordinador.
Lanzar subagentes en paralelo en turnos separados.

Checklist para el examen

0 de 7 dominados

Marca lo que ya sabrías responder en el examen.

Siguiente paso

Próxima lección: Diseño de herramientas y MCP: descripciones, errores estructurados, reparto de herramientas y configuración de servidores (dominio 2).

Arquitectura agéntica: bucles, coordinador, subagentes y hooks