Elección de arquitecturas agénticas: curso acelerado guiado por decisiones

Un curso acelerado conceptual sobre selección de patrones: cuándo usar un flujo de trabajo secuencial, un agente único + ReAct + herramientas, planificación + ejecución ReAct o un sistema especialista multiagente (los cuatro patrones centrales), y cuándo añadir reflexión encima de cualquiera de ellos, para ingenieros que ya entregaron agentes y necesitan elegir arquitecturas de forma fundamentada, no por lo que parece impresionante.

*22 conceptos • 5 decisiones • Cuatro rutas de aprendizaje. Ruta de lector: 2-3 horas de lectura conceptual pura (el árbol de decisión, los cinco patrones, las señales de fallo, sin configuración). Rutas principiante / intermedia / avanzada: ~1 día, 2-3 días, 4-5 días cada una (lectura conceptual más profundidad creciente para clasificar tareas reales, bosquejar topologías de despliegue y cablear señales de eval específicas de cada patrón). Estimación honesta total: 2-3 horas para la ruta de lector; 4-5 días para que un equipo internalice la selección de patrones como disciplina de trabajo. Elige tu ruta antes del laboratorio de decisión de la Parte 5.*

Artículo ancla: Bala Priya C, "Choosing the Right Agentic Design Pattern: A Decision-Tree Approach", Machine Learning Mastery, 15 de mayo de 2026: machinelearningmastery.com/choosing-the-right-agentic-design-pattern-a-decision-tree-approach. El árbol de decisión que sostiene este curso es suyo. La capa de composición, lo que cada patrón implica para tu topología de despliegue y tu suite de evals, es lo que este curso añade encima.

La versión en lenguaje claro (lee esto primero)

Ya construiste agentes. Tal vez el Worker de soporte al cliente que Maya construyó en el curso de Digital FTE, un agente de evaluación en el curso guiado por evals, un agente de soporte de nivel 1 que llevaste hasta producción en el curso de despliegue en la nube. Ahora puedes construir uno. Lo que todavía no puedes hacer, de forma fundamentada, es decidir qué tipo de agente construir la próxima vez.

Un modo de fallo real en la IA de producción: los ingenieros eligen el patrón que parece impresionante, normalmente multiagente, cuando la tarea pedía un flujo de trabajo secuencial que ni siquiera necesitaría un LLM en tres de sus cinco pasos. Semanas de trabajo de orquestación para un problema que un agente único bien instruido, con dos herramientas, podría manejar en un día. El modo de fallo opuesto también es real: los ingenieros eligen un agente único con una indicación de sistema larga cuando la tarea realmente necesita descomponerse en especialistas, y el agente colapsa bajo un contexto que no encaja en un solo modelo mental.

La selección de patrones es el trabajo de diseño que viene antes de construir. Es la pregunta: "¿qué forma debería tener realmente este sistema de agentes?". Y hay una respuesta fundamentada: haz cinco preguntas sobre tu tarea, y las respuestas apuntan a uno de cinco patrones de partida. Este curso enseña las cinco preguntas, los cinco patrones, las señales de fallo que indican que el patrón era incorrecto y (la parte que más importa cuando ya entregas sistemas reales) lo que cada patrón implica para tu topología de despliegue y tu suite de evals.

La disciplina no es "elige siempre el patrón más simple". Es "elige el patrón más simple que coincida con lo que la tarea realmente requiere, y añade complejidad solo cuando puedas nombrar la propiedad específica de la tarea que la exige". Un sistema multiagente es la respuesta correcta cuando la especialización o la escala crean un cuello de botella real, no cuando se ve más avanzado en una diapositiva.

Este curso es más corto que el curso guiado por evals y el curso de despliegue en la nube por diseño. El marco de lógica de decisión es compacto; rellenarlo con contenido panorámico sobre la historia de cada patrón diluiría la disciplina. El marco compacto es una virtud, no un error.

📖 Si no has tomado los cursos anteriores de la ruta Agent Factory

Este curso cruza referencias con la capa operativa (Inngest), la disciplina de evals y un despliegue en la nube, y usa "el agente de soporte de nivel 1 de Maya" como ejemplo continuo de esos cursos. Puedes usar este curso perfectamente sin haberlos leído. El árbol de decisión de cinco preguntas, los cinco patrones y la disciplina de señales de fallo funcionan por sí solos como marco transferible.

Para una primera pasada enfocada sin el contexto de los cursos previos, lee en este orden:

Parte 1 (el problema de selección de patrones): establece la disciplina

Parte 2 (el árbol de decisión de cinco preguntas): la columna vertebral conceptual

Patrones de la Parte 3, pero hojea los recuadros de capa operativa en la primera pasada

Parte 4 (señales de fallo y revisión)

Parte 5 (el laboratorio de decisión): los cinco ejemplos trabajados aterrizan incluso sin el contexto de Maya

Cierre de la Parte 7

Qué tratar como vista previa u opcional en una primera pasada:

Concepto 8.5 (primitivas del SDK): útil si usas OpenAI Agents SDK; hojéalo si usas otro framework, porque las formas de patrón subyacentes se transfieren

Concepto 8.6 (capa operativa con Inngest): útil si entregas sistemas agénticos de producción; hojéalo si todavía estás en la fase solo de diseño. El argumento de que "los patrones más elaborados necesitan más maquinaria operativa" se generaliza más allá de Inngest

Los recuadros de composición de despliegue en la Parte 3: útiles si estás en el mismo stack de nube; el principio general (qué patrones necesitan sandbox y cuáles no) se transfiere a cualquier configuración de nube

Trata las referencias cruzadas como ejemplos concretos de principios generales, no como prerrequisitos excluyentes. El marco funciona sin ellas.

Tabla de traducción de plataformas: a qué corresponde cada elección de Agent Factory

Si estás en otro stack, esta tabla asigna cada referencia de Agent Factory a alternativas comunes. El árbol de decisión, los cinco patrones, las señales de fallo y la galería de antipatrones funcionan igual en estas plataformas; solo cambian los nombres de las primitivas.

Referencia de Agent Factory (el stack usado aquí)	Alternativas comunes en 2026	Qué hace la capa
Inngest (capa operativa)	Temporal, Restate, Dapr Workflows, AWS Step Functions, Azure Durable Functions, LangGraph (parcial; ejecución durable mediante checkpointers)	Disparadores, ejecución durable, control de flujo, puertas HITL
OpenAI Agents SDK (motor de agentes)	LangGraph, AutoGen, CrewAI, AWS Strands, Pydantic AI, LlamaIndex Workflows	Bucle del agente, enrutamiento de herramientas, composición multiagente, salida estructurada
Phoenix / Arize (observabilidad de trazas)	Langfuse, Helicone, LangSmith, Logfire, Honeycomb, Datadog APM	Observabilidad del comportamiento del agente por traza más pipeline de traza a eval
Azure Container Apps (runtime del harness)	AWS Fargate, Google Cloud Run, Fly.io, Railway, Render, Kubernetes (cualquier nube)	Host de servicio HTTP de larga duración, autoscaling, secretos, ingreso
Neon Postgres (estado durable)	Supabase, AWS RDS Postgres, PlanetScale, CockroachDB, Google Cloud SQL	Sesiones, runs, trazas, log de auditoría: estado durable del agente
Cloudflare R2 (almacenamiento de archivos)	AWS S3, Google Cloud Storage, Azure Blob, Backblaze B2	Entradas, salidas, artefactos de conocimiento; acceso con URL prefirmada para sandbox
Cloudflare Sandbox (ejecución de código)	E2B, Modal, Daytona, Vercel Sandbox, Fly.io Machines, Cloudflare Containers	Espacio de trabajo aislado para código generado por agentes
`@inngest_client.create_function` (primitiva de envolvente)	`@workflow.defn` (Temporal), definición de máquina de estados (Step Functions), `StateGraph(...)` (LangGraph)	Registra una unidad de función durable
`ctx.step.run(name, fn)` (primitiva de envolvente)	`workflow.execute_activity()` (Temporal), estado `Task` (Step Functions), nodo en `StateGraph` (LangGraph)	Checkpoint durable que memoiza en reintentos
`ctx.step.wait_for_event(...)` (primitiva de envolvente)	`workflow.wait_condition()` (Temporal), `waitForTaskToken` (Step Functions), `interrupt()` (LangGraph)	Suspensión durable hasta evento o timeout, primitiva HITL
Disparador fan-out (primitiva de envolvente)	`workflow.execute_child_workflow()` paralelo (Temporal), estado `Map` (Step Functions), aristas paralelas (LangGraph)	Un coordinador → N runs especialistas
`Agent(...)` + `Runner.run()` (primitiva del SDK)	`Agent.execute()` (LangGraph), `Agent` + `initiate_chat()` (AutoGen), `Crew` + `kickoff()` (CrewAI)	Ejecutar el bucle del agente
`@function_tool` (primitiva del SDK)	`@tool` (LangGraph/LangChain), `Tool(...)` (AutoGen), modelos Pydantic en CrewAI	Exponer una función Python como herramienta del agente
`handoff(target_agent)` (primitiva del SDK)	`Command(goto=...)` (LangGraph), chats anidados (AutoGen), delegación de tareas (CrewAI)	Toma de control por un especialista
`Agent.as_tool()` (primitiva del SDK)	Subgrafo como nodo (LangGraph), llamadas a agentes anidados (AutoGen), patrones `as_tool` en CrewAI	El coordinador usa al especialista como herramienta
`output_guardrail` (primitiva del SDK)	Nodo personalizado + arista condicional (LangGraph), patrón validador (Pydantic AI), guardrails de AWS Strands	Pase de crítica/validación sobre la salida del agente

Cómo usar esta tabla. Cuando este curso diga "envuelve Runner.run() en step.run", y estés en Temporal más LangGraph, léelo como "envuelve Agent.execute() en workflow.execute_activity()". El argumento arquitectónico es idéntico; la sintaxis difiere. Un antipatón que debes evitar: no intentes aprender el stack de Agent Factory solo para leer este curso. Mapea las primitivas, lee el marco y aplícalo a tu stack.

Una fila que no se mapea limpiamente: Agent.as_tool() frente a handoff(). OpenAI Agents SDK distingue "el coordinador sigue al mando" (as_tool) de "el especialista toma el control" (handoff) como primitivas de primera clase. La mayoría de los demás frameworks colapsan la distinción o implementan solo una mitad. La distinción en sí es lo arquitectónicamente importante; el nombre de la primitiva es incidental. Cuando eliges entre composición estilo as_tool y estilo handoff en tu framework, estás tomando la misma decisión arquitectónica que este curso nombra; quizá tu framework solo la expone de otra forma.

Glosario (lee una vez y vuelve cuando lo necesites)

Haz clic para expandir el glosario completo.

Patrón de diseño agéntico. Una forma arquitectónica recurrente para sistemas de agentes de IA: flujo de trabajo secuencial, ReAct + herramientas, planificación + ejecución, reflexión, especialista multiagente. Cada patrón supone cosas específicas sobre la tarea; cuando esas suposiciones se cumplen, el patrón aporta valor; cuando no, se vuelve sobrecarga.
Flujo de trabajo secuencial. Un pipeline fijo de pasos donde la salida de cada paso alimenta el siguiente. La ruta de solución se conoce de antemano; las llamadas al LLM se reservan para interpretación o generación, no para decidir qué hacer después. Ejemplo: ingreso de factura → extraer → validar → almacenar → notificar.
ReAct (Reason + Act). Un bucle agéntico en el que el agente alterna entre razonar sobre su estado actual y tomar una acción (normalmente una llamada a herramienta), observa el resultado y repite. La propiedad definitoria: la siguiente acción se decide en runtime, no se especifica de antemano.
Agente de planificación. Un agente que produce un plan explícito (secuencia de etapas con dependencias) antes de que empiece la ejecución. El plan estructura el trabajo; los pasos individuales aún pueden usar ReAct internamente. Ejemplo: "investigar un mercado" → generar un plan de 5 pasos → ejecutar cada paso con herramientas.
Reflexión (autocrítica). Un patrón donde el agente genera una salida, la critica contra criterios explícitos y refina según la crítica. Añade latencia y costo; solo vale la pena cuando los criterios son verificables y los errores son caros. Ejemplo: generación de SQL con comprobaciones de corrección.
Sistema especialista multiagente. Un sistema en el que varios agentes con roles distintos (investigador, redactor, revisor) colaboran en una tarea, coordinados por un agente de enrutamiento o supervisión. Se justifica por especialización, sobrecarga de contexto o necesidades de ejecución paralela; no por estética.
Ruta de solución. La secuencia de pasos que resuelve la tarea. Una ruta conocida significa que los pasos se pueden especificar antes del runtime; una ruta desconocida significa que los pasos emergen de la investigación del agente.
Estructura de la tarea. Las etapas principales y sus dependencias. Una estructura articulable significa que puedes describir las etapas antes de ejecutar; una estructura emergente significa que las etapas se revelan mediante retroalimentación.
Encaje arquitectónico. La coincidencia entre las suposiciones de un patrón y las propiedades reales de la tarea. La selección de patrones es emparejar por encaje, no por capacidad: elegir el patrón más capaz es la heurística incorrecta.
Sobrecarga de coordinación. El costo (en tokens, latencia, complejidad de depuración y modos de fallo) de enrutar entre varios agentes o coordinar sus handoffs. Los sistemas multiagente pagan este costo; debe justificarse por lo que la coordinación compra.
Señal de fallo. Un síntoma en runtime que indica que el patrón elegido no coincide con la tarea. Ejemplos: bucles ReAct que vuelven a trabajo ya resuelto (falta estructura), el plan produce rutas de las que la ejecución diverge (sobreestructurado), la reflexión no mejora la salida (criterios vagos).
Composición de patrones. Usar patrones distintos en capas distintas de un sistema mayor. Ejemplo: un agente de planificación en la capa superior, ReAct + herramientas dentro de cada paso del plan, reflexión sobre la síntesis final.
Agent (OpenAI Agents SDK). La clase central del SDK: una entidad impulsada por LLM definida mediante instructions=, tools= opcionales, output_type= opcional para salida estructurada y handoffs= opcionales. La unidad atómica de cada patrón de este curso.
Runner.run(agent, input) (OpenAI Agents SDK). La llamada del SDK que ejecuta un Agent hasta que produce salida final. El SDK ejecuta internamente el bucle razonar-actuar-observar: no hace falta escribir un bucle propio. El parámetro max_turns= es el presupuesto de pasos.
@function_tool (OpenAI Agents SDK). Decorador que convierte una función Python en una herramienta que el agente puede llamar. Las sugerencias de tipo y las docstrings se convierten automáticamente en el esquema JSON de la herramienta.
handoff() (OpenAI Agents SDK). Primitiva de primera clase del SDK para transiciones multiagente: un agente entrega explícitamente la conversación a otro, y el SDK conserva el contexto. Úsalo cuando el especialista necesita hacerse cargo de la interacción con el usuario.
Agent.as_tool() (OpenAI Agents SDK). Método del SDK que envuelve un Agent como herramienta invocable que otro Agent puede llamar. Úsalo cuando el coordinador necesita seguir al mando y componer salidas de especialistas.
output_guardrail (OpenAI Agents SDK). Decorador del SDK que conecta un agente de validación/crítica a la ruta de salida de otro agente. La primitiva nativa del SDK para reflexión estilo bloquear-salidas-malas; lanza OutputGuardrailTripwireTriggered cuando se activa.
Capa operativa (Inngest). La capa de runtime que despierta una función de agente (disparadores), sobrevive a fallos a mitad de ejecución (ejecución durable mediante step.run), limita la carga (concurrencia, throttle, prioridad) y coordina HITL (step.wait_for_event). Compone con tu despliegue en la nube y el motor del SDK. Se enseña en el curso de capa operativa.
@inngest_client.create_function (Inngest). Decorador que registra una función asíncrona de Python en Inngest como unidad ejecutada de forma durable. Declara la superficie de disparo y la política de control de flujo.
ctx.step.run(name, fn, args) (Inngest). El checkpoint de durabilidad. Los pasos completados devuelven salida memoizada en reintentos; los pasos fallidos reintentan de forma independiente con backoff exponencial.
ctx.step.wait_for_event(...) (Inngest). Suspensión durable hasta que llega un evento coincidente o se dispara un timeout. Cero cómputo consumido durante la suspensión. La primitiva de runtime detrás de las puertas HITL.
Patrón de disparador fan-out (Inngest). Un coordinador emite N eventos; cada evento despierta su propia función suscriptora. La primitiva de runtime detrás de la ejecución paralela de especialistas en sistemas multiagente.
Replay (Inngest). Los runs fallidos persisten con traza completa. Entrega un arreglo, haz clic en replay; la función se reanuda desde el paso fallido con el código nuevo. Los pasos exitosos permanecen memoizados.

¿Estás listo? (requisitos previos)

Has construido tu primer agente, o tienes experiencia equivalente. Los patrones que enseña este curso suponen que entiendes qué es un bucle de agente, cómo se ve una llamada a herramienta y cómo un modelo devuelve salida estructurada. Si todavía no has construido un agente, trabaja primero el curso de construcción de agentes.

Has construido al menos un agente funcional. Ya sea el Worker de soporte al cliente que Maya construyó, un agente de investigación, un chatbot o un agente de coding, necesitas la experiencia de haber tomado una decisión arquitectónica (aunque no te dieras cuenta de que la estabas tomando) y haber vivido con sus consecuencias.

Puedes leer pseudocódigo. Este es un curso conceptual, así que tiene muy poco código ejecutable. Lo que verás es pseudocódigo para ilustrar patrones; si puedes leer Python o TypeScript, puedes leerlo.

(Opcional pero muy recomendable) Has trabajado los cursos de evals y despliegue en la nube. La contribución principal de este curso es componer la selección de patrones con tu topología de despliegue y tu suite de evals. Los lectores que no hayan hecho esos cursos aún pueden beneficiarse del marco, pero se perderán los argumentos de integración.

Si te falta el punto 4, lee este curso de todos modos y trata los recuadros de composición de despliegue y de composición de evals como vistas previas. El marco aterriza sin ellos.

Bordes ásperos que conviene conocer desde el inicio (el alcance honesto)

Este es un curso conceptual, no un curso de código. Te enseña a elegir una arquitectura, no a implementar una. La disciplina de implementación vive en los cursos anteriores de Agent Factory. Espera unas 30 páginas de razonamiento arquitectónico y unas 5 páginas de pseudocódigo en total.

Los cinco patrones no son exhaustivos. La realidad tiene sistemas de agentes basados en grafos, patrones de debate, patrones de pizarra, redes jerárquicas de tareas y otros que no se cubren aquí. Este curso cubre los cinco patrones que el artículo identifica como los puntos de partida arquitectónicos dominantes; estos cinco cubren la gran mayoría de los sistemas de agentes de producción a mediados de 2026, aunque no todos.

El árbol de decisión es un punto de partida, no una respuesta final. Las arquitecturas de agentes reales evolucionan. Un sistema que empezó como agente único con herramientas puede convertirse en sistema multiagente a medida que la carga de trabajo se diversifica; un sistema de planificación y luego ejecución puede simplificarse en un flujo de trabajo secuencial cuando las rutas se vuelven más claras. Este curso enseña la decisión inicial, no toda la evolución.

El costo y la latencia forman parte de la elección. La reflexión añade latencia. Multiagente añade tokens. La planificación añade una llamada adicional al LLM. Este curso trata esos costos como restricciones reales; el Concepto 18 cubre cuándo se justifica la sobrecarga de cada patrón.

El artículo es la columna vertebral; la capa de composición es la extensión. El árbol de decisión de Bala Priya C es la estructura central de este curso. Este curso añade dos capas que el artículo no cubre: (a) qué implica cada patrón para tu topología de despliegue y (b) cómo se ven los modos de fallo de cada patrón a través de tu suite de evals. Si solo has leído el artículo, este curso añade la capa de disciplina de producción.

Cuatro rutas de aprendizaje

Ruta	Compromiso de tiempo	Qué completas	Para quién es
Lector (conceptual puro)	~2-3 horas, sin laboratorio	El arco conceptual completo: Parte 1 (el problema), Parte 2 (el árbol de decisión), Parte 3 (los cinco patrones), Parte 4 (señales de fallo) y el cierre de la Parte 7. Sin ejercicios de clasificación, sin laboratorio de decisión.	Líderes de ingeniería, arquitectos de plataforma o lectores curiosos no ingenieros que deciden si invertir tiempo de equipo en selección sistemática de patrones.
Principiante	~1 día	Ruta de lector + Decisiones 1-2 del laboratorio de decisión. Clasificar dos tareas (el soporte de nivel 1 de Maya y un agente de respuesta a incidentes) usando el árbol de decisión; bosquejar el patrón elegido a alto nivel.	Ingenieros nuevos en arquitectura agéntica que quieren una ronda guiada de práctica de selección de patrones.
Intermedio	~2-3 días	Ruta principiante + Decisiones 3-4. Añadir un agente de investigación y un agente de onboarding empresarial; bosquejar sus topologías de despliegue en tu stack de nube; identificar las señales de eval que atraparían el modo de fallo de cada patrón.	Ingenieros que entregan sistemas agénticos y quieren componer selección de patrones con despliegue y evaluación.
Avanzado	~4-5 días	Ruta intermedia + Decisión 5 + Partes 6 y 7. Añadir un agente de coding (el caso más difícil); explorar composición de patrones (varios patrones en distintas capas); arquitectar un sistema hipotético de agentes de extremo a extremo usando la disciplina completa.	Ingenieros sénior y tech leads que quieren convertir la selección de patrones en una disciplina de todo el equipo.

Guía para elegir ruta. Los líderes de ingeniería deberían empezar por la ruta de lector. Los ingenieros deberían elegir por defecto la ruta intermedia; el laboratorio de decisión es donde el marco realmente se internaliza. No te saltes por completo la Parte 5 solo porque puedas leer rápido la Parte 2. El marco solo se fija cuando lo aplicas a tareas reales.

🚀 Ruta mínima viable, el camino más corto hacia selección de patrones funcional. Lee la Parte 1 (el problema), la Parte 2 (el árbol de decisión) y la Decisión 1 del laboratorio (soporte de nivel 1 de Maya). Eso son ~90 minutos; al final podrás clasificar una tarea nueva usando las cinco preguntas y elegir un patrón de partida. Todo lo demás profundiza la disciplina; esta es la semilla.

Qué tendrás al final (resultados concretos)

La ruta de lector produce comprensión, no artefactos. Podrás: explicar por qué importa la selección de patrones antes de escribir código; describir cada uno de los cinco patrones y sus suposiciones características sobre la tarea; reconocer las cinco señales de fallo comunes que indican desajuste de patrón.

Las rutas principiante / intermedia / avanzada producen una disciplina de clasificación funcional:

La capacidad de recorrer el árbol de decisión de cinco preguntas sobre una tarea nueva y elegir un patrón de partida fundamentado.
Un bosquejo de la topología de despliegue de cada patrón en tu stack de nube (qué componentes necesita un flujo de trabajo secuencial frente a un sistema multiagente o de planificación).
Un mapeo desde los modos de fallo probables de cada patrón hasta las señales de eval específicas que los atraparían.
Un artefacto compartible con el equipo: una plantilla de una página para "clasificar esta tarea" que puedes usar en revisiones de diseño.

TL;DR: las cuatro afirmaciones que defiende este curso

La selección de patrones es encaje arquitectónico, no emparejamiento por capacidad. Cada patrón supone algo sobre la tarea. El patrón correcto es aquel cuyas suposiciones coinciden con las propiedades reales de la tarea, no el que tiene más capacidad o la estructura más impresionante. Multiagente no es "mejor que" un flujo de trabajo secuencial; es mejor para el caso específico donde la especialización o la escala crean un cuello de botella.

Cuatro patrones centrales + una capa adicional. Las preguntas Q1-Q3 del árbol de decisión eligen un patrón central: flujo de trabajo secuencial, agente único + ReAct + herramientas, planificación + ejecución ReAct o sistema especialista multiagente. Q4 decide si añadir reflexión como capa adicional encima del núcleo elegido. La reflexión no es un quinto patrón par; es una capa de control de calidad que envuelve cualquiera de los cuatro núcleos. Esta distinción importa: los estudiantes que tratan la reflexión como patrón independiente se pierden la verdad arquitectónica de que se compone con el patrón central que ya eligieron.

Cinco preguntas sobre la tarea determinan la arquitectura. Q1-Q3 eligen el patrón central: ¿se conoce la ruta de solución? ¿El flujo de trabajo es fijo? ¿La estructura de la tarea es articulable? Q4 decide si se añade reflexión encima: ¿la calidad importa más que la velocidad con criterios verificables? Q5 decide si escalar a multiagente: ¿hay un cuello de botella de especialización, contexto o escala? Las respuestas se asignan de forma determinista a una arquitectura inicial. El artículo tiene razón en que lo que falta en la literatura es la lógica de decisión, no los patrones en sí.

La selección de patrones compone con la topología de despliegue y las señales de eval. Cada patrón usa un subconjunto distinto del stack de nube: los flujos de trabajo secuenciales no necesitan ejecución en sandbox; los sistemas multiagente necesitan logs de auditoría cuidadosos porque los fallos de coordinación son el bug de producción más difícil. Cada patrón tiene modos de fallo característicos que tu suite de evals atrapa de forma distinta. Pocos cursos sobre este tema enseñan esta composición, porque necesita los cursos de despliegue y evals como base.

El árbol de decisión da un punto de partida, no una respuesta final. Los sistemas reales evolucionan. La disciplina no es "bloquear la arquitectura para siempre", sino "tomar la decisión inicial de forma fundamentada, vigilar las señales de fallo y dejar que la evidencia de runtime guíe la evolución". La selección de patrones es el primer movimiento; la revisión de patrones es el movimiento continuo.

La forma de lo que estás aprendiendo (un diagrama, vuelve a él durante todo el curso)

Este curso presenta 22 conceptos (19 principales más 3 conceptos puente en 8.5, 8.6 y 16.5) y recorre 5 decisiones. Antes de todo eso, aquí está el árbol de decisión alrededor del cual se compone todo.

*La forma del árbol: empieza preguntando si siquiera necesitas un agente impulsado por LLM (Q1-Q2); si sí, pregunta qué tan estructurada es la tarea (Q3); luego añade calidad (Q4) y escala (Q5) solo cuando creen valor real. Vuelve a este diagrama cada vez que un concepto o decisión se sienta abstracto.*

Parte 1: El problema de selección de patrones

Concepto 1: La selección de patrones es el trabajo de diseño que viene antes de construir

La mayoría de los cursos sobre sistemas agénticos te enseñan cómo construir cada patrón. Este curso trata una pregunta distinta: dada una tarea, ¿qué patrón deberías construir? Esta pregunta viene antes de construir, y así debería ser, pero normalmente no se enseña por una razón incómoda: la implementación de cada patrón está bien documentada; la lógica de decisión para elegir entre ellos no.

El catálogo de patrones está maduro. ReAct viene de un paper de 2022. Los patrones de planificación y luego ejecución se remontan a STRIPS en la IA clásica y fueron redescubiertos para LLMs en 2023. La reflexión se formalizó desde 2023. Todos los grandes frameworks enseñan arquitecturas multiagente. Puedes encontrar un tutorial de cualquier patrón en menos de cinco minutos. Lo que no puedes encontrar fácilmente es: dada esta tarea específica con estas restricciones específicas, ¿qué patrón encaja?

El modo de fallo que esto crea. Los ingenieros eligen por defecto el patrón que vieron más recientemente o el que se ve más impresionante en charlas. Las demos multiagente son especialmente tentadoras porque parecen "IA real": agentes hablando entre sí, dividiendo trabajo, coordinándose. Los equipos pasan semanas construyendo orquestación para problemas que un agente único con dos herramientas bien definidas podría resolver en un día. El resultado: entregan más lento, depuran con más dificultad y pagan más tokens de los que la tarea requería.

El modo de fallo opuesto también es real y se discute menos. Los ingenieros eligen "usa solo un agente único con una indicación de sistema muy larga" cuando la tarea realmente necesita descomposición estructural. El agente colapsa bajo un contexto que no encaja en un solo modelo mental. Los errores de llamada a herramientas se encadenan. La reflexión se convierte en el único arreglo que el equipo conoce, así que la añaden en todas partes, y ahora cada respuesta tarda 30 segundos. Entregan algo frágil que una decisión arquitectónica podría haber evitado.

La disciplina que enseña este curso: la selección de patrones es emparejar por encaje arquitectónico, no por capacidad. No preguntes "¿cuál es el mejor patrón?" (no existe). Pregunta "¿qué requiere realmente esta tarea y cuál es el patrón más pequeño que lo proporciona?". El árbol de decisión de cinco preguntas de la Parte 2 es la forma sistemática de responder.

Por qué esto importa más que antes. En 2023, los sistemas agénticos eran experimentales. Elegir el patrón incorrecto desperdiciaba un fin de semana. En 2026, los sistemas agénticos están en producción sirviendo a usuarios reales; el patrón que eliges determina tu topología de despliegue, tu disciplina de evals y tu costo operativo a escala. Una elección de patrón incorrecta ahora es cara de formas que se acumulan: infraestructura construida para la suposición equivocada, evals escritas para los modos de fallo equivocados, runbooks respondiendo a los incidentes equivocados. La selección de patrones pasó de ser "preferencia" a ser "decisión de diseño de alto impacto".

Idea central: los patrones en sí están bien documentados; la lógica de decisión para elegir entre ellos es el vacío que llena este curso. La selección de patrones es emparejar por encaje arquitectónico, no por capacidad. El patrón equivocado se encarece de forma compuesta en producción: infraestructura equivocada, evals equivocadas, runbooks equivocados. Este curso enseña la disciplina de cinco preguntas que evita los fallos más comunes de selección de patrones.

Concepto 2: Cada patrón supone algo distinto sobre la tarea

La idea profunda que vuelve manejable la selección de patrones: cada patrón agéntico es una apuesta sobre cómo se ve la tarea. Cuando la apuesta coincide con la realidad, el patrón aporta valor. Cuando la apuesta es incorrecta, el patrón se vuelve sobrecarga: a veces sobrecarga invisible que solo cuesta tokens, a veces sobrecarga catastrófica que rompe todo el sistema.

Esto es lo que apuesta cada uno de los cinco patrones:

El flujo de trabajo secuencial apuesta: conozco los pasos de antemano y son los mismos cada vez. La apuesta es que la ruta de solución es fija y articulable antes del runtime. Si es cierto, no necesitas un LLM para decidir qué hacer después: el flujo de trabajo lo sabe. Reservas las llamadas al LLM solo para los pasos que realmente necesitan interpretación (extraer esto del texto, generar ese resumen). El costo es predecible; la latencia está acotada; los modos de fallo son obvios. Si es falso: si los pasos en realidad varían según lo que contiene la entrada, el flujo de trabajo fuerza la ruta equivocada o falla ruidosamente.

Agente único + ReAct + herramientas apuesta: no conozco la ruta de antemano; el agente la descubrirá. La apuesta es que la tarea es lo bastante abierta como para que el siguiente paso deba decidirse según lo observado hasta ahora. Si es cierto, el bucle de ReAct (razonar → actuar → observar → repetir) es la única forma de manejarla; cualquier plan predeterminado estaría equivocado para el paso 3. Si es falso: si la ruta en realidad es bastante estable y podría haberse escrito, ReAct añade latencia, costo y riesgo de que el agente entre en bucle o vuelva a trabajo ya resuelto, sin comprar nada que no pudieras obtener de un flujo de trabajo secuencial.

Planificación + ejecución ReAct apuesta: puedo articular las etapas principales y sus dependencias de antemano, pero cada etapa aún requiere razonamiento adaptativo. La apuesta es que la forma del trabajo se conoce (investigar → analizar → sintetizar → informar), pero el contenido de cada etapa requiere investigación. Si es cierto, el plan proporciona andamiaje y evita que el agente divague, mientras que ReAct dentro de cada etapa maneja la incertidumbre. Si es falso: si el plan no puede articularse realmente (usa ReAct puro) o si cada etapa no necesita razonamiento adaptativo (usa un flujo de trabajo secuencial), el plan se convierte en sobrecarga de la que la ejecución diverge de todos modos.

Reflexión apuesta: la calidad de salida importa más que la velocidad, y la calidad es verificable. La apuesta es que un pase de crítica puede identificar defectos que el generador omitió, y que los criterios de "buena salida" son lo bastante explícitos para que la crítica tenga sentido. Si es cierto, la reflexión mejora la confiabilidad al atrapar errores que produjo la primera pasada (SQL incorrecto, argumentos legales débiles, errores factuales en informes). Si es falso: si los criterios son vagos o si el crítico y el generador comparten los mismos puntos ciegos, la reflexión añade latencia y costo sin mejorar la salida. Peor: puede producir falsa confianza en que la crítica "verificó" una calidad que en realidad no verificó.

El sistema especialista multiagente apuesta: ningún agente único tiene la expertise, el contexto o la capacidad para hacer esto bien. La apuesta es que la tarea realmente se particiona en roles especialistas (investigador + redactor + revisor; programador + seguridad + documentación), y que coordinar especialistas es más barato que sobrecargar a un solo agente. Si es cierto, los especialistas producen mejores salidas en sus dominios que un generalista, y la ejecución paralela mejora el throughput. Si es falso: si los "especialistas" hacen casi lo mismo, o si la sobrecarga de coordinación domina el trabajo, añadiste complejidad que no compra nada e introdujiste nuevos modos de fallo (errores de enrutamiento, errores de integración, ambigüedad de propiedad).

El patrón es la apuesta; las propiedades reales de la tarea determinan si la apuesta es correcta. Por eso la selección de patrones es emparejar por encaje. No preguntas "¿qué patrón es más poderoso?". Preguntas "¿qué apuesta de patrón coincide mejor con lo que realmente sé sobre esta tarea?".

Idea central: cada patrón agéntico es una apuesta sobre la tarea: el flujo de trabajo secuencial apuesta por rutas conocidas y fijas, ReAct por rutas adaptativas desconocidas, la planificación por estructura articulable, la reflexión por criterios de calidad verificables y multiagente por necesidades reales de especialización. El patrón correcto es aquel cuya apuesta coincide con la realidad; la selección de patrones es emparejar por encaje, no por capacidad.

Concepto 3: Dos modos de fallo: sobredimensionar y quedarse corto

El Concepto 2 nombró que cada patrón es una apuesta. El Concepto 3 nombra las dos formas en que esa apuesta sale mal, y ocurren con frecuencia más o menos igual en sistemas de producción reales.

Sobredimensionar: elegir un patrón más elaborado de lo que la tarea necesita. Este es el modo de fallo más famoso, el que las charlas y demos facilitan. Ejemplos:

Construir un sistema de tres agentes (investigador, redactor, revisor) para una tarea que es generar una sola publicación de LinkedIn. La salida del agente "investigador" son dos párrafos que el "redactor" luego tiene que resumir. El revisor rechaza 5% de las salidas por problemas que una indicación de autocheck habría atrapado. Tres agentes, tres veces el costo, ninguna mejora de calidad medible.
Añadir planificación a una tarea que en realidad es un flujo de trabajo fijo. El planificador produce el mismo plan cada vez (porque la tarea es la misma). Cada run paga una llamada adicional al LLM para nada. Peor: cuando la entrada es ligeramente inusual, el planificador produce un plan ligeramente distinto, y ahora el equipo tiene que depurar "¿por qué el planificador tomó una ruta distinta con esta entrada?".
Añadir reflexión a una tarea sin criterios verificables. El crítico y el generador comparten el mismo modelo, los mismos datos de entrenamiento y (a menudo) los mismos puntos ciegos. El pase de reflexión aprueba mecánicamente la salida o genera crítica verbosa pero no accionable. La latencia se duplica; la calidad queda igual.

El patrón de fallo por sobredimensionamiento: pagaste por capacidad que la tarea no necesitaba, y no puedes deshacerlo fácilmente porque la orquestación ahora es parte crítica del sistema. Quitar un sistema multiagente que lleva seis meses en producción no es un refactor; es una reescritura.

Quedarse corto: elegir un patrón más simple de lo que la tarea realmente necesita. Este es el modo de fallo que las charlas rara vez muestran porque es menos vistoso, pero es al menos igual de común. Ejemplos:

Usar un agente único con una indicación de sistema de 4.000 tokens para manejar soporte al cliente en facturación, técnico, cuenta y reembolsos. El agente confunde reglas de facturación con reglas técnicas. La reflexión ayuda de forma marginal, pero no arregla la causa raíz. La tarea realmente necesitaba enrutamiento a especialistas; un agente único no podía contener el contexto.
Usar ReAct + herramientas para un flujo de trabajo que debería ser un pipeline fijo. El agente a veces omite pasos, a veces vuelve a trabajo completado, a veces inventa llamadas a herramientas que no existen. El equipo añade "condiciones de parada" y "criterios de progreso" a la indicación, tratando síntomas en lugar del desajuste subyacente. La variación de costo se convierte en un problema de runbook.
Saltarse la reflexión en salidas que realmente necesitan verificación. Consultas SQL con errores sutiles llegan a producción. Borradores legales se envían a clientes con errores de cita. El equipo añade pruebas después del hecho, pero el lugar natural para atrapar esos errores era un pase de reflexión en el momento de generación.

El patrón de fallo por quedarse corto: entregaste algo frágil que sobrevive por supervisión manual o por suerte. Producción revela las brechas; remediarlas implica añadir el patrón con el que debiste empezar o aceptar la tasa de fallo como costo de hacer negocio.

Por qué ambos modos de fallo importan por igual. Las discusiones sobre selección de patrones se enfocan en sobredimensionar (porque es el fallo más visible: el sistema multiagente que nadie puede depurar). Pero quedarse corto es igual de común y quizá más peligroso: produce sistemas que parecen funcionar hasta que dejan de hacerlo, y los modos de fallo son sutiles. Un equipo que aprende a evitar el sobredimensionamiento pero nunca reconoce cuando se queda corto solo aprendió la mitad de la disciplina.

El árbol de decisión de la Parte 2 está diseñado para hacer visibles ambos modos de fallo. Cada pregunta indaga una propiedad de la tarea (¿se conoce la ruta?, ¿la estructura es articulable?, ¿la calidad es verificable?); si la respuesta no justifica un patrón más elaborado, el árbol enruta a uno más simple (previene sobredimensionar). Si la respuesta sí justifica el patrón más elaborado, el árbol enruta allí explícitamente (previene quedarse corto al hacer consciente la actualización).

Idea central: la selección de patrones falla de dos maneras: sobredimensionar (elegir un patrón más elaborado de lo que la tarea necesita, pagando por capacidad que no ayuda) y quedarse corto (elegir un patrón más simple de lo que la tarea requiere, entregando algo frágil). Ambos modos de fallo ocurren con frecuencia similar; las charlas enfatizan sobredimensionar, pero quedarse corto es al menos igual de peligroso porque es más sutil. El árbol de decisión de la Parte 2 muestra ambos fallos al preguntar por propiedades de la tarea, no por preferencias de patrón.

Parte 2: El árbol de decisión de cinco preguntas

Esta parte recorre el árbol de decisión pregunta por pregunta. Cada concepto cubre una de las cinco preguntas: qué prueba, cómo responderla para una tarea real y a qué patrón enruta la respuesta. Al final de la Parte 2, habrás recorrido el árbol completo una vez.

La estructura del árbol:

#	Pregunta	Qué prueba	Enruta a
Q1	¿La ruta de solución se puede definir de antemano?	Si el proceso se puede especificar antes del runtime	Si sí → Q2 (verificación de flujo fijo); si no → se necesita razonamiento adaptativo, ir a Q3
Q2	¿El flujo de trabajo es fijo y estable entre runs?	Si los mismos pasos aplican cada vez	Si sí → Flujo de trabajo secuencial; si no → volver a patrones adaptativos
Q3	¿La estructura de la tarea es articulable antes de ejecutar?	Si las etapas principales y dependencias están claras	Si sí → Planificación + ejecución ReAct; si no → Agente único + ReAct + herramientas
Q4	¿La calidad importa más que la velocidad, con criterios verificables?	Si los pases extra de crítica/refinamiento valen la latencia/costo	Si sí → añadir capa de reflexión encima del patrón elegido; si no → omitir reflexión
Q5	¿Hay un cuello de botella de especialización, contexto o escala?	Si un agente no tiene la expertise, el contexto o la capacidad paralela	Si sí → Sistema especialista multiagente; si no → mantener agente único

Las preguntas 1-3 determinan el patrón central. Las preguntas 4-5 son capas adicionales; pueden aplicar encima de cualquier patrón central, pero solo cuando sus suposiciones se cumplen.

Concepto 4: Q1: ¿La ruta de solución se puede definir de antemano?

La pregunta más importante, porque determina si necesitas siquiera un sistema agéntico.

Qué significa "la ruta de solución". Concretamente: si te digo la entrada, ¿puedes decirme la secuencia exacta de pasos que produce la salida? No la respuesta en sí, solo la ruta. Para ingreso de facturas: recibir el correo → extraer campos estructurados → validar contra la base de datos → almacenar → notificar al solicitante. Cinco pasos, los mismos cinco pasos, cada vez. Esa es una ruta de solución conocida.

Contraste: un cliente pregunta "¿por qué me cobraron dos veces el 12 de noviembre?". La ruta depende de lo que encuentres. Consulta el historial de transacciones. Encuéntralo. Los dos cargos son de comercios distintos: pivota a "¿fue fraude?". O son del mismo comercio con timestamps distintos: pivota a "¿el segundo fue un reintento?". O la cuenta del cliente tiene varios usuarios: pivota a "¿alguien más hizo la compra?". Cada rama lleva a un siguiente paso distinto. La ruta no se puede especificar de antemano; emerge de lo que revela la investigación. Esa es una ruta de solución desconocida.

Cómo probar esto honestamente. Tres pruebas, en orden:

¿Puedes escribir un diagrama de flujo de los pasos antes de ver la entrada? Si sí, la ruta es conocida. Si tu diagrama necesita cuadros de "ahora el agente decide qué hacer", la ruta es desconocida.
¿Los pasos se repiten sin cambios en muchos runs? El ingreso de facturas se repite. Las investigaciones de soporte al cliente no. El esquema de un informe de investigación quizá tenga la misma forma cada vez (introducción, tres secciones, conclusión), pero el descubrimiento de contenido no es una secuencia de pasos; es búsqueda adaptativa.
Cuando cambia la entrada, ¿cambian los pasos? Una ruta conocida produce la misma secuencia de pasos para entradas distintas. Una ruta desconocida produce secuencias de pasos distintas según lo que revela cada paso.

Dónde se equivocan los equipos. El error más común es creer que la ruta es conocida porque la descripción de la tarea suena estructurada. "Procesar solicitudes de reembolso" suena conocido: recibe la solicitud, busca el pedido, emite el reembolso, notifica al cliente. Las solicitudes reales de reembolso no son así. Algunas requieren investigación de disputa (¿fue un contracargo?), otras requieren consulta de política (¿el plan de este cliente permite reembolsos?), otras requieren escalamiento (el monto supera la autoridad del agente), otras involucran múltiples cargos que hay que desambiguar. El diagrama de cuatro pasos es incorrecto; la ruta real es adaptativa.

El error espejo: creer que la ruta es desconocida porque la descripción de la tarea suena abierta. "Ayúdame a encontrar un buen restaurante en la ciudad esta noche" suena adaptativo, pero si la implementación real es: analizar la solicitud → consultar la base de datos de restaurantes con filtros → devolver los 5 mejores por calificación, la ruta es conocida y el patrón correcto es un flujo de trabajo secuencial. El encuadre "agéntico" era engañoso.

La ruta. Si la ruta es conocida (y estable, ver Q2 a continuación), vas hacia un flujo de trabajo secuencial. Quizá ni siquiera necesitas un agente impulsado por LLM; quizá necesitas un flujo de trabajo con llamadas al LLM incrustadas en pasos específicos para interpretación o generación. Si la ruta es desconocida, necesitas razonamiento agéntico; la pregunta es si la estructura es articulable (Q3, planificación) o no (Q3, ReAct puro).

Una heurística útil. Pregúntate: "Si tuviera que escribir esto como una función Python sin llamadas a LLM, ¿sabría cómo estructurarla?" Si sí, la ruta probablemente es conocida; el LLM solo se necesita para momentos específicos de razonamiento o generación. Si no, la ruta probablemente es desconocida; el LLM está tomando decisiones estructurales, no solo generativas.

Idea central: Q1 pregunta si la ruta de solución se puede especificar antes del runtime. Las rutas conocidas van a flujos de trabajo secuenciales (Q2); las rutas desconocidas van a razonamiento agéntico adaptativo (Q3). El error más común es creer que la ruta es conocida cuando la descripción de la tarea suena estructurada, pero la implementación real es adaptativa: procesamiento de reembolsos, soporte al cliente, depuración. El error opuesto es creer que la ruta es desconocida cuando en realidad es un flujo de trabajo con entrada sabor LLM. Prueba con la heurística de "función Python sin llamadas a LLM".

Concepto 5: Q2: ¿El flujo de trabajo es fijo y estable entre runs?

Respondiste Q1 con "sí, la ruta es conocida". Q2 es la segunda verificación: ¿es fija y estable entre las entradas que realmente esperas? Porque "conocida" y "estable" no son lo mismo.

La distinción. Una ruta puede ser conocida en principio pero variar en la práctica. Considera un agente "asistente de investigación" que maneja consultas de usuarios. A veces el usuario quiere una respuesta rápida (buscar un dato y devolverlo). A veces quiere una síntesis de varias fuentes (buscar, comparar, resumir). A veces quiere análisis de un documento que sube (leerlo, extraer afirmaciones, evaluar). Podrías escribir la ruta de cada caso, pero la ruta varía con el tipo de entrada. Eso es conocido pero variable, no conocido y estable.

Frente a: ingreso de facturas. Cada factura pasa por los mismos cinco pasos. La ruta es estable. El contenido de cada paso varía (proveedores distintos, montos distintos), pero la estructura de pasos no.

Por qué importa. Un flujo de trabajo secuencial supone estabilidad. Si construyes un pipeline fijo y la ruta varía, el pipeline fuerza la ruta incorrecta para algunas entradas, ya sea intentando aplicar pasos que no aplican (la consulta de respuesta rápida recibe el tratamiento completo de síntesis) o fallando ruidosamente (la ruta de análisis de documentos no encaja con la estructura de respuesta rápida).

La prueba. Mira una muestra representativa de entradas reales (o imagínalas con cuidado). ¿La secuencia de pasos permanece igual entre ellas?

Sí, cada entrada pasa por los mismos pasos → el flujo de trabajo es estable; construye un flujo de trabajo secuencial.
No, entradas distintas necesitan secuencias de pasos distintas → el flujo de trabajo es variable; necesitas (a) un flujo de trabajo con ramificación explícita que maneje cada variante, o (b) un patrón agéntico que adapte la ruta según la entrada.

Dónde se equivocan los equipos. Tratar "conocido en promedio" como "conocido y estable". El caso de 80% es un flujo de trabajo fijo; el caso de 20% requiere desviarse. Los ingenieros construyen el flujo para el 80% y agregan parches ad hoc para el 20%. Finalmente los parches dominan el flujo original, y tienes un híbrido indocumentado que nadie entiende. Este patrón aparece más a menudo cuando el equipo se resiste a admitir que la tarea es más adaptativa de lo esperado: los flujos secuenciales se sienten más seguros que los patrones agénticos, así que sobreajustan.

La ruta. Si el flujo de trabajo es fijo y estable → Flujo de trabajo secuencial. Detente aquí para esta rama del árbol. Omite las preguntas 3 y (a menudo) 4. Considera Q5 solo si la escala fuerza paralelización entre instancias del flujo.

Si el flujo de trabajo es conocido pero variable → tienes dos opciones:

Flujo de trabajo secuencial con ramificación explícita: escribe cada variante como una rama; enruta hacia ella de forma determinista (a menudo mediante una pequeña llamada al LLM que solo clasifica el tipo de entrada y luego enruta). Mejor cuando las variantes son pocas y estables.
Tratar la ruta como efectivamente desconocida: procede a Q3 y deja que el razonamiento agéntico maneje la variación. Mejor cuando las variantes son muchas o evolucionan.

La heurística pragmática. Si puedes listar las variantes con los dedos de una mano y no cambian a menudo, flujo ramificado. Si no puedes, patrón agéntico.

Idea central: Q2 pregunta si la ruta conocida también es estable entre las entradas que esperas. Las rutas estables van a flujos de trabajo secuenciales. Las rutas conocidas pero variables van a flujos con ramificación explícita (pocas variantes estables) o a patrones agénticos (variantes muchas o cambiantes). La trampa es tratar "el 80% del caso es fijo" como "fijo"; el 20% crece hasta convertirse en parches que dominan el diseño original.

Concepto 6: Q3: ¿La estructura de la tarea es articulable antes de ejecutar?

Respondiste Q1 con "la ruta es desconocida"; se necesita razonamiento agéntico. Q3 hace la siguiente pregunta: ¿la estructura de alto nivel del trabajo es articulable de antemano, aunque los pasos específicos no lo sean?

Qué significa "estructura" aquí. No los pasos en sí: esos, por Q1, son desconocidos. Las etapas y sus dependencias. Ejemplo: un agente de investigación de mercado. No puedes especificar los pasos de antemano (qué fuentes consultar, qué competidores investigar, qué análisis ejecutar depende de lo que encuentres). Pero sí puedes articular la estructura: recopilar datos → analizar → sintetizar → informar. Cuatro etapas, en ese orden, con dependencias claras. Eso es estructura articulable.

Contraste: un agente de soporte al cliente que maneja "tengo un problema". El agente investiga. Según lo que encuentre, el trabajo puede requerir búsqueda de cuenta, luego búsqueda en base de conocimiento, luego una verificación de política, luego escalamiento; o quizá nada de eso, solo una redirección rápida. No puedes articular etapas porque el trabajo no encaja en una estructura por fases; es investigación que termina cuando termina. Eso no es articulable.

La prueba. Intenta dibujar el trabajo como un diagrama de fases antes de ver una entrada específica. ¿Puedes nombrar las fases principales y sus dependencias?

Sí, las fases están claras (recopilar → analizar → sintetizar; o diseñar → implementar → probar; o investigar → redactar → revisar) → la estructura es articulable; usa planificación.
No, el trabajo no encaja en fases; es investigación, iteración o exploración abierta → la estructura no es articulable; usa ReAct.

Dónde se equivocan los equipos. Inventar estructura donde no existe. Los ingenieros sienten que siempre debería ser posible un plan, así que lo fuerzan. El planificador genera un plan; la ejecución diverge de inmediato porque la tarea no tenía realmente esas fases. El equipo entonces (a) trata la divergencia como un bug del planificador ("el planificador produjo un mal plan"; reescribe el planificador; repite) o (b) acorta gradualmente el plan hasta que se vuelve trivial y no aporta nada. La respuesta honesta era "esta tarea no necesitaba un plan; usa ReAct".

El error opuesto: perder estructura que sí existe. Los ingenieros usan ReAct puro para tareas que realmente tienen fases. El agente divaga, vuelve a trabajo resuelto o pierde el hilo del progreso global. Añadir "recuerda hacer estas fases" a la indicación es un parche; el arreglo arquitectónico es añadir planificación encima del bucle ReAct.

La ruta. Si la estructura es articulable → Planificación + ejecución ReAct. El agente de planificación produce la estructura de fases; ReAct se ejecuta dentro de cada fase para manejar la adaptación de pasos desconocidos que Q1 identificó.

Si la estructura no es articulable → Agente único + ReAct + herramientas. El agente razona sobre el estado actual, toma la siguiente acción, observa el resultado y repite: sin una capa de estructura más allá de la que el propio agente mantiene.

Una heurística que vale la pena internalizar. La planificación ayuda cuando la forma del trabajo es predecible pero el contenido no. ReAct solo es correcto cuando incluso la forma depende de lo que descubres. La distinción forma frente a contenido es la manera más limpia de diferenciarlos.

🔍 La confusión Q2 frente a Q3, desambiguación con ejemplos

Q2 ("¿el flujo de trabajo es fijo y estable?") y Q3 ("¿la estructura de la tarea es articulable?") confunden incluso a equipos experimentados. Ambas preguntan por predictibilidad; la diferencia es qué tipo de predictibilidad:

Pregunta Qué pregunta Qué significa "sí" A qué enruta "sí"
Q2 ¿Los pasos en sí están fijos entre runs? La misma secuencia de llamadas a funciones Python produce la respuesta correcta cada vez. Sin decisiones impulsadas por LLM sobre qué hacer después. Flujo de trabajo secuencial
Q3 ¿Las etapas principales son articulables de antemano, aunque el trabajo a nivel de paso varíe? Puedes describir la estructura de fases en una pizarra antes de ver una entrada específica. El LLM aún decide qué hacer dentro de cada etapa. Planificación + ejecución ReAct

La confusión que muerde: los ingenieros ven estructura en la tarea ("claramente hay etapas: investigar, analizar, escribir") y responden SÍ a Q2. Pero "existe estructura" es la pregunta de Q3, no de Q2. Q2 pregunta si puedes predecir la secuencia exacta de pasos en runtime; si el agente aún necesita tomar decisiones dentro de cada etapa (qué fuentes, qué análisis, qué encuadres), la respuesta a Q2 es NO y deberías estar en Q3.

Tres ejemplos de frontera que distinguen Q2 de Q3:

Ejemplo A, ingreso de facturas (Q2 = SÍ → flujo de trabajo secuencial): extraer → validar → almacenar → notificar. Los mismos cinco pasos cada vez. El LLM extrae campos y escribe la notificación, pero no decide qué hacer después. La secuencia de pasos es fija.

Ejemplo B, informe de investigación de mercado (Q2 = NO, Q3 = SÍ → planificación + ReAct): recopilar datos → analizar → sintetizar → redactar → revisar. Las etapas son articulables, pero dentro de cada etapa el agente decide qué hacer (qué fuentes consultar, en qué competidores enfocarse, qué análisis ejecutar). Las etapas son fijas; los pasos dentro de las etapas son adaptativos.

Ejemplo C, investigación de soporte al cliente (Q2 = NO, Q3 = NO → agente único + ReAct): el agente investiga el problema del cliente. No hay estructura de fases predeterminada: según lo que encuentre, el trabajo puede ser una consulta o cinco consultas más una verificación de política más un escalamiento. Ni las etapas ni los pasos son fijos.

Observa que el ejemplo B es el caso que las decisiones de la Parte 5 solo ejercitan parcialmente. Si te ves queriendo decir tanto "esto tiene fases claras" como "el planificador produjo un plan del que la ejecución siguió divergiendo", estás en la frontera Q2/Q3, y la respuesta casi siempre es Planificación + ReAct, no flujo de trabajo secuencial.

El subcaso conocido pero variable de Q2 (vale la pena nombrarlo). A veces Q1 = SÍ (la ruta es conocida) pero Q2 = NO (variable entre entradas), por ejemplo, el flujo tiene 3-4 variantes estables según el tipo de entrada (consulta rápida frente a síntesis de varias fuentes frente a análisis de documento). Eso no es un caso de flujo de trabajo secuencial NI de planificación + ReAct; es un flujo de trabajo ramificado con enrutamiento explícito por tipo de entrada. El Concepto 5 lo cubre; la variante de la Decisión 4 en la galería de antipatrones (la fila del Concepto 16.5 sobre "añadir planificación a un flujo estable") cubre el fallo inverso.

Pregunta	Qué pregunta	Qué significa "sí"	A qué enruta "sí"
Q2	¿Los pasos en sí están fijos entre runs?	La misma secuencia de llamadas a funciones Python produce la respuesta correcta cada vez. Sin decisiones impulsadas por LLM sobre qué hacer después.	Flujo de trabajo secuencial
Q3	¿Las etapas principales son articulables de antemano, aunque el trabajo a nivel de paso varíe?	Puedes describir la estructura de fases en una pizarra antes de ver una entrada específica. El LLM aún decide qué hacer dentro de cada etapa.	Planificación + ejecución ReAct

Idea central: Q3 pregunta si la estructura de alto nivel de la tarea (etapas y dependencias) es articulable antes de ejecutar. La estructura articulable enruta a planificación + ejecución ReAct (el plan da forma; ReAct maneja contenido desconocido dentro de cada etapa). La estructura no articulable enruta a ReAct puro + herramientas (el agente descubre forma y contenido adaptativamente). Las trampas son inventar estructura donde no existe (planes forzados de los que la ejecución diverge) y no ver estructura que sí existe (ReAct puro en trabajo por fases, lo que lleva a divagación).

Concepto 7: Q4: ¿La calidad importa más que la velocidad, con criterios verificables?

Q4 es la primera de dos preguntas de capa adicional. El patrón central (flujo de trabajo secuencial, ReAct o planificación + ReAct) ya fue elegido por Q1-Q3. Q4 pregunta si debes añadir reflexión encima.

Qué hace la reflexión. Después de que el agente produce una salida, un pase de crítica la evalúa contra criterios explícitos. Si la crítica identifica defectos, el agente refina (o regenera). La apuesta del patrón (del Concepto 2): un pase de crítica puede atrapar errores que el generador omitió, y los criterios de "buena salida" son lo bastante explícitos para que la crítica sea significativa.

Las dos condiciones que deben cumplirse para que la reflexión valga la pena.

La calidad importa más que la velocidad. La reflexión añade al menos una llamada adicional al LLM (la crítica) y a menudo dos (crítica + refinamiento). Para casos interactivos donde importa la latencia (soporte al cliente en tiempo real, agentes conversacionales), este costo suele ser prohibitivo. Para casos por lotes donde la salida la revisan humanos o se envía a sistemas posteriores (generación de informes, generación de código, redacción de documentos), la latencia suele ser aceptable. Prueba: ¿una respuesta 2-5× más lenta sería aceptable a cambio de una mejora significativa de calidad?
Los criterios de evaluación son explícitos y verificables. Criterios vagos producen críticas vagas. "Asegúrate de que esto sea bueno" no es un criterio. "Verifica que el SQL parsee, toque solo las tablas listadas y no use SELECT *" sí lo es. Sin criterios explícitos, el pase de crítica se convierte en charla verbosa que no mejora la salida, y a menudo produce falsa confianza en que "la IA lo revisó" cuando en realidad no se revisó nada.

Ambas condiciones importan por igual. Añadir reflexión a una tarea sensible a latencia desperdicia tiempo. Añadir reflexión a una tarea con criterios vagos produce teatro. Ambos fallos son comunes; ambos vienen de saltarse Q4 y añadir reflexión porque suena riguroso.

La prueba. Haz dos preguntas:

Si esta respuesta tardara 3-5× más en producirse, ¿mis usuarios (o los consumidores posteriores) estarían de acuerdo con eso, dada una mejora significativa de calidad? Si no, la reflexión no se justifica por presupuesto de latencia.
¿Puedo escribir, en 5-10 viñetas específicas, exactamente qué significa "buena salida" para esta tarea, de modo que un LLM distinto pueda leer esas viñetas y comprobar la salida contra ellas? Si no, la reflexión no se justifica por claridad de criterios.

Si ambas respuestas son sí, la reflexión aporta valor. Si cualquiera es no, omite la reflexión.

Dónde se equivocan los equipos.

Añadir reflexión porque los críticos suenan rigurosos. "Genera y luego critica" suena como buena ingeniería. A menudo lo es; a veces es solo puesta en escena. La prueba es si la crítica cambia realmente la salida de formas medibles. Si añadiste reflexión y la salida posterior a la reflexión es idéntica a la salida previa 90% del tiempo, la reflexión no está haciendo trabajo; está añadiendo costo.

Usar el mismo modelo y estilo de indicación para generador y crítico. El crítico tiene los mismos datos de entrenamiento, los mismos sesgos, los mismos puntos ciegos que el generador. Tiende a aprobar mecánicamente. Los patrones de reflexión efectivos (a) usan un modelo distinto para el crítico, (b) encuadran al crítico con una perspectiva fundamentalmente distinta ("eres un revisor estricto que busca problemas" frente al encuadre servicial del generador) o (c) dan al crítico herramientas explícitas de comprobación (ejecutar el SQL, parsear el JSON, validar contra el esquema).

Reflexionar sobre tareas sin salida verificable. La reflexión funciona en tareas donde la incorrección está definida: SQL con errores, código que no compila, resúmenes que omiten hechos clave de la fuente. Funciona mal en tareas donde "bueno" es subjetivo: copy de marketing, escritura creativa, respuestas conversacionales. Los dominios subjetivos se benefician más de revisión human-in-the-loop que de reflexión con LLM.

La ruta. Si ambas condiciones se cumplen, añade reflexión como capa encima del patrón central de Q1-Q3. Esto no reemplaza el patrón central; lo envuelve. Un flujo de trabajo secuencial con reflexión ejecuta el flujo y luego critica la salida final. Un agente ReAct con reflexión completa su bucle y luego critica la salida final. La reflexión es control de calidad posterior, no reemplazo del patrón central.

Si cualquiera de las condiciones falla, omite la reflexión. Si realmente necesitas aseguramiento de calidad pero los criterios no son verificables, el arreglo correcto es revisión humana, no reflexión con LLM.

Idea central: Q4 pregunta si la calidad importa más que la velocidad Y si los criterios de evaluación son explícitos y verificables. Ambas condiciones deben cumplirse para que la reflexión aporte valor. La reflexión en tareas sensibles a latencia desperdicia tiempo; la reflexión en tareas con criterios vagos produce teatro. Los dos modos de fallo más comunes son añadir reflexión porque suena rigurosa (sin comprobar si cambia la salida) y usar el mismo modelo y estilo de indicación para generador y crítico (lo que produce aprobación mecánica). Cuando se justifica, la reflexión se añade encima del patrón central; no lo reemplaza.

Concepto 8: Q5: ¿Hay un cuello de botella de especialización, contexto o escala?

Q5 es la segunda pregunta de capa adicional, y la más consecuente porque los sistemas multiagente son el patrón más caro de construir y el más caro de retirar si resultan ser incorrectos.

Qué apuestan los sistemas multiagente. Tres afirmaciones distintas, a menudo confundidas:

Afirmación de especialización: la tarea requiere expertise distinta que un agente único no puede sostener bien en una indicación. Un programador, un revisor de seguridad y un redactor de documentación tienen indicaciones óptimas distintas, herramientas óptimas distintas y criterios de evaluación óptimos distintos. Intentar meter los tres en un agente produce mediocridad en los tres.
Afirmación de contexto: la tarea requiere más contexto del que un agente único puede usar eficazmente. Aunque la ventana de contexto sea técnicamente suficiente, la recuperación y el razonamiento se degradan cuando crece el contexto. Dividir el trabajo entre agentes, cada uno con su propio contexto enfocado, preserva la calidad del razonamiento.
Afirmación de escala: la tarea involucra trabajo que puede ejecutarse en paralelo, y un sistema multiagente puede hacerlo más rápido que un agente secuencial único. Investigar 10 competidores simultáneamente vence a investigarlos uno por uno.

Cada afirmación debe probarse por separado, contra la tarea real.

La afirmación de especialización es la que más a menudo se cree sin evidencia. Los ingenieros ven una tarea como "construir una función" y la descomponen en roles (arquitecto, programador, tester, revisor) porque se siente intuitivo. La intuición se equivoca tan a menudo como acierta. Construir funciones reales a menudo funciona mejor en un agente único con buen acceso a herramientas; la separación arquitecto-programador-tester introduce costos de handoff que superan la ganancia de especialización. Prueba la afirmación: ¿el trabajo mejoraría de forma significativa si un especialista de dominio se enfocara solo en esta porción?

La afirmación de contexto es más a menudo verdadera a escala. Un agente único que hace diez recuperaciones en diez bases de conocimiento acumula contexto que degrada el razonamiento. Dividirlo en diez agentes de recuperación y resumen que producen briefs enfocados, y luego componer los briefs, suele rendir mejor porque el contexto de cada agente de recuperación permanece pequeño y enfocado. Pero esto es una decisión arquitectónica real, no un valor predeterminado.

La afirmación de escala es la más fácil de probar: ¿la ejecución paralela proporciona una mejora de throughput medible y la tarea se paraleliza limpiamente? Si el trabajo tiene dependencias secuenciales estrictas (cada paso necesita la salida del anterior), la ejecución multiagente paralela añade costo de coordinación sin comprar velocidad.

La prueba. Tres subpreguntas:

¿Puedo nombrar la expertise específica que justifica a un especialista? "Sería más limpio" no cuenta. "El revisor necesita aplicar estándares OWASP que el programador no debería tener que aprender" sí cuenta. Si no puedes nombrar la expertise, la afirmación de especialización probablemente es estética.
¿El contexto de la tarea excederá lo que un agente único puede usar eficazmente? En general sí si la tarea requiere varias bases de conocimiento distintas, investigaciones largas en muchas fuentes o conjuntos de herramientas especializados por fase. En general no si el contexto cabe en una indicación bien gestionada.
¿El trabajo se paraleliza de verdad, con mejora medible de throughput? Si el trabajo es secuencial (cada paso depende del anterior), paralelizar no ayuda. Si el trabajo es genuinamente independiente (investigar 10 competidores, evaluar 10 candidatos, resumir 10 documentos), la paralelización proporciona valor real.

Si al menos una subpregunta recibe un sí fuerte, multiagente está justificado. Si las tres reciben "tal vez" o "sería agradable tener agentes separados por razones organizativas", quédate con el patrón de agente único. La sobrecarga de coordinación es real y sustancial.

Dónde se equivocan los equipos.

Construir sistemas multiagente por razones organizativas. "Tenemos tres equipos trabajando en esto; tengamos tres agentes." Esto hace que la arquitectura de agentes copie el organigrama. Casi siempre es incorrecto. Los sistemas multiagente deben diseñarse alrededor de propiedades de la tarea, no de límites de equipo. (Tres equipos pueden colaborar en un agente; la estructura organizativa y la estructura del agente no tienen que coincidir).

Subestimar el costo de coordinación. Cada handoff entre agentes introduce un punto de serialización (la salida de un agente se vuelve entrada de otro), un punto potencial de fallo (el formato de handoff puede no coincidir) y una dificultad de depuración (cuando algo sale mal, ¿qué agente lo causó?). Los sistemas multiagente son aproximadamente un orden de magnitud más caros de depurar que los sistemas de agente único: inclúyelo en tu razonamiento sobre si el costo está justificado.

Construir multiagente para demostrar sofisticación. Este es el modo de fallo de charlas y demos. Los sistemas multiagente se ven impresionantes en diagramas de arquitectura; muestran "IA real". Si la tarea real no los justifica, construiste sobrecarga impresionante.

La ruta. Si la especialización, el contexto o la escala crean un cuello de botella real → Sistema especialista multiagente. El sistema puede tener un agente coordinador/de enrutamiento más especialistas, o especialistas con contratos explícitos de handoff, o especialistas que se comunican mediante estado compartido. El patrón central (flujo secuencial, ReAct, planificación + ReAct) aún aplica dentro del dominio de cada especialista; multiagente es una composición de patrones, no un reemplazo.

Si no existe un cuello de botella real → mantén el patrón de agente único. Añade reflexión (Q4) si esas condiciones se cumplen, pero no añadas multiagente por razones estéticas.

Disparadores cuantitativos para Q5, métricas concretas que activan la decisión multiagente. "Cuello de botella de especialización, contexto o escala" es por defecto una cuestión de juicio, y en el juicio se infiltra el sobredimensionamiento de patrones. Siempre que puedas, reemplaza juicio por medición. Los disparadores siguientes son reglas prácticas que mueven Q5 de subjetivo ("se siente como especialistas") a defendible ("medimos X y X supera el umbral").

Afirmación de cuello de botella	Disparador cuantitativo que justifica la actualización	Qué mide la métrica
Especialización	Las trazas de agente único muestran errores de enrutamiento de herramientas concentrados en dominios de conocimiento específicos (como umbral de trabajo aproximado, en el orden de un tercio de los runs en la categoría afectada, calibrado a tu propia línea base). Ejemplo: un agente unificado de facturación+técnico elige la herramienta equivocada en una proporción considerable de consultas técnicas porque la terminología de facturación domina su contexto.	Corrección de herramienta por traza, segmentada por categoría de consulta: el evaluador Phoenix de tu suite de evals
Especialización (fallback cualitativo)	¿No se puede medir? Exige una especificación escrita de los roles especialistas antes de la actualización: responsabilidades, herramientas y criterios de aceptación de cada rol en lenguaje claro. Si la especificación es vaga o los roles se solapan >40% en responsabilidad, la afirmación de especialización es estética, no arquitectónica.	Revisión documental, no métrica
Desborde de contexto	La exactitud en un conjunto holdout se degrada de forma material a medida que crece el contexto (mide tu propia curva; como bandera aproximada, vale investigar una caída de unos 10 puntos en un barrido de 15K → 45K tokens). Ejemplo: un agente de investigación que carga 25 documentos fuente muestra 78% de exactitud a 15K de contexto, 71% a 30K, 62% a 45K.	Curva contexto-frente-a-exactitud en el dataset golden
Escala (paralelizable)	El trabajo tiene >5 subtareas independientes por run Y la latencia de ejecución de agente único excede el presupuesto de latencia de cara al usuario por >2×. Ejemplo: investigar 10 competidores → el agente único tarda 8 minutos secuencialmente, el presupuesto es 3 minutos → la ejecución multiagente paralela es la única ruta que encaja.	Latencia de extremo a extremo + análisis de independencia de subtareas
Escala (throughput)	El volumen de runs supera 10× el techo de rate limit de un diseño de agente único Y ninguna limitación de concurrencia por tenant puede preservar la equidad. Ejemplo: 5K runs/día por tenant contra una cuota de OpenAI de 500 RPM requiere fan-out entre varias identidades de agentes o descomposición estilo especialistas.	Carga de producción × límites de API: visible en los paneles de control de flujo de la capa operativa

La jerarquía de evidencia. De la justificación más fuerte a la más débil para multiagente:

Datos de trazas de producción que muestran el cuello de botella (mejor: tienes evidencia de que el sistema de agente único falla realmente de esta forma)
Mediciones en conjunto holdout que muestran el cuello de botella (fuerte: un experimento controlado)
Análisis de dominio con especificaciones escritas de roles especialistas (aceptable: al menos definiste lo que estás construyendo)
"Se siente como especialistas" (insuficiente: ahí vive el sobredimensionamiento de patrones)

Un autochequeo útil. "¿Cuál es el diseño de agente único más pequeño que podríamos entregar primero, y qué fallo específico nos obligaría a multiagente después?" Si la respuesta es "descubriríamos X patrón de fallo en trazas de producción", entrega primero agente único y deja que el disparador de actualización se active cuando se active. Multiagente rara vez es el destino equivocado; casi siempre es el punto de partida equivocado.

Idea central: Q5 pregunta si la especialización, el contexto o la escala crean un cuello de botella real que justifica arquitectura multiagente. Cada una de las tres afirmaciones (especialización, contexto, escala) debe probarse por separado y, cuando sea posible, contra disparadores cuantitativos (umbrales ilustrativos, calibrados a tu sistema: aproximadamente un tercio de runs con errores de enrutamiento de herramientas, una caída de exactitud de unos 10 puntos con más contexto, latencia que supera el presupuesto por más de 2×). La especialización es la que más se cree sin evidencia; el contexto es más a menudo realmente cierto a escala; la escala es la más fácil de probar. El mayor modo de fallo es construir sistemas multiagente por razones organizativas o estéticas en lugar de propiedades de la tarea; la sobrecarga de coordinación es real y sustancial, y retirar un sistema multiagente desplegado es una reescritura, no un refactor. Empieza con agente único; deja que disparadores medidos fuercen la actualización.

Concepto 8.5: Las primitivas de OpenAI Agents SDK, qué usa cada patrón

Antes de que la Parte 3 recorra los cinco patrones, aquí está el puente desde la selección de patrones de vuelta a la implementación. Los cursos anteriores enseñaron OpenAI Agents SDK como framework ancla. Los patrones de este curso no son formas arquitectónicas abstractas que reimplementas desde cero; son formas que compones usando primitivas del SDK que ya conociste. Este concepto asigna cada patrón a las primitivas específicas del SDK que lo construyen.

Las cinco primitivas que importan para selección de patrones.

Primitiva	Qué es	Qué patrones la usan
`Agent`	La clase central, una entidad impulsada por LLM con instrucciones, herramientas y esquema opcional de salida estructurada. La unidad atómica de cada patrón.	Los cinco patrones
`Runner.run(agent, input)`	Ejecuta un bucle de agente hasta que produce salida final. El SDK ejecuta el bucle por ti: sin ciclo razonar-actuar-observar escrito a mano.	Agente único + ReAct (el caso más visible), planificación + ReAct, multiagente (por especialista)
`@function_tool`	Decorador que convierte una función Python en una herramienta que el agente puede llamar. Las firmas de tipo y docstrings se vuelven automáticamente el esquema de la herramienta.	Agente único + ReAct, planificación + ReAct, multiagente (por especialista), flujo secuencial (cuando el paso LLM necesita herramientas)
`handoff(target_agent)`	Primitiva de primera clase del SDK para transiciones multiagente: un agente entrega explícitamente el control a otro con el contexto de conversación preservado. Más limpio que escribir un coordinador propio.	Multiagente (uso principal); planificación + ReAct (planificador a ejecutor)
`output_guardrail` / `input_guardrail`	Primitivas del SDK para ejecutar pases de validación/crítica sobre la entrada o salida de un agente. El patrón nativo del SDK para reflexión.	Reflexión (uso principal); cualquier patrón que necesite validación de entrada

Una primitiva más que vale la pena nombrar: Agent.as_tool(). Convierte un Agent en una herramienta invocable que otro Agent puede llamar. Es el mecanismo del SDK para composición multiagente jerárquica (un agente coordinador usa agentes especialistas como herramientas, llamándolos como cualquier otra function tool). Los sistemas multiagente con Agent.as_tool() son más simples que los sistemas multiagente con handoff() porque el coordinador mantiene el control; handoff() es para situaciones en las que realmente quieres que el especialista tome el control de la conversación.

El mapeo patrón → primitiva de un vistazo.

Sequential workflow:
    Agent(output_type=...) at the LLM-steps; plain Python everywhere else
    Runner.run() called once per LLM-step: no agentic loop (the agent has no tools)

Single agent + ReAct + tools:
    Agent(instructions=..., tools=[@function_tool, @function_tool, ...])
    Runner.run(agent, input): the SDK runs the reason-act-observe loop

Planning + ReAct execution:
    planner = Agent(output_type=PlanSchema)
    plan = await Runner.run(planner, task)
    for stage in plan.stages:
        result = await Runner.run(stage.agent, stage.input)

Single agent + reflection:
    Agent(..., output_guardrails=[critic_guardrail])
    OR: Agent(..., tools=[Agent.as_tool(critic_agent)])

Multi-agent specialist system:
    coordinator = Agent(handoffs=[researcher, writer, reviewer])
    OR: coordinator = Agent(tools=[researcher.as_tool(), writer.as_tool(), ...])

Los bloques de código de la Parte 3 que siguen muestran cada una de estas formas con detalle completo del SDK.

Por qué este mapeo importa para la selección de patrones. Las primitivas del SDK no son solo comodidades de implementación; codifican decisiones arquitectónicas. Elegir handoff() frente a as_tool() es en sí una decisión de composición de patrones. handoff() significa "el especialista toma el control de la conversación"; as_tool() significa "el coordinador sigue al mando y usa al especialista como función". Lo primero es apropiado cuando el especialista necesita interactuar directamente con el usuario; lo segundo es apropiado cuando el coordinador compone salidas de especialistas. Saber cuál elegir está aguas abajo de la misma disciplina de selección de patrones que enseña este curso.

La conexión con el ejemplo trabajado. El Worker de soporte al cliente (el agente de soporte de nivel 1 de Maya) usa Agent + @function_tool (para búsqueda, reembolso y escalamiento) + Runner.run() (en el handler FastAPI). Es un patrón de agente único + ReAct + herramientas, exactamente lo que el Concepto 10 recorrerá en detalle del SDK. La implementación de Maya es uno de los cinco patrones de este curso; los otros cuatro son variaciones a las que recurres cuando cambian las propiedades de la tarea.

Idea central del Concepto 8.5: las primitivas del SDK son los bloques de construcción de los cinco patrones. Agent es la unidad atómica; Runner.run() ejecuta el bucle; @function_tool expone funciones Python como herramientas; handoff() y as_tool() componen agentes en sistemas multiagente; output_guardrail implementa reflexión. El mapeo patrón → primitiva vuelve concretas las decisiones arquitectónicas de este curso: la selección de patrones no es abstracta; es una elección sobre qué primitivas del SDK componer y cómo.

Concepto 8.6: Consideraciones de capa operativa por patrón (con Inngest como ejemplo concreto)

📖 Nota para lectores independientes. Este concepto trata las consecuencias operativas de elegir un patrón, no enseña Inngest. El argumento arquitectónico se generaliza a cualquier plataforma de ejecución durable (Temporal, Restate, Dapr Agents, AWS Step Functions); Inngest es el ejemplo concreto porque es lo que enseña el curso de capa operativa. Si tienes otra plataforma, o si sigues en etapa de diseño con la plataforma operativa sin decidir, lee buscando el argumento de arquitectura de patrón: cuanto más elaborado es el patrón, más depende de tener una capa operativa. Sustituye las primitivas de tu plataforma por las de Inngest.

El Concepto 8.5 mapeó los patrones a primitivas del motor (OpenAI Agents SDK). El Concepto 8.6 mapea los patrones a primitivas de capa operativa: la maquinaria de runtime que hace que el bucle del agente sobreviva a fallos, escale a muchos usuarios concurrentes e integre con el mundo que dispara eventos hacia él. El SDK ejecuta el bucle del agente; la capa operativa vuelve ese bucle apto para producción. Cada patrón usa primitivas operativas distintas, y cuanto más elaborado es el patrón, más depende de la capa operativa.

En la ruta Agent Factory, la capa operativa es Inngest. Las primitivas de abajo son de Inngest; el argumento arquitectónico subyacente es general.

Las primitivas de capa operativa que importan para la selección de patrones.

Primitiva	Qué es	Qué patrones la usan más
`@inngest_client.create_function`	Decorador que registra una función con el runtime de ejecución durable. La unidad de trabajo gestionado operativamente.	Los cinco patrones
`TriggerEvent`, `TriggerCron`	Superficies de disparo: eventos que dispara el mundo, horarios que despiertan la función. El agente no se ejecuta cuando tú lo llamas; se ejecuta cuando el mundo dispara el trigger.	Los cinco patrones; cron es más relevante para respuesta a incidentes y flujos por lotes
`ctx.step.run(name, fn, ...)`	Cada llamada es un checkpoint durable; los pasos completados devuelven salida memoizada en reintentos; los pasos fallidos reintentan de forma independiente. La mecánica debajo de la confiabilidad de producción.	Flujo de trabajo secuencial (mapeo más directo), planificación + ReAct (un step.run por etapa), reflexión (pasos separados de generador/crítico)
`ctx.step.wait_for_event(...)`	La función se suspende de forma durable, con cero cómputo consumido, hasta que llega un evento coincidente o se dispara un timeout. La primitiva de runtime detrás de las puertas HITL.	Cualquier patrón que necesite aprobación humana; multiagente (entre especialistas); reflexión (cuando el juicio humano es el crítico)
`concurrency`, `throttle`, `priority`	Políticas de control de flujo por función. Concurrency limita runs activos; throttle limita inicios/seg; priority ordena la cola; la concurrencia por clave da equidad multitenant.	Multiagente (más crítico, los límites por especialista evitan agotar rate limits); cualquier patrón de agente único de alto volumen
Disparadores fan-out	Un evento despierta N funciones suscritas; o un padre dispara N eventos hijos. La primitiva de runtime detrás de la ejecución paralela de especialistas.	Multiagente (topología paralela); planificación + ReAct (cuando las etapas se ejecutan en paralelo)
Replay + dead-letter	Los runs fallidos persisten; entrega un arreglo, haz clic en replay, la función se reanuda desde el paso fallido con código nuevo. Los pasos previos al fallo quedan memoizados.	Todos los patrones, pero cuanto más elaborado es el patrón, más importa replay porque más está en juego cuando un run largo falla a mitad

El mapeo patrón → primitiva de un vistazo.

Sequential workflow:
    @inngest_client.create_function(trigger=TriggerEvent(...))
    async def workflow(ctx):
        a = await ctx.step.run("extract", extractor_agent.run, ...)
        b = await ctx.step.run("validate", validate, a)
        c = await ctx.step.run("store", db.insert, b)
        await ctx.step.run("notify", notifier_agent.run, ...)
    # Each step independently checkpointed; failure → memoized resume

Single agent + ReAct + tools:
    @inngest_client.create_function(
        trigger=TriggerEvent(event="customer/email.received"),
        concurrency=[Concurrency(limit=10, key="event.data.customer_id")],
    )
    async def support(ctx):
        result = await ctx.step.run("agent-loop", Runner.run, support_agent, ctx.event.data["query"])
        # If agent needs HITL escalation, use step.wait_for_event inside the agent's tool
        return result.final_output

Planning + ReAct execution:
    @inngest_client.create_function(trigger=TriggerEvent(event="research/started"))
    async def planning(ctx):
        plan = await ctx.step.run("plan", Runner.run, planner, ctx.event.data["task"])
        results = {}
        for stage in plan.stages:
            # Each stage = one step.run. Crash mid-stage → only that stage retries.
            results[stage.id] = await ctx.step.run(f"stage-{stage.id}", Runner.run, stage.agent, ...)
        return await ctx.step.run("synthesize", Runner.run, synthesizer, results)

Single agent + reflection:
    @inngest_client.create_function(trigger=TriggerEvent(...))
    async def reflective(ctx):
        output = await ctx.step.run("generate", Runner.run, generator, ctx.event.data["task"])
        critique = await ctx.step.run("critique", Runner.run, critic, output)
        if not critique.final_output.is_safe:
            output = await ctx.step.run("refine", Runner.run, generator, refine_prompt(output, critique))
        return output

Multi-agent specialist system:
    # Coordinator triggers fan-out of specialist events
    @inngest_client.create_function(trigger=TriggerEvent(event="research/landscape.requested"))
    async def coordinator(ctx):
        plan = await ctx.step.run("plan", Runner.run, planner, ctx.event.data["topic"])
        await ctx.step.run("fan-out", fan_out_specialist_events, plan.competitors)
        # Each specialist runs independently as its own function:

    @inngest_client.create_function(
        trigger=TriggerEvent(event="research/competitor.research"),
        concurrency=[Concurrency(limit=5, key="event.data.tenant_id")],  # per-tenant cap
    )
    async def competitor_research(ctx):
        return await ctx.step.run("research", Runner.run, researcher, ctx.event.data["target"])

Los recuadros de la Parte 3 que siguen muestran cada uno de estos mapeos con una sección explícita de capa operativa por patrón.

Por qué este mapeo importa para la selección de patrones. Dos modos de fallo de producción que no son visibles al nivel del diagrama de arquitectura, pero pegan fuerte en producción:

Fallo a mitad de ejecución. Una ejecución de planificación + ReAct de seis pasos que falla en el paso 4 (sin ejecución durable) vuelve a pagar por los primeros tres pasos. El curso de capa operativa cuantifica esto: con precios clase GPT-5, un flujo de agente multietapa puede volver a pagar aproximadamente $0.10-$2.00 por run fallido. A 1000 runs/día, eso es del orden de $30-$600/mes en trabajo perdido solo por fallos. Los flujos de trabajo secuenciales sobreviven barato a fallos porque los reintentos son cortos; los sistemas multiagente + reflexión sobreviven caro porque los reintentos son largos. Cuanto más elaborado el patrón, más vale en dólares la memoización step.run de la capa operativa.
Coordinación a escala. Un sistema multiagente con cinco especialistas, diez tenants y ráfagas de 100 eventos/minuto agotará rate limits sin límites de concurrencia por especialista. La capa operativa convierte esto en una línea: concurrency=[Concurrency(limit=5, key="event.data.tenant_id")]. El árbol de decisión de este curso elige el patrón; las primitivas de control de flujo de la capa operativa mantienen saludable el patrón elegido a escala.

La composición de despliegue. La capa operativa (Inngest) y tu despliegue en la nube componen; no compiten. El curso de despliegue en la nube enseña la topología de nube: ACA + Neon + R2 + Cloudflare Sandbox + Phoenix. El curso de capa operativa enseña la capa que envuelve el runner del SDK dentro de esa topología. Un sistema real de producción usa ambos: funciones de Inngest desplegadas en ACA, llamando Runner.run() dentro de bloques step.run(), con Neon almacenando las trazas del agente y el sandbox ejecutando código de herramientas. Los recuadros de composición de despliegue de la Parte 3 nombran ambas capas explícitamente.

La composición de evals. La traza estructurada de Inngest (entrada, salida, conteo de reintentos y latencia de cada paso) fluye a Phoenix igual que la traza del agente del SDK, mediante OpenTelemetry. Los patrones de detección de fallos de la suite de evals (anomalías de longitud de traza, divergencia plan-ejecución, aprobación mecánica) funcionan en runs instrumentados con Inngest; la suite de evals no cambia porque se añada la capa operativa.

Idea central del Concepto 8.6: la capa operativa (Inngest) es el sustrato de producción para los cinco patrones. Los disparadores despiertan la función; step.run la vuelve durable; step.wait_for_event implementa puertas HITL; concurrencia, throttle y prioridad le dan forma bajo carga; fan-out coordina especialistas multiagente; replay maneja recuperación tras arreglos de bugs. Cuanto más elaborado es el patrón, más vale la capa: los flujos secuenciales pueden sobrevivir sin ella; los sistemas multiagente + reflexión la necesitan. La capa compone con tu despliegue en la nube y tu suite de evals, no como alternativas sino como capas paralelas de la arquitectura de producción.

Las tres capas, lado a lado. Juntos, los Conceptos 8.5 y 8.6 establecen que cualquier patrón agéntico de producción es una composición de tres capas: la capa operativa (Inngest), el motor (OpenAI Agents SDK) y el despliegue en la nube. El mundo dispara eventos en la parte superior (correos de clientes, webhooks de facturación o Slack o CRM, un horario cron, eventos fan-out de otros Workers, aprobaciones humanas); esos disparadores fluyen hacia abajo por las tres capas. El diagrama de abajo mapea las primitivas de cada capa y qué hace cada una. Vuelve a él cada vez que los recuadros de capa operativa de la Parte 3 se sientan abstractos.

La conclusión: las tres capas se apilan. Inngest (la capa operativa) envuelve el SDK (el motor), y ambos se ejecutan dentro del despliegue en la nube. Este curso elige el patrón; las tres capas convierten el patrón elegido en realidad de producción. Los cinco patrones de la Parte 3 son composiciones de estas tres capas; lo que varía de patrón a patrón es qué primitivas de cada capa se usan. Cuanto más elaborado es el patrón (multiagente con reflexión), más crítica se vuelve la capa operativa, porque coordinación, durabilidad y HITL dejan de ser opcionales.

Prueba con IA, después de la Parte 2. Ya tienes las cinco preguntas. Úsalas en algo real antes de leer los patrones en profundidad. Abre tu sesión de Claude Code u OpenCode y pega:

"Estoy aprendiendo a elegir arquitecturas agénticas. Elige una tarea real de mi trabajo actual para la que podría construir un agente. Pídeme que la describa y luego guíame por las cinco preguntas: Q1 (¿se conoce la ruta de solución?), Q2 (¿el flujo de trabajo es fijo y estable?), Q3 (¿la estructura de la tarea es articulable?), Q4 (¿la calidad supera a la velocidad, con criterios verificables?), Q5 (¿hay un cuello de botella de especialización, contexto o escala?). Cuestióname cuando mi respuesta sea vaga o cuando esté eligiendo un patrón más elaborado de lo que la tarea necesita. Al final, dime qué patrón inicial señalan las respuestas."

Lo que estás aprendiendo. Las cinco preguntas solo se vuelven reflejo cuando las ejecutas sobre una tarea que realmente te importa. Hacer esto una vez, en voz alta, con algo que cuestione respuestas débiles, vale más que leer las próximas diez páginas.

Parte 3: Los cinco patrones en profundidad

La Parte 2 recorrió el árbol de decisión a nivel de pregunta. La Parte 3 lo recorre a nivel de patrón. Para cada uno de los cinco patrones terminales: qué es el patrón, cómo se ve su implementación característica, qué implica para tu topología de despliegue y qué vigila tu suite de evals para detectar cuándo el patrón está mal aplicado.

La composición de despliegue y evals es lo que este curso añade encima. Pocos cursos sobre patrones agénticos enseñan esta capa, porque necesita los cursos de despliegue y evals como base. Si no has hecho esos cursos, lee los recuadros como vistas previas de lo que viene; si ya los hiciste, la composición vuelve operativa la selección de patrones.

Antes de recorrer los patrones uno por uno, aquí está la matriz que resume toda la parte. Cada patrón usa un subconjunto distinto del stack de nube; las diferencias de costo de despliegue son reales y sustanciales. Vuelve a ella mientras los Conceptos 9-13 recorren cada patrón en detalle.

La matriz cruza cada patrón (las columnas) con los componentes de despliegue en la nube que necesita (las filas). Una marca significa necesario; una cruz significa no necesario; una tilde significa condicional.

La disciplina de costos codificada en la selección de patrones: un sistema multiagente con reflexión encima puede costar un múltiplo grande de un flujo de trabajo secuencial para el mismo volumen de tarea (relación ilustrativa, del orden de decenas de veces, no un benchmark medido). Un flujo de trabajo secuencial omite por completo los niveles de sandbox y bridge Worker, así que evita una gran parte de la infraestructura; recurrir a ReAct o multiagente sin justificación paga por capacidad que la tarea no necesita.

La conclusión: el flujo de trabajo secuencial tiene dos marcas claras de "no necesario" (sandbox y bridge Worker), lo que se traduce en bastante menos infraestructura que los patrones agénticos. Multiagente tiene la mayor cantidad de marcadores de expansión (tracing por especialista, configuración de bridge Worker por especialista). La matriz es la disciplina de costos del árbol de decisión, hecha visible.

Concepto 9: Flujo de trabajo secuencial, forma característica, despliegue y señales de eval

Qué es. Un pipeline fijo de pasos donde la salida de cada paso alimenta el siguiente. La ruta es conocida y estable (Q1=sí, Q2=sí). Las llamadas al LLM se reservan para pasos que realmente necesitan interpretación o generación: extracción, resumen, clasificación, no para decidir qué paso viene después.

Implementación característica en OpenAI Agents SDK:

from agents import Agent, Runner
from pydantic import BaseModel

class Invoice(BaseModel):
    vendor: str
    amount_cents: int
    due_date: str
    line_items: list[dict]

class NotificationMessage(BaseModel):
    subject: str
    body: str

# Two narrow agents: each does ONE LLM-step in the workflow.
# Notice: no tools, no agentic loop. Just structured-output extraction.
extractor = Agent(
    name="invoice_extractor",
    instructions="Extract structured invoice fields from the email body. Be strict about field types.",
    output_type=Invoice,
)

notifier = Agent(
    name="notification_writer",
    instructions="Write a brief notification message to the requester, referencing the invoice details.",
    output_type=NotificationMessage,
)

async def invoice_intake_workflow(email_content: str) -> ProcessingResult:
    # Step 1: extraction (SDK Agent with structured output)
    extraction = await Runner.run(extractor, email_content)
    invoice: Invoice = extraction.final_output

    # Step 2: validation (plain Python, no LLM)
    validation = validate_against_db(invoice)
    if not validation.ok:
        return ProcessingResult(status="rejected", reason=validation.reason)

    # Step 3: store (plain Python, no LLM)
    record_id = db.insert(invoice)

    # Step 4: notify (SDK Agent with structured output)
    notif = await Runner.run(notifier, f"Invoice {record_id} from {invoice.vendor} stored. Notify {invoice.requester}.")
    email.send(invoice.requester, notif.final_output.subject, notif.final_output.body)

    return ProcessingResult(status="completed", record_id=record_id)

Observa la forma del SDK: dos instancias estrechas de Agent, cada una haciendo un solo trabajo solo de LLM (extracción, redacción de notificación). Cada agente tiene salida estructurada mediante output_type=, sin parseo de texto libre. Runner.run() se llama dos veces, una por paso LLM. Sin herramientas, sin decoradores @function_tool, sin handoffs, porque el flujo de trabajo no necesita razonamiento agéntico, solo llamadas al LLM incrustadas en Python normal.

La idea del SDK que conviene internalizar: no todo uso de un Agent es "agéntico". Un Agent con output_type= y sin herramientas es la forma idiomática del SDK de "llamar a un LLM con una respuesta tipada", exactamente lo que necesitan los pasos de interpretación de un flujo secuencial. Estás usando el SDK sin usar el bucle de agente.

Composición de despliegue. Los flujos de trabajo secuenciales usan el subconjunto más pequeño del stack de nube:

Primitivas del SDK usadas: Agent (con output_type= para extracción/generación estructurada), Runner.run() para cada paso LLM. Sin @function_tool, sin handoff(), sin as_tool(), sin output_guardrail. El bucle de agente no se usa; Runner.run() devuelve tras una llamada al LLM porque el agente no tiene herramientas.
Harness FastAPI en Azure Container Apps: sí, aún necesitas un servicio HTTP para recibir solicitudes.
Neon Postgres para estado durable: sí, para el registro del flujo de trabajo e idempotencia.
OpenAI API para las llamadas al LLM: sí, pero solo para los pasos específicos que lo necesitan.
Cloudflare R2 para archivos: quizá, solo si el flujo maneja artefactos de archivo.
Cloudflare Sandbox para ejecución: no. Los flujos secuenciales no ejecutan código generado por agentes; ejecutan código determinista con llamadas al LLM incrustadas. La capa de sandbox (y el bridge Worker) no se necesita.

Este es el hallazgo más subestimado sobre los flujos de trabajo secuenciales: no necesitan la mayor parte de la complejidad de despliegue que enseña el curso de despliegue en la nube. Si tu tarea encaja con un flujo secuencial, puedes entregar sobre un stack FastAPI + Postgres + OpenAI y saltarte por completo la infraestructura de sandbox. Ahorro de costos: bastante menos infraestructura que un despliegue agéntico completo, porque omites por completo los niveles de sandbox y bridge Worker. No pagues por capacidad que el patrón no necesita.

Señales de eval. Lo que la suite de evals vigila, específico de flujos secuenciales:

Modo de fallo	Cómo lo atrapa la eval
El paso de extracción lee mal la entrada	Falla la validación de esquema de salida; DeepEval atrapa el desajuste de salida estructurada
La lógica de validación tiene una brecha	Un caso de producción se cuela; la traza muestra un registro válido-pero-incorrecto llegando al almacenamiento
El mensaje de notificación tiene tono incorrecto o error factual	El evaluador inline de Phoenix sobre el mensaje generado lo atrapa; promoción al dataset golden
El flujo maneja un caso para el que no fue diseñado	La suite de DeepEval incluye "entradas de casos límite"; los fallos exponen el límite de suposición del flujo

La idea clave: las evals de flujo secuencial tratan de corrección a nivel de paso, no de calidad de razonamiento del agente. Pruebas cada paso que usa LLM por separado (¿la extracción devuelve el esquema correcto? ¿la generación produce el tono correcto?). Pruebas los puntos de ramificación del flujo (¿la validación atrapa los casos que debe?). No necesitas probar "si el agente eligió la ruta correcta" porque la ruta es fija.

Dónde se equivocan los equipos en producción. Tratar los flujos con LLM incrustado como si fueran agénticos. Los equipos añaden observabilidad diseñada para bucles de agente (tracing de llamadas a herramientas, inspección de pasos de razonamiento) a flujos que no tienen ni llamadas a herramientas ni pasos de razonamiento. Solo necesitas tracing estándar de solicitud/respuesta más validación de salida estructurada por paso. Los dashboards de razonamiento de agentes de Phoenix son excesivos; el tracing estándar de solicitudes de App Insights es el nivel correcto.

Capa operativa. El flujo de trabajo secuencial es el encaje más directo para el modelo de ejecución durable de Inngest. La estructura del patrón (pasos fijos, cada uno puede fallar, dependencias deterministas) es exactamente para lo que están hechas las funciones de Inngest.

Primitivas de Inngest usadas: @inngest_client.create_function para registrar el flujo; TriggerEvent o TriggerCron para la señal de activación; un ctx.step.run("step-name", fn, args) por paso del flujo. Sin step.wait_for_event (no se necesita HITL para un flujo rutinario), sin fan-out (el flujo es lineal), sin control de flujo complejo.
El mapeo 1:1: cada paso del flujo secuencial se convierte en una llamada ctx.step.run dentro de la función de Inngest. El ingreso de facturas de cinco pasos del código del Concepto 9 (extraer → validar → almacenar → notificar) se vuelve cinco llamadas step.run. Fallo en el paso 3 → los pasos 1-2 devuelven salida memoizada, el paso 3 reintenta.
Beneficio de costo: a $0.001-$0.05 por llamada al LLM, un flujo que falla en el paso 5 sin memoización vuelve a pagar los pasos 1-4. Con memoización, solo reintenta el paso 5. El curso de capa operativa cuantifica esto; los ahorros se acumulan a medida que los flujos se alargan.

Flujo secuencial más Inngest es el despliegue agéntico listo para producción más simple del currículo. Muchos flujos reales que se confunden con "sistemas agénticos" deberían ser funciones de Inngest con checkpoints step.run. Q1 del árbol de decisión ("¿se conoce la ruta?") en esencia pregunta si deberías elegir Inngest sin un bucle de agente encima.

*Idea central del Concepto 9: el flujo de trabajo secuencial es el patrón correcto cuando la ruta es conocida y estable. Usa el subconjunto más pequeño del stack de nube (sin sandbox), reserva llamadas al LLM para pasos solo de interpretación y se evalúa a nivel de paso en lugar de razonamiento de agente. El error de producción más común es sobreinstrumentar flujos con observabilidad de grado agente que no necesitan.*

Concepto 10: Agente único + ReAct + herramientas, forma característica, despliegue y señales de eval

Qué es. Un agente que alterna entre razonar sobre su estado actual y tomar una acción (una llamada a herramienta), observa el resultado y repite. La ruta es desconocida (Q1=no) y la estructura no es articulable (Q3=no). La propiedad definitoria: el agente decide qué hacer después según lo que acaba de observar.

Implementación característica en OpenAI Agents SDK:

from agents import Agent, Runner, function_tool

# Tools: plain async Python functions, exposed to the agent via the decorator.
# Type hints and docstrings become the tool's schema automatically.
@function_tool
async def lookup_account(account_id: str) -> dict:
    """Look up an account's current state including balance, plan, and billing status."""
    return await db.accounts.find_by_id(account_id)

@function_tool
async def lookup_transactions(account_id: str, since_days: int = 90) -> list[dict]:
    """Return recent transactions for an account; defaults to last 90 days."""
    return await db.transactions.find(account_id=account_id, since=since_days)

@function_tool
async def issue_refund(transaction_id: str, amount_cents: int, reason: str) -> dict:
    """Issue a refund. Fails if amount exceeds agent's authority ($500). Returns refund_id."""
    return await refund_service.create(transaction_id, amount_cents, reason)

@function_tool
async def escalate_to_human(reason: str, context: dict) -> str:
    """Hand the case to a human reviewer. Returns the escalation ticket id."""
    return await escalation_service.create_ticket(reason, context)

# One Agent with all the tools. The SDK runs the reason-act-observe loop.
support_agent = Agent(
    name="tier1_support",
    instructions=(
        "You are a Tier-1 customer support agent. Investigate the customer's issue "
        "using your tools. Issue refunds only when policy clearly allows and the "
        "amount is under $500. Escalate any ambiguous case. If you cannot determine "
        "the right action within 3 lookups, escalate. State when you are done."
    ),
    tools=[lookup_account, lookup_transactions, issue_refund, escalate_to_human],
)

# The FastAPI handler: exactly the customer-support Worker's shape.
async def handle_support_request(customer_id: str, query: str) -> str:
    result = await Runner.run(
        support_agent,
        input=f"Customer {customer_id} asks: {query}",
        max_turns=25,  # explicit step budget: non-optional in production
    )
    return result.final_output

Observa la forma del SDK: un Agent con varias herramientas, llamado mediante Runner.run(). El SDK ejecuta internamente el bucle razonar-actuar-observar: no escribes for step in range(max_steps): response = llm.chat(...); for tool_call in response.tool_calls: .... El parámetro max_turns es el presupuesto de pasos; el SDK lanza MaxTurnsExceeded cuando se alcanza.

La idea del SDK que conviene internalizar: el bucle ReAct canónico es una llamada a Runner.run(). La complejidad está en las definiciones de herramientas y las instrucciones del agente; la maquinaria del bucle es responsabilidad del SDK. Este es exactamente el patrón detrás del agente de soporte de nivel 1 de Maya, el Worker de soporte al cliente.

Composición de despliegue. ReAct con agente único usa la mayor parte del stack de nube:

Primitivas del SDK usadas: Agent (con tools= e instructions=), decorador @function_tool en cada función Python expuesta como herramienta, Runner.run(agent, input, max_turns=N) para el bucle agéntico. Esta es la forma canónica del SDK, exactamente lo que despliega el Worker de soporte al cliente. Sin handoff() ni as_tool() (esas son primitivas multiagente); sin output_guardrail (eso es reflexión).
Harness FastAPI en Azure Container Apps: sí, para el servicio HTTP.
Neon Postgres para estado durable: sí, para sesiones, runs, trazas. Crítico porque la traza de razonamiento del agente es el artefacto principal de depuración.
Cloudflare R2 para archivos: sí, si el agente maneja entradas/salidas de archivos.
Cloudflare Sandbox para ejecución: sí, si el agente tiene herramientas que ejecutan código. El agente ejecuta apply_patch, comandos de shell o Python arbitrario; ese código va al sandbox. El bridge Worker es obligatorio.
Patrón de background worker: sí, porque los bucles ReAct pueden tardar más de 30 segundos y no deberían bloquear la solicitud HTTP.

Señales de eval. Los modos de fallo de ReAct ocurren a nivel de razonamiento, así que las señales de eval también:

Modo de fallo	Cómo lo atrapa la eval
El agente entra en bucle, vuelve a trabajo resuelto	Anomalía de longitud de traza: la misma herramienta se llama repetidamente con argumentos similares. Bandera de Phoenix
El agente invoca herramientas inexistentes (herramientas alucinadas)	Validación de llamadas a herramientas en el SDK; la traza estructurada muestra la llamada inválida; la eval de CI la atrapa con DeepEval
El agente se rinde antes de resolver (terminación prematura)	Comparar salida final con comportamiento esperado; la traza muestra pocos pasos; DeepEval lo atrapa
El razonamiento del agente diverge de sus acciones	Evaluador Phoenix de corrección de herramientas: ¿la razón declarada por el agente coincide con la herramienta que llamó?
La latencia de llamadas a herramientas se encadena (cada paso es lento)	Los tiempos OTel muestran que el runtime agregado supera el presupuesto de latencia

La idea clave: las evals de ReAct deben capturar la traza de razonamiento, no solo la entrada/salida. La traza es el dato. Si solo compruebas si el agente dio la respuesta correcta, perderás casos en los que acertó por llamadas a herramientas afortunadas, y perderás casos en los que debería haber acertado pero no lo hizo por una sola mala decisión. Los evaluadores inline de trazas de Phoenix son la capa de observabilidad fundamental para ReAct.

Dónde se equivocan los equipos en producción. Dejar los presupuestos de pasos en infinito por defecto. Un bucle ReAct sin límite de pasos tarde o temprano encontrará una entrada que lo hace iterar indefinidamente, quemando tokens, bloqueando workers y agotando rate limits. Siempre limita pasos explícitamente (25 es un valor predeterminado razonable; algunas tareas necesitan 50; muy pocas necesitan 100). Cuando se alcanza el límite, es una señal para investigar, no un parche que quitar.

Capa operativa. Agente único + ReAct se envuelve limpiamente en Inngest, con una decisión estructural que conviene tomar bien: ¿haces que todo el bucle del agente sea un solo step.run o lo descompones en varios pasos?

Primitivas de Inngest usadas: @inngest_client.create_function con disparador de evento (TriggerEvent(event="customer/email.received"), la configuración exacta de Maya); ctx.step.run("agent-loop", Runner.run, agent, input) envolviendo la llamada Runner.run() del SDK; concurrency y throttle para proteger sistemas posteriores; opcionalmente ctx.step.wait_for_event dentro de una herramienta de escalamiento para implementar HITL.
La decisión estructural: un step.run para todo el bucle del agente es el patrón estándar. El SDK ejecuta internamente el bucle razonar-actuar-observar; desde la perspectiva de Inngest, es un paso durable. Fallo a mitad del bucle → reintenta todo el bucle (las trazas del SDK se pierden, pero la función se recupera). Alternativa descompuesta: envolver cada llamada a herramienta en su propio step.run da durabilidad más fina, pero exige sacar el bucle del SDK fuera de Runner.run(), lo cual es frágil. Por defecto, usa un step.run por bucle de agente salvo que tengas una razón específica para descomponer.
HITL mediante wait_for_event: la herramienta de escalamiento del código del Concepto 10 se vuelve un patrón de Inngest. Cuando el agente llama escalate_to_human, esa herramienta dispara un evento (refund/approval.requested) y la función se suspende mediante step.wait_for_event hasta que el humano responde. El código del agente queda limpio: solo llama una herramienta, y la durabilidad la maneja la capa.
Límites de concurrencia: concurrency=[Concurrency(limit=10, key="event.data.customer_id")] evita que una ráfaga de un solo cliente deje sin recursos a otros. Este es el patrón de concurrencia por clave de la capa operativa, aplicado directamente al despliegue de Maya.

El agente de soporte de nivel 1 de Maya es implícitamente esta composición: Agent + Runner.run() del SDK para el motor, ACA + Neon + R2 + sandbox para el despliegue, más la capa de Inngest (cuando está presente) para disparadores, durabilidad y control de flujo. La Decisión 1 de la Parte 5 hace explícita la composición.

Idea central del Concepto 10: ReAct con agente único es el patrón correcto cuando la ruta es desconocida y la estructura no es articulable. Usa la mayor parte del stack de nube (sandbox obligatorio si el agente ejecuta código; bridge Worker obligatorio para harnesses Python). La disciplina de eval captura la traza de razonamiento, no solo la salida final: Phoenix es la observabilidad fundamental para ReAct porque las señales a nivel de traza son las que atrapan los fallos característicos (bucles, herramientas alucinadas, terminación prematura, divergencia razonamiento-acción).

Concepto 11: Planificación + ejecución ReAct, forma característica, despliegue y señales de eval

Qué es. Un patrón de dos capas: un agente de planificación produce un plan explícito (etapas con dependencias) antes de que empiece la ejecución; ReAct + herramientas maneja el trabajo dentro de cada etapa. La ruta es desconocida a nivel de paso (Q1=no), pero la estructura es articulable a nivel de etapa (Q3=sí).

Implementación característica en OpenAI Agents SDK:

from agents import Agent, Runner, function_tool
from pydantic import BaseModel
from typing import Literal

class Stage(BaseModel):
    id: str
    description: str
    agent_role: Literal["researcher", "analyzer", "synthesizer"]
    depends_on: list[str]  # other stage ids
    step_budget: int

class Plan(BaseModel):
    task_summary: str
    stages: list[Stage]
    success_criteria: str

# Planner: an Agent that produces a structured plan, no tools.
planner = Agent(
    name="market_research_planner",
    instructions=(
        "Given a research task, produce a plan with 3-7 stages. Each stage has clear "
        "dependencies and a step budget. Prefer fewer broader stages over many narrow ones."
    ),
    output_type=Plan,
)

# Three execution specialists: each with its own tools and instructions.
researcher = Agent(
    name="researcher",
    instructions="Investigate the assigned topic using your tools. Return a structured brief.",
    tools=[web_search, fetch_url, read_document],
)
analyzer = Agent(
    name="analyzer",
    instructions="Analyze the briefs from researchers. Identify patterns, contradictions, gaps.",
    tools=[compute_metrics, compare_briefs],
)
synthesizer = Agent(
    name="synthesizer",
    instructions="Synthesize the analyzed findings into a coherent report.",
    tools=[draft_report, format_citations],
)

ROLE_TO_AGENT = {"researcher": researcher, "analyzer": analyzer, "synthesizer": synthesizer}

async def planning_then_react(task: str, session_id: str) -> str:
    # Stage 1: Generate the plan via the planner Agent
    plan_result = await Runner.run(planner, task)
    plan: Plan = plan_result.final_output
    await db.runs.persist_plan(session_id, plan)  # cloud deployment: plan persistence

    # Stage 2: Execute each stage via the matching specialist Agent
    stage_results: dict[str, str] = {}
    for stage in topological_order(plan.stages):
        agent = ROLE_TO_AGENT[stage.agent_role]
        stage_input = compose_stage_input(stage, stage_results, task)
        stage_run = await Runner.run(agent, stage_input, max_turns=stage.step_budget)
        stage_results[stage.id] = stage_run.final_output
        await db.runs.persist_stage(session_id, stage.id, stage_run.final_output)

    # Stage 3: Final synthesis via the synthesizer one more time
    final = await Runner.run(
        synthesizer,
        f"Compose the final report. Plan: {plan.model_dump_json()}. Results: {stage_results}",
    )
    return final.final_output

Observa la forma del SDK: el planificador es un Agent con output_type=Plan y sin herramientas (solo produce salida estructurada). Cada etapa de ejecución usa el Agent especialista que coincide con el rol de la etapa, llamado mediante Runner.run(). El plan está estructurado por Pydantic, así que el SDK lo valida a nivel de tipo: nada de parsear JSON y esperar lo mejor. La persistencia del plan ocurre mediante la tabla runs de Neon Postgres del despliegue en la nube (el Worker de soporte al cliente la cablea).

La idea del SDK que conviene internalizar: Agent con salida estructurada + Agent con herramientas son las dos mitades de planificación + ejecución ReAct. output_type= del SDK es lo que vuelve los planes artefactos de primera clase; el resto es código de orquestación normal sobre llamadas Runner.run().

Composición de despliegue. Planificación + ReAct usa los mismos componentes que ReAct con agente único, más una disciplina adicional:

Primitivas del SDK usadas: Agent planificador con output_type=PlanSchema (sin herramientas, solo salida estructurada); un Agent de ejecución por rol con tools=[...] y decoradores @function_tool; Runner.run() llamado una vez para el planificador y una vez por etapa. La persistencia del plan vive en la tabla runs del despliegue en la nube, no en el SDK en sí; el SDK no conserva estado entre llamadas Runner.run().
Todos los requisitos de despliegue ReAct del Concepto 10: mismo harness, sandbox, R2, background worker.
Persistencia de plan en Neon. El plan es un artefacto que vale la pena almacenar para auditoría y reanudabilidad. Una tabla nueva o una extensión del esquema de runs rastrea plan_id, el contenido del plan y el progreso etapa por etapa.
Los runs de larga duración son más comunes. Los planes suelen tener 5-10 etapas, cada una potencialmente con 20-30 pasos ReAct. Runs de extremo a extremo de 5-10 minutos son normales. El patrón de background worker es obligatorio, no opcional.

Señales de eval. Planificación + ReAct añade nuevos modos de fallo más allá de ReAct puro:

Modo de fallo	Cómo lo atrapa la eval
El planificador produce un plan del que la ejecución diverge	Comparar el plan con la ejecución real de etapas; marcar cuando se omitieron, reordenaron o redefinieron sustancialmente etapas a mitad de run
El plan tiene etapas faltantes (un paso obvio no está en el plan)	Comparar contra planes de dataset golden para tareas similares; DeepEval marca divergencia estructural
Los handoffs entre etapas pierden contexto	Inspeccionar la entrada de cada etapa; si la etapa N no puede referenciar salida crítica de la etapa M, el handoff perdió información
El plan es demasiado detallado (cada etapa es una sola llamada a herramienta)	Análisis de tamaño de etapa; si cada etapa ejecuta 1-2 pasos ReAct, la capa de planificación no está haciendo trabajo
El plan es demasiado poco detallado (una etapa cubre un alcance enorme)	Análisis de tamaño de etapa; si una etapa ejecuta 50+ pasos ReAct, la planificación no descompuso realmente

La idea clave: las evals de planificación + ReAct deben medir calidad del plan separada de calidad de ejecución. Un buen plan con mala ejecución se ve distinto de un mal plan con buena ejecución; confundirlos produce diagnósticos falsos. La señal de eval "divergencia plan-ejecución" es la más informativa: indica que el planificador está produciendo una estructura que la tarea no tiene realmente.

Dónde se equivocan los equipos en producción. Confiar en el plan como si fuera un contrato. El plan es una estructura inicial; la ejecución dentro de etapas puede descubrir legítimamente que la siguiente etapa necesita un trabajo distinto al planificado. Tratar toda divergencia como mala crea rigidez; tratarla siempre como aceptable elimina el valor de planificar. La disciplina correcta es: registra cada divergencia, revisa periódicamente patrones de divergencia (una divergencia recurrente significa que el planificador necesita mejorar) y permite pequeñas adaptaciones dentro de etapa sin alarma.

Capa operativa. Planificación + ejecución ReAct es el encaje más claro para el modelo step.run de Inngest: cada etapa se mapea a un step.run, y los beneficios de durabilidad se acumulan a lo largo del run multietapa.

Primitivas de Inngest usadas: @inngest_client.create_function para la función padre; un ctx.step.run por etapa (step.run("plan", Runner.run, planner, task), luego un step.run por etapa de ejecución); retries= configurado por etapa si algunas etapas tienen modos de fallo no transitorios; concurrency para limitar runs paralelos.
El mapeo planificar-luego-ejecutar: step.run("plan", ...) produce el plan; la función recorre plan.stages y llama step.run(f"stage-{stage.id}", ...) por cada una. Si la función falla a mitad de ejecución (digamos, en la etapa 4 de 6), Inngest restaura el plan y las etapas 1-3 desde memoización; solo reintenta la etapa 4. La persistencia del plan es gratis: Inngest lo almacena como salida del paso "plan".
Impacto de costo: aquí los ahorros son los mayores de cualquier patrón. Un run de planificación + ReAct puede tardar 5-10 minutos e involucrar 20-30 llamadas a herramientas; un fallo en el minuto 8 sin durabilidad vuelve a pagar todo. La memoización de la capa operativa puede ahorrar $0.50-$2.00 por run fallido con precios clase GPT-5. Para sistemas con 1000 runs/día y tasas de fallo de 1-5% por problemas transitorios de infraestructura, son $150-$1000/mes de costos de LLM directamente ahorrados.
Ejecución paralela de etapas: las etapas sin dependencias entre sí pueden desplegarse mediante el patrón fan-out de la capa operativa (un evento por etapa, cada uno disparando su propia función), paralelizando la ejecución y preservando la durabilidad por etapa.

El requisito de "persistencia de plan en Neon" de la composición de despliegue del Concepto 11 es parcialmente innecesario si Inngest está en la capa, porque Inngest almacena el plan como salida del paso "plan". Neon aún rastrea el run para auditoría y observabilidad mediante OTel, pero la historia de recuperación del plan la maneja Inngest, no tu código de aplicación.

Idea central del Concepto 11: planificación + ejecución ReAct es el patrón correcto cuando la estructura es articulable pero el trabajo a nivel de paso requiere adaptación. Usa todo el stack de despliegue ReAct más persistencia de plan y el patrón de background worker. La disciplina de eval separa calidad del plan de calidad de ejecución; la divergencia plan-ejecución es la señal más informativa, porque indica que el planificador está produciendo una estructura que la tarea no tiene realmente.

Concepto 12: Agente único + reflexión, forma característica, despliegue y señales de eval

Qué es. Una capa encima de cualquier patrón central: después de que el agente produce salida, un pase de crítica la evalúa contra criterios explícitos; si se identifican defectos, el agente refina o regenera. La reflexión se justifica por Q4 (calidad > velocidad Y criterios verificables).

Implementación característica en OpenAI Agents SDK. El SDK te da dos primitivas distintas para reflexión; elige según quieras validación (bloquear salidas malas) o refinamiento (mejorar salidas fronterizas).

Sabor 1, output_guardrail para reflexión estilo validación (el patrón nativo ligero del SDK):

from agents import Agent, Runner, output_guardrail, GuardrailFunctionOutput, RunContextWrapper
from pydantic import BaseModel

class SQLReview(BaseModel):
    is_safe: bool
    issues: list[str]
    reasoning: str

# A critic Agent: uses a different model from the generator to avoid blind-spot overlap.
sql_critic = Agent(
    name="sql_critic",
    model="claude-opus-4-5",  # different model family from the generator
    instructions=(
        "Review the SQL query. Check that it parses, hits only allowed tables, "
        "does not use SELECT *, and has appropriate WHERE clauses. Flag any issues."
    ),
    output_type=SQLReview,
)

@output_guardrail
async def critic_guardrail(ctx: RunContextWrapper, agent: Agent, output: str) -> GuardrailFunctionOutput:
    review_result = await Runner.run(sql_critic, output)
    review: SQLReview = review_result.final_output
    return GuardrailFunctionOutput(
        output_info={"issues": review.issues, "reasoning": review.reasoning},
        tripwire_triggered=not review.is_safe,
    )

# The generator Agent: uses output_guardrails to invoke the critic.
sql_generator = Agent(
    name="sql_generator",
    model="gpt-5",  # different model family from the critic
    instructions="Generate a SQL query that answers the user's question.",
    tools=[fetch_schema, list_tables],
    output_guardrails=[critic_guardrail],
)

# When tripwire fires, Runner.run raises OutputGuardrailTripwireTriggered.
# Catch it and decide: retry with critique context, escalate, or fail loudly.

Sabor 2, bucle separado de crítico y refinador para reflexión estilo refinamiento (cuando quieres que el generador arregle su salida, no solo bloquear una salida mala):

async def with_reflection(task: str, max_refinements: int = 2) -> str:
    output = (await Runner.run(sql_generator, task)).final_output
    for refinement in range(max_refinements):
        critique = (await Runner.run(sql_critic, output)).final_output
        if critique.is_safe and not critique.issues:
            return output
        # Refinement: feed the critique back to the generator
        refine_prompt = f"Original query:\n{output}\n\nCritic flagged: {critique.issues}\n\nRevise the query."
        output = (await Runner.run(sql_generator, refine_prompt)).final_output
    return output  # max refinements reached; output is best-effort

Observa las dos formas del SDK: output_guardrail es el patrón nativo del SDK para "bloquear salidas malas": declarativo, atado a la definición del agente, se ejecuta automáticamente en cada Runner.run(). El bucle separado de crítico y refinador es el patrón idiomático del SDK para "mejorar salidas fronterizas": más flexible, pero escribes la orquestación. Ambos patrones usan modelos distintos para crítico y generador. Esta es la disciplina nombrada en el Concepto 7, concretada mediante el parámetro model= del SDK en cada Agent.

La idea del SDK que conviene internalizar: la reflexión no es una primitiva de framework separada en el SDK; es una composición de Agent + Agent. El decorador output_guardrail es solo una convención del SDK para cablear el segundo agente en la ruta de salida del primero.

Composición de despliegue. La reflexión se añade encima del patrón central, así que la composición de despliegue depende de lo que haya debajo:

Primitivas del SDK usadas: output_guardrail (la primitiva nativa de validación del SDK) para reflexión que bloquea salidas malas; o dos instancias de Agent (generador + crítico) con Runner.run() llamado por agente para reflexión estilo refinamiento. Crítico: el crítico debería usar un model= distinto del generador, mismo SDK, familia de modelo distinta.
Si el núcleo es un flujo de trabajo secuencial, la reflexión añade 1-2 llamadas al LLM; el despliegue no cambia estructuralmente.
Si el núcleo es ReAct + herramientas, la reflexión añade 1-2 llamadas al LLM después de que termina el bucle del agente; el despliegue no cambia estructuralmente.
Si el núcleo es planificación + ReAct, la reflexión a menudo va entre etapas (criticar la salida de la etapa N antes de que empiece la etapa N+1) y sobre la síntesis final; esto añade latencia.

La nueva consideración de despliegue: variedad de modelos. Si el crítico usa un modelo distinto al generador (Claude criticando GPT, o viceversa), el harness necesita admitir varios proveedores de modelos. El curso de despliegue en la nube enseña un despliegue de proveedor único; añadir reflexión a menudo vuelve multiproveedor una necesidad real. Planifica la gestión de secretos y el enrutamiento en consecuencia.

Señales de eval. La reflexión tiene sus propios modos de fallo característicos:

Modo de fallo	Cómo lo atrapa la eval
La reflexión no cambia la salida (aprobación mecánica)	Comparar salidas pre y post reflexión; si son casi idénticas >80% del tiempo, la reflexión no está haciendo trabajo
La reflexión refina en la dirección equivocada (empeora la salida)	Puntuar pre y post reflexión contra el dataset golden; impacto neto negativo significa que el crítico está fallando
Crítico y generador comparten puntos ciegos	Prueba A/B: mismo generador, dos críticos distintos (modelos o prompts distintos); si el contenido de crítica correlaciona mucho, los críticos no son lo bastante independientes
Deriva de criterios con el tiempo (la lista de criterios crece o se encoge ad hoc)	Versionar la lista de criterios; marcar cambios que no correspondan a decisiones documentadas
Los bucles de refinamiento exceden el presupuesto	El contador de refinamiento supera el umbral; investigar por qué el crítico sigue encontrando defectos que el generador no puede arreglar

La idea clave: las evals de reflexión deben medir si la reflexión es netamente positiva, no solo si se ejecuta. Un pase de reflexión que se ejecuta sin cambiar la salida es sobrecarga; un pase de reflexión que empeora las salidas es dañino. El modo de fallo de "aprobación mecánica" es el más difícil de detectar porque el sistema se ve saludable desde una métrica superficial (subió la latencia, los errores quedaron planos), pero no está ganándose su costo.

Dónde se equivocan los equipos en producción. Añadir reflexión porque suena rigurosa. Los equipos añaden un patrón de "generar y luego criticar" sin medir si la crítica atrapa cosas que el generador omitió. Meses después, el pase de reflexión costó $X en llamadas adicionales al LLM y aportó $0 en mejora medible de calidad. La disciplina es: mide la contribución neta de la reflexión durante el primer mes y quítala si la contribución está por debajo del umbral.

Capa operativa. La reflexión compone bien con el modelo de pasos de Inngest: cada pase (generar, criticar, refinar) se convierte en su propio step.run, y los beneficios de durabilidad son proporcionales a cuántos pases hiciste antes de cualquier fallo individual.

Primitivas de Inngest usadas: tres o cuatro llamadas ctx.step.run por run: step.run("generate", ...), step.run("critique", ...) y 0-2 step.run("refine-N", ...) para intentos de refinamiento. Opcional: ctx.step.wait_for_event cuando el crítico es humano (la función se suspende hasta que un revisor humano dispara el evento de aprobación, la misma primitiva de puerta HITL que proporciona la capa operativa).
La victoria de durabilidad: si el paso generador completa con éxito (el paso más caro, produce la salida que se critica) y el paso crítico falla transitoriamente (rate limit, fallo de red), solo reintenta el paso crítico. La salida del generador queda memoizada y no se regenera. La disciplina step.run de la capa operativa es lo que evita que la latencia añadida de la reflexión se convierta en doble costo ante fallos.
Reflexión HITL. Cuando los criterios de evaluación no son verificables por otro LLM (la salvedad de "dominios subjetivos" del Concepto 7), la respuesta correcta suele ser reflexión humana. step.wait_for_event de Inngest lo vuelve limpio: step.run("generate", ...) → step.run("send-to-reviewer", ...) → step.wait_for_event("await-human-decision", timeout=timedelta(hours=4)) → step.run("act-on-decision", ...). La función se suspende con cero cómputo consumido mientras un humano revisa. El curso de capa operativa recorre el patrón HITL en detalle.
Disciplina de costo por salida de la reflexión: el seguimiento de costos a nivel de run de Inngest (costo LLM por step.run) vuelve trivial medir la contribución neta de la reflexión. La comparación de costo por run (con reflexión frente a sin reflexión) está a una consulta de dashboard de Phoenix.

Los dos sabores de reflexión del SDK del Concepto 12 (output_guardrail frente a bucle separado de crítico y refinador) componen naturalmente con la capa de Inngest. Elige el sabor del SDK por estilo de reflexión; la disciplina de la capa es la misma de cualquier modo.

Idea central del Concepto 12: la reflexión es la capa adicional correcta cuando la calidad importa más que la velocidad Y los criterios son verificables. Se añade encima de cualquier patrón central. La disciplina de eval mide si la reflexión es netamente positiva; la aprobación mecánica es el modo de fallo más insidioso porque las métricas superficiales se ven saludables. Si la reflexión no mejora salidas de forma medible dentro del primer mes de despliegue, quítala.

Concepto 13: Sistema especialista multiagente, forma característica, despliegue y señales de eval

Qué es. Varios agentes con roles distintos colaboran en una tarea. Se justifica por Q5: especialización, contexto o escala crea un cuello de botella real. La composición del patrón importa: la arquitectura interna de cada especialista puede ser flujo de trabajo secuencial, ReAct o planificación + ReAct. Multiagente no reemplaza los otros patrones; los compone.

Tres topologías nativas del SDK, cada una usando una primitiva distinta del SDK.

Topología 1, coordinador con especialistas como herramientas (el patrón Agent.as_tool() del SDK). El coordinador mantiene el control; los especialistas se invocan como herramientas de función.

from agents import Agent, Runner, function_tool

# Three specialists, each with its own tools and instructions.
researcher = Agent(name="researcher", instructions="...", tools=[web_search, fetch_url])
writer = Agent(name="writer", instructions="...", tools=[draft_document])
reviewer = Agent(name="reviewer", instructions="...", tools=[lint_check, fact_check])

# The coordinator uses specialists as_tool(): calling them like functions.
coordinator = Agent(
    name="coordinator",
    instructions=(
        "Decompose the task into research, writing, and review phases. "
        "Use the specialist tools in order. Compose their outputs into a final report."
    ),
    tools=[
        researcher.as_tool(tool_name="research_topic", tool_description="Investigate a topic and return a brief"),
        writer.as_tool(tool_name="draft_document", tool_description="Draft a document from research notes"),
        reviewer.as_tool(tool_name="review_document", tool_description="Review a draft and return critique"),
    ],
)

async def coordinator_topology(task: str) -> str:
    result = await Runner.run(coordinator, task, max_turns=30)
    return result.final_output

Topología 2: handoff secuencial (el patrón handoff() del SDK). Los especialistas toman el control de la conversación; el SDK pasa contexto entre ellos.

from agents import Agent, Runner, handoff

# Define specialists; each one declares which agents it can hand off TO.
final_reviewer = Agent(name="reviewer", instructions="Review the draft and produce the final output.")
writer = Agent(
    name="writer",
    instructions="Draft from the research. When the draft is ready, hand off to the reviewer.",
    handoffs=[handoff(final_reviewer)],
)
researcher = Agent(
    name="researcher",
    instructions="Investigate the topic. When research is complete, hand off to the writer.",
    tools=[web_search, fetch_url],
    handoffs=[handoff(writer)],
)

async def handoff_topology(task: str) -> str:
    # Start with the researcher; the SDK threads control through handoffs.
    result = await Runner.run(researcher, task, max_turns=50)
    return result.final_output  # whoever ended up holding the conversation

Topología 3, especialistas paralelos compuestos por un sintetizador. El SDK ejecuta cada especialista de forma independiente mediante Runner.run(); el sintetizador compone sus salidas.

import asyncio
from agents import Agent, Runner

# Five domain specialists running in parallel: one per competitor to research.
competitor_specialist = Agent(
    name="competitor_research",
    instructions="Research one competitor in depth: pricing, product, positioning, recent news.",
    tools=[web_search, fetch_url, read_document],
)
synthesizer = Agent(
    name="synthesizer",
    instructions="Compose competitor briefs into a single comparative landscape report.",
)

async def parallel_topology(competitors: list[str]) -> str:
    # Each specialist runs independently: different Runner.run() calls.
    parallel_briefs = await asyncio.gather(*[
        Runner.run(competitor_specialist, f"Research: {c}", max_turns=15)
        for c in competitors
    ])
    briefs_text = "\n\n".join(r.final_output for r in parallel_briefs)
    final = await Runner.run(synthesizer, briefs_text)
    return final.final_output

Observa las tres primitivas del SDK en juego:

Agent.as_tool() envuelve un agente como herramienta invocable; el coordinador mantiene el control y llama especialistas como funciones. Mejor cuando el coordinador necesita componer salidas y decidir el siguiente paso.
handoff() entrega la conversación a otro agente, transfiere control y el SDK gestiona el contexto. Mejor cuando el especialista necesita tomar el control de la interacción con el usuario.
Runner.run() paralelo + asyncio.gather() ejecuta especialistas de forma independiente: sin conversación compartida, sin handoff. Mejor cuando los especialistas trabajan aislados y sus salidas las compone un sintetizador.

La idea del SDK que conviene internalizar: el SDK te da primitivas nativas para composición multiagente. No escribes lógica de enrutamiento a mano. as_tool() para composición jerárquica; handoff() para toma de control secuencial; Runner.run() paralelo para fan-out. Elegir entre ellas es una decisión de selección de patrones por derecho propio, y está aguas abajo de las mismas propiedades de tarea que mostró Q5.

Composición de despliegue. Los sistemas multiagente usan el stack completo de nube más una disciplina adicional crítica:

Primitivas del SDK usadas: Agent.as_tool() para composición jerárquica (el coordinador mantiene el control); handoff() para toma de control secuencial (el especialista toma la conversación); Runner.run() paralelo + asyncio.gather() para fan-out. Cada especialista es su propio Agent con su propia lista tools= e instructions=. El SDK gestiona el paso de contexto entre handoffs; no escribes enrutamiento a mano.
Todos los requisitos de ReAct con agente único para cada especialista (harness, sandbox si hace falta, R2, background worker).
Runs/trazas por especialista en Neon. La ejecución de cada especialista es su propio run; el sistema multiagente es un run padre que referencia los runs hijos. El esquema necesita columnas parent_run_id y agent_role.
Logs de auditoría de enrutamiento. Cada decisión de enrutamiento (¿qué especialista? ¿qué formato de handoff?) se registra. Los fallos multiagente suelen manifestarse como decisión-de-enrutamiento-equivocada o contexto-perdido-en-handoff; sin logs explícitos de enrutamiento, depurar es casi imposible.
Seguimiento de costos por especialista. Los sistemas multiagente facilitan perder de vista qué especialista quema tokens. La atribución de costos por especialista evita que los costos descontrolados se oculten en métricas agregadas.

El bridge Worker más especialistas. Si varios especialistas ejecutan código, quizá necesites varias configuraciones de bridge Worker (manifiestos distintos para las necesidades de herramientas de cada especialista) o un solo bridge Worker que enrute por identidad de especialista. La complejidad escala más rápido de lo que la gente espera: aquí es donde los costos de topología de despliegue empiezan a dominar.

Señales de eval. Los fallos multiagente son los más difíciles de evaluar porque pueden ocurrir en tres capas: dentro de un especialista, en el enrutamiento/coordinación o en la integración:

Modo de fallo	Cómo lo atrapa la eval
El especialista produce salida incorrecta	Eval estándar por agente sobre cada rol especialista (trata a cada especialista como si fuera un agente independiente para evaluar)
El coordinador enruta al especialista equivocado	Eval de exactitud de enrutamiento: dada una tarea, ¿fue al especialista correcto? Requiere ejemplos etiquetados de enrutamiento en el dataset golden
El handoff pierde información (el especialista B no puede usar la salida del especialista A)	Eval de completitud de handoff: ¿el especialista B tenía lo que necesitaba del especialista A? Etiquetas manuales al inicio; se automatiza cuando los patrones están claros
La integración combina incorrectamente las salidas de especialistas	Eval de extremo a extremo contra el dataset golden; si los especialistas pasan individualmente pero falla la salida integrada, el problema es integración
Los especialistas discrepan sin resolución	Detector de inconsistencias: especialistas paralelos producen respuestas conflictivas; el agregador las resuelve explícitamente o expone el conflicto
La sobrecarga de coordinación excede el valor del trabajo	Costo por salida correcta: si multiagente cuesta más de 3× que agente único y la mejora de calidad es menor que 20%, la arquitectura no se gana su sobrecarga

La idea clave: las evals multiagente necesitan tres marcadores separados: calidad de especialistas, exactitud de enrutamiento, calidad de integración. Confundirlos produce puntajes agregados sin sentido. La calidad individual de cada especialista puede ser 95%, la exactitud de enrutamiento 90%, la calidad de integración 80%, y el sistema extremo a extremo rendir ~68% (el producto). Sin separación, no puedes saber qué capa mejorar.

Dónde se equivocan los equipos en producción. Tratar el sistema multiagente como una sola unidad. Cuando algo falla, el equipo depura todo el sistema en lugar de localizar la capa. Solución: impón trazas por especialista y logs por handoff desde el día uno. Sin eso, la depuración multiagente es sustancialmente más difícil y lenta que la de agente único, a menudo por un múltiplo grande, y ese es uno de los mayores costos ocultos del patrón.

Capa operativa. Multiagente es el patrón que más depende de la capa operativa de Inngest. Casi todas las primitivas de la capa cumplen un rol: fan-out para especialistas paralelos, concurrencia por clave para equidad entre tenants, prioridad para colas por nivel, puertas HITL entre especialistas, replay para recuperación de fallos parciales.

Primitivas de Inngest usadas (la composición más extensa del currículo):
- Patrón de disparador fan-out para ejecución paralela de especialistas: la función coordinadora dispara N eventos de especialistas; cada especialista es su propia @inngest_client.create_function con su propio TriggerEvent. Un evento despierta N funciones; se ejecutan en paralelo; Inngest rastrea cada una de forma independiente.
- step.run por run de especialista dentro de cada función especialista, la misma historia de durabilidad que ReAct con agente único (Concepto 10), pero multiplicada por N.
- Límites de concurrencia por clave para impedir que un solo tenant monopolice capacidad especialista: concurrency=[Concurrency(limit=5, key="event.data.tenant_id")]. La concurrencia por clave es el patrón fundamental aquí.
- Expresiones de prioridad para equidad por nivel: los runs de tenants Enterprise saltan delante del nivel Free en la cola.
- step.wait_for_event entre especialistas cuando los handoffs necesitan aprobación humana (por ejemplo, investigación → investigación validada por humano → análisis).
- Replay para recuperación de fallos parciales: cuando fallan 3 de 5 especialistas y 2 tienen éxito, arregla el código del especialista que falla y ejecuta replay; las salidas de los 2 especialistas exitosos quedan memoizadas.
La idea de costo de coordinación: el Concepto 13 señaló que la sobrecarga de coordinación es el mayor costo oculto de multiagente. Las primitivas de Inngest absorben gran parte de esa sobrecarga: la lógica de enrutamiento se vuelve eventos + triggers (sin router escrito a mano); los contratos de handoff se vuelven esquemas de evento (modelos Pydantic validados por el SDK); los fallos de integración se vuelven candidatos a replay (no trabajo perdido); el seguimiento de costos por especialista se vuelve métricas de panel por función.
Ahorros cuantificados. Un sistema multiagente sin Inngest normalmente requiere:
- Una capa personalizada de enrutamiento/despacho (~500-2000 líneas de código)
- Un manejador personalizado de reintentos/dead-letter (~200-1000 líneas)
- Una cola personalizada de aprobación HITL con timeouts (~500-1500 líneas)
- Rate limiting por tenant (~300-800 líneas)
- Herramientas personalizadas de replay/recuperación (~500-2000 líneas)
En conjunto: 2.000-7.000 líneas de código de capa operativa que hay que probar, depurar y mantener. Con Inngest, esto se vuelve ~50-200 líneas de declaraciones de trigger y llamadas step.run. La diferencia de costo total se acumula durante toda la vida de un sistema multiagente de producción.
La observabilidad de tres marcadores se conserva. Los marcadores de calidad por especialista, exactitud de enrutamiento y calidad de integración de la suite de evals (de las señales de eval del Concepto 13) siguen aplicando; las trazas estructuradas de Inngest fluyen a Phoenix mediante OTel, así que la disciplina de eval no cambia.

El requisito del despliegue en la nube de "tracing por especialista, logs de auditoría de enrutamiento y seguimiento de costos por especialista" queda parcialmente absorbido por Inngest. Aún necesitas trazas a nivel de aplicación (Phoenix), pero los logs de auditoría y el seguimiento de costos se vuelven funciones de runs-de-función en el dashboard de Inngest. La composición es: Inngest para datos operativos a nivel de run, Phoenix para datos de evaluación a nivel de traza, Neon para auditoría a nivel de aplicación. Tres capas, cada una dueña de lo que mejor hace.

Idea central del Concepto 13: los sistemas especialistas multiagente usan el stack completo de nube más tracing por especialista, logs de auditoría de enrutamiento y seguimiento de costo por especialista. La disciplina de eval requiere tres marcadores separados (calidad de especialistas, exactitud de enrutamiento, calidad de integración) porque los puntajes agregados ocultan qué capa falló. La sobrecarga de coordinación es el costo más subestimado; sin instrumentación rigurosa por especialista, depurar es mucho más difícil y lento que en agente único.

Prueba con IA, después de la Parte 3. Ya viste cuánto cuesta desplegar cada patrón y cómo falla cada uno. Vuelve concreto un patrón al que realmente recurrirías. Abre tu sesión de Claude Code u OpenCode y pega:

"Elige el patrón agéntico que más probablemente construiré después (flujo de trabajo secuencial, agente único con ReAct y herramientas, planificación con ReAct o sistema especialista multiagente). Para ese patrón, guíame por dos cosas. Primero, la topología de despliegue: qué componentes necesita (servicio HTTP, estado durable, almacenamiento de archivos, ejecución de código en sandbox, background workers, observabilidad de trazas) y cuáles puede omitir. Segundo, la señal de fallo única que debería vigilar primero en producción y el arreglo barato específico que debería probar antes de cambiar la arquitectura. Sé concreto sobre mi patrón, no genérico."

Lo que estás aprendiendo. Una elección de patrón no es real hasta que puedes nombrar cuánto cuesta ejecutarla y cómo sabrás que se rompió. Esto convierte la composición de despliegue y evals de algo que leíste en algo que puedes bosquejar en una pizarra.

Parte 4: Señales de fallo y revisión de patrones

Elegiste un patrón de partida. El sistema está funcionando. ¿Qué te dice que el patrón era incorrecto y qué deberías hacer? La Parte 4 cubre las cinco señales de fallo características del artículo de Bala Priya C, mapeadas a señales específicas de eval y observabilidad de tu suite de evals, con arreglos dirigidos que no requieren abandonar la arquitectura.

Concepto 14: Las cinco señales de fallo (y qué significa cada una)

El artículo identifica cinco síntomas de runtime que indican desajuste patrón-tarea. Cada uno tiene una forma característica que, cuando la has visto dos veces, puedes reconocer de inmediato.

Señal 1: ReAct entra en bucle o vuelve a trabajo resuelto. El agente llama la misma herramienta con argumentos similares varias veces dentro de un run. O produce salidas parciales y luego vuelve a derivarlas desde cero. Al patrón le falta estructura o condiciones de parada. El agente no tiene una forma de saber que terminó.

Dónde aparece esto en observabilidad: anomalías de longitud de traza (el run tomó 40 pasos cuando la mayoría toma 15); patrones de llamadas duplicadas a herramientas (el mismo customer_lookup llamado cinco veces); señales de bucle de razonamiento (el texto de razonamiento del modelo muestra "let me try this again" o equivalente).

Significados probables, en orden de frecuencia:

La indicación del agente no define cuándo el trabajo está "terminado"
Los contratos de herramientas son flojos (varias herramientas podrían hacer plausiblemente lo mismo; el agente oscila entre ellas)
La tarea realmente necesitaba planificación (Q3 debió ser sí)

Señal 2: el planificador crea un plan pero la ejecución diverge. El plan dice "etapa 1: investigar; etapa 2: redactar; etapa 3: revisar". La ejecución hace la etapa 1, luego salta a la etapa 3, luego vuelve a la etapa 2. O la ejecución añade etapas que el planificador no incluyó. La tarea era menos predecible de lo que suponía la apuesta de planificación.

Dónde aparece esto en observabilidad: métrica de divergencia plan-ejecución (calcular la distancia de edición entre etapas planificadas y etapas ejecutadas); señales de reordenamiento (etapas ejecutadas fuera del orden de dependencia); señales de etapa insertada (la ejecución incluye etapas que no estaban en el plan).

Significados probables, en orden de frecuencia:

La estructura de la tarea es parcialmente articulable, no totalmente; el planificador identifica correctamente fases grandes pero omite subfases adaptativas (usa planificación ligera)
El entrenamiento del planificador no coincide con el dominio de esta tarea (mejora la indicación de planificación con ejemplos de dominio)
La tarea realmente no tiene estructura articulable (Q3 debió ser no; baja a ReAct puro)

Señal 3: la reflexión no mejora la respuesta. El pase de crítica se ejecuta, produce crítica, el agente refina, y la salida refinada es indistinguible de la original. O la salida refinada es peor. La apuesta de reflexión está fallando: los criterios son vagos, o crítico y generador comparten puntos ciegos, o ambas cosas.

Dónde aparece esto en observabilidad: puntajes de comparación pre/post reflexión (si son estadísticamente indistinguibles, la reflexión no está haciendo trabajo); tasas de activación de criterios (¿qué criterios disparan refinamiento? si siempre es el mismo, ese criterio es el único útil); tasa de acuerdo crítico-generador (si el crítico casi siempre aprueba, está aprobando mecánicamente).

Significados probables, en orden de frecuencia:

Los criterios son demasiado vagos para impulsar refinamiento (hazlos más específicos y verificables)
Crítico y generador son el mismo modelo con prompts similares (usa un modelo distinto o un encuadre de crítico fundamentalmente distinto)
La tarea no necesitaba realmente reflexión (Q4 debió ser no: quizá la calidad importa, pero los criterios no son verificables)

Señal 4: falla el enrutamiento multiagente. El coordinador envía la tarea al especialista equivocado. O dos especialistas producen salidas conflictivas que el agregador no puede reconciliar. O el handoff entre especialistas pierde información crítica. La sobrecarga de coordinación está dominando el trabajo.

Dónde aparece esto en observabilidad: métrica de exactitud de enrutamiento (comparar las decisiones de enrutamiento del coordinador con etiquetas del dataset golden); señales de completitud de handoff (la entrada del especialista B no referencia contenido crítico de la salida del especialista A); tasa de fallo de integración (los especialistas pasan individualmente, el end-to-end falla).

Significados probables, en orden de frecuencia:

Los roles de especialistas se solapan (aclara límites; fusiona especialistas solapados)
Los contratos de handoff son implícitos (hazlos explícitos; exige formatos de handoff estructurados)
La tarea no necesitaba realmente multiagente (Q5 debió ser no; colapsa a agente único)

Señal 5: el sistema se siente complejo pero no mejor. La más difícil de diagnosticar porque ninguna señal de eval individual la atrapa. La arquitectura tiene varias capas (planificación + reflexión + multiagente, por ejemplo), pero la calidad de salida no es mediblemente mejor que la de una línea base más simple. La arquitectura está resolviendo un problema estético, no un cuello de botella de tarea.

Dónde aparece esto en observabilidad: no hay una sola señal de observabilidad. La detección requiere una comparación de línea base: implementa una versión más simple de la misma tarea (agente único + ReAct + herramientas, sin reflexión, sin multiagente) y mide su calidad en el dataset golden. Si la versión más simple queda dentro de aproximadamente 10% de la versión compleja, la arquitectura compleja no se está ganando su costo.

Significado probable, en casi todos los casos:

El equipo añadió capas de patrones sin probar si cada capa estaba justificada; el sobredimensionamiento se acumuló entre varias decisiones

Idea central del Concepto 14: cinco señales de fallo características indican desajuste patrón-tarea: bucles/revisitas ReAct (falta estructura), divergencia plan-ejecución (sobreestructurado), reflexión que no mejora (criterios vagos), fallos de enrutamiento multiagente (sobreparticionado), sistema-complejo-pero-no-mejor (sobredimensionamiento acumulado). Cada señal tiene una forma de observabilidad característica. Reconocer la señal es el primer paso; el arreglo no siempre es arquitectónico, a veces es afinar prompts o clarificar contratos.

Concepto 15: Arreglos dirigidos que no requieren abandonar la arquitectura

Reconocer una señal de fallo no siempre significa reescribir la arquitectura. La mayoría de los arreglos están a nivel de prompt, contrato o instrumentación, no a nivel arquitectónico. Este concepto asigna cada señal a la primera opción más barata de arreglo.

Señal	Arreglo más barato para probar primero	Si eso no funciona	Cambio arquitectónico requerido
Bucles/revisitas ReAct	Añadir condiciones de parada explícitas ("has completado la tarea cuando...") y límites de herramientas ("usa X para Y; no uses X para Z")	Mejorar contratos de herramientas (mejores descripciones, tipos de retorno más claros)	Añadir capa de planificación (actualizar al patrón del Concepto 11)
Divergencia plan-ejecución	Cambiar a planificación ligera (menos etapas, más amplias)	Mejorar la indicación del planificador con ejemplos específicos de dominio	Bajar a ReAct puro (Concepto 10)
Reflexión que no mejora	Hacer criterios más específicos y verificables (umbrales numéricos, validación de esquema, reglas explícitas)	Usar un modelo distinto para el crítico; o herramientas explícitas de comprobación (parser, validador)	Quitar reflexión por completo si no aparece mejora
Fallos de enrutamiento multiagente	Cambiar el coordinador de enrutamiento basado en LLM a enrutamiento determinista para casos conocidos	Hacer contratos de handoff explícitos y estructurados (modelos Pydantic, no texto libre)	Fusionar especialistas solapados; colapsar a agente único si Q5 no se cumple realmente
Complejo pero no mejor	Quitar la capa superior (el patrón añadido más recientemente) y medir	Quitar la siguiente capa; iterar	Volver a agente único con línea base fuerte; reconstruir solo con evidencia

El principio: arregla en el alcance más pequeño que funcione. Afinar prompts es más barato que cambiar contratos de herramientas. Cambiar contratos de herramientas es más barato que cambiar arquitectura. Cambiar arquitectura es más barato que reescribir. La mayoría de las señales de fallo se pueden abordar a nivel de prompt o contrato; no recurras primero a la perilla de arquitectura.

La excepción: si una señal de fallo se repite después de arreglos de prompt y contrato, eso es evidencia de que la arquitectura realmente está equivocada. Distingue "puedo seguir parcheando esto" de "sigo parcheando esto y sigue fallando de formas nuevas". Lo segundo es la señal para volver a seleccionar el patrón.

Idea central del Concepto 15: las señales de fallo no siempre requieren cambios arquitectónicos. La mayoría se puede arreglar a nivel de prompt (condiciones de parada, especificación de criterios, límites de roles) o contrato (descripciones de herramientas, estructuras de handoff, lógica de enrutamiento). El cambio arquitectónico es el último recurso, no el primer movimiento. La excepción: fallos recurrentes después de arreglos de prompt y contrato indican que el patrón en sí es incorrecto; ahí es cuando vuelves a recorrer el árbol de decisión.

Concepto 16: Cuándo se equivoca el árbol de decisión

El árbol de decisión es bueno. No es infalible. Tres situaciones en las que la primera respuesta del árbol es incorrecta, y qué hacer:

Situación 1, las propiedades de la tarea cambian después del despliegue. Lo que era un flujo estable se vuelve adaptativo (el negocio añade 20 casos límite). Lo que era expertise especializada se vuelve común (el LLM mejora y un generalista ahora puede manejar el trabajo que antes necesitaba especialista). Ejemplo real: un flujo de soporte al cliente que empezó como pipeline secuencial (extraer → clasificar → enrutar → responder) se vuelve adaptativo cuando el equipo añade personalización, conciencia de historial y ajuste de tono. El patrón original ahora es incorrecto, pero el sistema está en producción.

El arreglo: la observabilidad de señales de fallo del Concepto 14 debería atraparlo. Cuando las rutas del flujo empiezan a fallar porque las entradas reales ya no coinciden con la forma esperada, esa es la señal. Recorre otra vez el árbol de decisión con las nuevas propiedades de la tarea. No finjas que la elección original sigue siendo correcta porque es lo desplegado.

Situación 2, subtareas distintas necesitan patrones distintos. El agente de soporte de nivel 1 de Maya maneja enrutamiento, consultas, reembolsos, escalamientos. Algunas son forma-flujo (consulta: determinista). Algunas son forma-ReAct (investigación de reembolso: adaptativa). El patrón de agente único ReAct las maneja todas, pero adecuadamente, no óptimamente. El arreglo: reconoce que esto es una oportunidad de composición multipatrón. Un coordinador de alto nivel enruta a subsistemas específicos por patrón: flujo secuencial para consultas, ReAct + herramientas para investigaciones, planificación para disputas complejas de varios pasos. La composición es multiagente, pero los especialistas no son por rol; son por patrón.

Situación 3, las restricciones cambian la respuesta. El árbol de decisión asume que puedes elegir el patrón que encaja. A veces no puedes. Un presupuesto de latencia duro descarta reflexión. Un presupuesto de costo duro descarta multiagente. Un requisito de simplicidad duro descarta planificación. Cuando las restricciones excluyen el patrón que elegiría el árbol, tienes que cambiar las restricciones, cambiar el alcance de la tarea o aceptar peor encaje.

El arreglo: registra explícitamente las elecciones de patrón impulsadas por restricciones como decisión separada. Documenta: "el árbol apuntaba a multiagente, pero elegimos agente único porque el techo de costo lo exigía. Limitación conocida: serán más comunes los fallos impulsados por especialización". Esto vuelve visible y revisable la elección por restricción; cuando cambien las restricciones, sabrás qué reconsiderar.

Idea central del Concepto 16: el árbol de decisión es un punto de partida, no una respuesta permanente. Tres situaciones exigen volver a recorrerlo: cambian las propiedades de la tarea después del despliegue (se atrapa con observabilidad de señales de fallo), subtareas distintas necesitan patrones distintos (compón varios patrones) y restricciones excluyen la respuesta del árbol (documenta explícitamente la elección impulsada por restricción). La selección de patrones es iterativa, no de una sola vez.

Concepto 16.5: La galería de antipatrones, elecciones equivocadas comunes y qué hacer en su lugar

Antes de que la Parte 5 recorra ejemplos trabajados de selección correcta de patrones, aquí está el inverso: una galería rápida de elecciones equivocadas comunes y la mejor alternativa para cada una. Reconocer antipatrones es una habilidad propia: los estudiantes que internalizan el árbol de decisión aún pueden caer en sobredimensionamiento o quedarse cortos cuando la tentación arquitectónica es fuerte.

La asimetría visual, 5 antipatrones de sobredimensionamiento frente a 3 de quedarse corto, refleja la frecuencia real en sistemas de producción. Sobredimensionar es más visible porque los patrones elaborados hacen mejores demos; quedarse corto es más peligroso porque sus modos de fallo son sutiles. Vale la pena atrapar ambos por igual durante la revisión de diseño. La tabla siguiente da el texto completo de la galería:

Mala elección	Por qué falla	Mejor patrón inicial
Multiagente para generación de contenido simple (por ejemplo, tres agentes, investigador + redactor + revisor, para una sola publicación de LinkedIn)	La sobrecarga de coordinación supera ampliamente la ganancia de especialización. La salida del "investigador" es un párrafo que el "redactor" resume. Fallos de enrutamiento, desajustes de formato de handoff, tres veces los tokens sin mejora medible de calidad.	Agente único + ReAct + herramientas (Concepto 10), o flujo de trabajo secuencial (Concepto 9) si la forma del contenido es fija. Recurre a multiagente solo cuando Q5 se activa de verdad.
ReAct para procesamiento fijo de facturas (extraer → validar → almacenar → notificar)	El agente a veces omite pasos, a veces revalida trabajo que ya hizo, a veces inventa llamadas a herramientas. Agotamiento de presupuesto de pasos en 5% de runs. El equipo añade "condiciones de parada" al prompt, tratando síntomas en lugar del desajuste arquitectónico.	Flujo de trabajo secuencial (Concepto 9). La ruta es conocida y estable; un bucle impulsado por LLM es la herramienta equivocada.
Planificador para depuración abierta (el planificador produce un plan de 5 etapas; la ejecución diverge de inmediato)	La estructura de la tarea no es articulable de antemano. El planificador produce un plan que se vuelve incorrecto en la etapa 2. La divergencia plan-ejecución domina la traza. El equipo aprieta el planificador sin fin o trata el plan como decorativo.	Agente único + ReAct + herramientas (Concepto 10). ReAct puro maneja tareas donde forma y contenido son desconocidos.
Reflexión en tareas con criterios de calidad vagos (copy de marketing, respuestas conversacionales, contenido subjetivo)	Crítico y generador comparten puntos ciegos. La crítica se vuelve aprobación mecánica. La latencia se duplica; la calidad queda plana. Peor: el equipo gana falsa confianza en que "la IA lo revisó".	Quitar reflexión por completo (respuesta correcta más común) o reemplazar reflexión con LLM por revisión humana (Concepto 12). La reflexión con LLM solo funciona con criterios verificables.
Un agente gigante para muchos dominios (facturación + técnico + cuenta + reembolso + ventas, todo en un agente con una indicación de sistema de 4.000 tokens)	Desborde de contexto, confusión de roles y errores de enrutamiento de herramientas se encadenan. La reflexión ayuda marginalmente, pero no arregla la causa raíz. El agente responde preguntas técnicas con política de facturación y viceversa.	Sistema especialista multiagente (Concepto 13), especialistas por dominio, coordinador enruta por clasificación de intención. La afirmación de especialización de Q5 se activa de verdad aquí.
Añadir planificación a un flujo estable (el planificador produce el mismo plan cada vez porque la tarea es la misma)	Cada run paga por una llamada adicional al LLM que no aporta nada. Cuando la entrada es ligeramente inusual, el planificador produce un plan ligeramente distinto, y ahora el equipo tiene que depurar "¿por qué el planificador tomó una ruta distinta?".	Flujo de trabajo secuencial (Concepto 9). Cuando la ruta es fija, no se necesita planificación; escribe la ruta directamente.
Agente único puro para tareas que necesitan contexto masivo (un agente que carga 20 documentos fuente, tres bases de conocimiento y un esquema de base de datos en su prompt)	Degradación de ventana de contexto. El razonamiento del agente se debilita a medida que crece el contexto; el modelo omite cosas que jurarías que debería ver.	Sistema especialista multiagente con contextos enfocados (Concepto 13). Cada especialista carga solo el contexto que necesita; el sintetizador compone sus salidas. La afirmación de contexto de Q5 se activa de verdad aquí.
Saltarse reflexión en salidas que realmente necesitan verificación (consultas SQL a producción, borradores legales a clientes, cambios de código a repos)	Se entregan errores sutiles. El equipo añade pruebas después del hecho, que atrapan menos errores que capturarlos en el momento de generación.	Capa de reflexión encima del patrón central (Concepto 12). Cuando los criterios son verificables, la reflexión aporta valor real. Q4 se activa; no la omitas.

El patrón en la galería de antipatrones: la mayoría de las malas elecciones están impulsadas por sobredimensionamiento por atractivo estético (multiagente se ve impresionante, planificación se ve rigurosa, reflexión se ve cuidadosa). Un subconjunto más pequeño pero igual de importante está impulsado por sesgo hacia simplicidad (un agente grande, ReAct puro en tareas de flujo, sin reflexión en salidas verificables). El árbol de decisión está diseñado para exponer ambos tipos de error: preguntando por propiedades de la tarea en lugar de preferencias de patrón.

Un autochequeo útil antes de cerrar una elección de patrón: "Si un ingeniero sénior revisara mi elección, ¿cuál sería la objeción más probable?" Si no puedes predecirla y defenderte contra ella, probablemente todavía no tomaste una decisión fundamentada.

Idea central del Concepto 16.5: la selección de patrones falla con más frecuencia por sobredimensionamiento (más elaborado de lo necesario) y con menos frecuencia, pero de forma igual de dañina, por quedarse corto (más simple de lo necesario). La galería de antipatrones nombra las formas más comunes de ambos modos de fallo. Internalizarlas acelera la disciplina del árbol de decisión; reconocer el antipatón en tu propia arquitectura borrador es la habilidad práctica que produce el marco. Consulta la plantilla de revisión de diseño de una página al final de este curso. Incluye una verificación explícita de antipatrones ("si un ingeniero sénior revisara esta elección, ¿qué objetaría?") que operacionaliza esta disciplina para revisiones de diseño en equipo.

Parte 5: El laboratorio de decisión

La Parte 5 recorre el árbol de decisión sobre cinco tareas reales. Cada decisión es una clasificación trabajada: la tarea, las cinco preguntas respondidas, el patrón resultante, el bosquejo de topología de despliegue y las señales de eval que debes vigilar. El punto no es la respuesta correcta; es ver la disciplina aplicada.

Cada decisión sigue la misma forma:

La tarea (un párrafo)
Recorrer el árbol (cinco preguntas respondidas con razonamiento específico de la tarea)
Elección de patrón y justificación
Bosquejo de topología de despliegue (qué componentes de nube, qué tablas nuevas en Neon, qué configuración de bridge Worker)
Señales de eval que vigilar (qué patrones de eval, qué evaluadores de Phoenix)
Recuadro de ruta simulada para lectores que no hicieron los cursos de despliegue y evals

Decisión 1: Agente de soporte de nivel 1 de Maya

La tarea. Un agente de soporte al cliente maneja consultas entrantes. El agente puede: consultar información de cuenta, consultar historial de transacciones, consultar reglas de política, buscar en una base de conocimiento, emitir reembolsos dentro de límites de autoridad, escalar a revisión humana cuando se excede la autoridad o cuando el caso es ambiguo. El agente mantiene una interacción conversacional con el cliente.

Tu turno. Recorre las cinco preguntas sobre esta tarea antes de seguir leyendo. Comprométete con un patrón y luego compárate con la respuesta trabajada. (O pega la tarea en tu IA y pídele que te interrogue de Q1 a Q5, cuestionándote cuando tu razonamiento sea delgado).

Recórrelo tú primero y luego abre la respuesta trabajada.

Recorrer el árbol.

Q1: ¿La ruta de solución se puede definir de antemano? No. Las consultas de clientes varían enormemente: "¿dónde está mi reembolso?" necesita consulta; "me cobraron dos veces" necesita investigación; "quiero cancelar" puede necesitar cambios de cuenta; "¿puedes explicarme mi factura?" necesita consulta de política y explicación. La ruta es desconocida.

Q2: N/A (Q1 fue no, así que se omite Q2).

Q3: ¿La estructura de la tarea es articulable antes de ejecutar? No. No hay "etapas" articulables; hay investigación que termina cuando termina. El agente puede hacer una consulta y responder, o cinco consultas y tres verificaciones de política. Sin estructura clara de etapas.

Q4: ¿La calidad importa más que la velocidad? Mixto. La velocidad importa porque los clientes esperan en una conversación en vivo; la calidad importa porque decisiones de reembolso incorrectas cuestan dinero al negocio. Pero los criterios de evaluación de "buena respuesta" no son verificables en tiempo real. Implican juicio matizado sobre si la situación del cliente se manejó bien. La reflexión no encaja aquí.

Q5: ¿Hay un cuello de botella de especialización, contexto o escala? Fronterizo. El agente sí necesita manejar facturación, técnico, cuenta y reembolsos, lo que se siente como caso de especialización. Pero: el volumen de solapamiento (la mayoría de clientes tienen preguntas que cruzan categorías) significa que el enrutamiento a especialistas crearía más fricción de handoff que beneficio de especialización. Agente único es la decisión correcta.

Elección de patrón: agente único + ReAct + herramientas. El patrón del Concepto 10.

Bosquejo de topología de despliegue. Esto es exactamente lo que construyó el despliegue en la nube del Worker de soporte al cliente. Stack completo: FastAPI en ACA, Neon para sesiones, runs y trazas, R2 para documentos adjuntos, Cloudflare Sandbox mediante bridge Worker para la herramienta apply_patch que el agente usa ocasionalmente para generar archivos de documentación de reembolso, background worker para runs que superan 30 segundos. Sin cambios de despliegue frente a lo que ya entrega ese despliegue.

Señales de eval que vigilar. Los fallos característicos de ReAct:

Anomalías de longitud de traza (dashboard Phoenix)
Duplicación de llamadas a herramientas (el agente consulta la misma cuenta tres veces)
Divergencia razonamiento-acción (evaluador Phoenix de corrección de herramientas)
Terminación prematura (el agente dice "no puedo ayudar" demasiado pronto)
Agotamiento de presupuesto de pasos (el agente supera 25 pasos sin producir salida)

Modo de fallo más probable en producción: el agente entrará en bucle en casos ambiguos de reembolso. El arreglo: añadir condiciones de parada explícitas ("si no puedes determinar el monto correcto de reembolso en 3 consultas, escala") y aclarar el límite entre "investigar más" y "escalar a humano".

Capa operativa. La configuración de Maya es la composición canónica de Inngest para un agente de soporte al cliente:

Trigger: TriggerEvent(event="customer/email.received"); el webhook de ingreso de correo dispara el evento; la función despierta por cada correo de cliente.
Durabilidad: envolver Runner.run(support_agent, ...) en un solo step.run("agent-loop", ...). Fallo a mitad de bucle → todo el run del agente reintenta; los subpasos dentro del bucle son internos al SDK y no durablemente separados.
HITL en escalamiento: la herramienta escalate_to_human dispara refund/approval.requested y la función se suspende mediante step.wait_for_event hasta 4 horas. Cero cómputo consumido mientras espera. El humano aprueba vía Slack; la función se reanuda con el veredicto.
Concurrencia: concurrency=[Concurrency(limit=10, key="event.data.customer_id"), Concurrency(limit=50)], como máximo 2-3 runs concurrentes por cliente (un cliente enojado no puede dejar a todos sin recursos) y 50 globales (protege el rate limit de OpenAI y el pool de conexiones de Neon).

Recuadro de ruta simulada para la Decisión 1. Incluso sin los cursos de despliegue y evals, puedes hacer este ejercicio en papel: recorre las cinco preguntas para la tarea de Maya, justifica la elección de patrón y bosqueja qué herramientas necesitaría el agente (consulta de cuenta, consulta de transacciones, búsqueda de política, emisión de reembolso, escalamiento). La disciplina de clasificación es lo que enseña la Decisión 1; los detalles de despliegue la profundizan, pero no son necesarios para internalizar el marco.

Decisión 2: Agente de respuesta a incidentes

La tarea. Un agente on-call recibe alertas (de sistemas de monitoreo, reportes de clientes o equipos internos) y ejecuta la respuesta inicial a incidentes: comprobar salud de servicios, correlacionar con despliegues recientes, identificar causa raíz probable, ejecutar runbook de remediación si aplica, escalar al humano on-call si la situación es novedosa o severa. El agente debe producir un informe de incidente claro.

Recórrelo tú primero y luego abre la respuesta trabajada.

Recorrer el árbol.

Q1: ¿La ruta de solución se puede definir de antemano? Parcialmente. Hay una estructura estándar: "comprobar salud de servicios, correlacionar despliegues, identificar causa, intentar remediación, escalar si hace falta". Pero la ruta específica depende de lo que realmente esté ocurriendo. Un pico de latencia en el servicio A puede llevar a "revertir despliegue reciente"; un pico de errores 500 en el servicio B puede llevar a "reiniciar pod"; un problema reportado por cliente puede llevar a "investigar flujo de datos específico de usuario". La ruta es desconocida a nivel de paso, pero estructurada a nivel de etapa.

Q2: N/A.

Q3: ¿La estructura de la tarea es articulable antes de ejecutar? Sí. Las etapas están claras: triage → diagnosticar → remediar → informar. Cada incidente pasa por estas etapas, aunque el trabajo específico dentro de cada una varíe. Estructura articulable.

Q4: ¿La calidad importa más que la velocidad? En respuesta a incidentes, la velocidad importa enormemente: cada minuto de incidente cuesta al negocio. Pero la calidad también importa porque una remediación equivocada puede empeorar las cosas. La reflexión sobre pasos de remediación antes de ejecutarlos está justificada. Un pase rápido de crítica que pregunte "¿esta remediación es segura? ¿coincide con los síntomas reales del incidente?" vale la latencia. Añade reflexión sobre decisiones de remediación.

Q5: ¿Hay un cuello de botella de especialización, contexto o escala? No. Un agente con acceso a monitoreo, historial de despliegues, biblioteca de runbooks y herramientas de remediación puede manejar esto. No uses multiagente.

Elección de patrón: planificación + ejecución ReAct, con reflexión sobre pasos de remediación. Conceptos 11 + 12 en capas.

Bosquejo de topología de despliegue. Construido sobre el despliegue de ReAct (Concepto 10) más persistencia de plan (Concepto 11). Adiciones específicas:

Nueva tabla de Neon: incidents (incident_id, severity, plan, current_stage, remediation_history)
El plan se almacena explícitamente y se actualiza a medida que completan etapas
La reflexión sobre remediación se ejecuta como agente separado (se recomienda modelo distinto, una instancia Claude criticando una instancia GPT, o viceversa, para evitar solapamiento de puntos ciegos)
El patrón de background worker es obligatorio (los runs de incidente pueden tardar 5-15 minutos)

Señales de eval que vigilar.

Divergencia plan-ejecución (¿el plan coincide con lo que realmente ocurrió?)
Efectividad de reflexión sobre remediación (¿la crítica atrapó remediaciones inseguras? si pasan meses sin hacerlo, la reflexión quizá aprueba mecánicamente)
Métrica de tiempo hasta resolución (la respuesta a incidentes se juzga por velocidad; rastrea y alerta regresiones)
Exactitud de escalamiento (¿el agente escaló cuando debía? ¿remedió cuando debía?)

Modo de fallo más probable en producción: el planificador produce planes demasiado detallados para incidentes simples, añadiendo latencia. El arreglo: entrenar el planificador con ejemplos de granularidad de plan apropiada: planes cortos para incidentes claros, planes más largos para ambiguos. El valor del plan no está en ser exhaustivo; está en tener el tamaño correcto para la situación.

Capa operativa. Respuesta a incidentes es el patrón que usa casi todas las primitivas de Inngest: cron, eventos, fan-out, durabilidad, HITL, replay:

Triggers: triggers dobles, TriggerCron(cron="*/5 * * * *") para comprobaciones proactivas de salud Y TriggerEvent(event="incident/alert.fired") para incidentes reactivos. La misma forma de función maneja ambos.
Durabilidad por etapa: un step.run por etapa de planificación y cada paso de remediación; si la remediación falla a mitad, las etapas anteriores quedan memoizadas.
HITL en remediación: entre la salida del planificador y la ejecución, step.wait_for_event("await-remediation-approval", timeout=timedelta(minutes=15)) pone la puerta del revisor humano. Timeout ajustado porque los incidentes son sensibles al tiempo.
Replay para arreglos de bugs por falsos positivos: cuando un script de remediación tiene un bug que hace fallar incidentes de una forma particular, arregla el script y haz replay masivo de los incidentes fallidos desde el dashboard de Inngest. Sin re-triage manual de incidentes.

Recuadro de ruta simulada para la Decisión 2. Esta es la primera decisión que introduce composición de patrones (planificación + reflexión). Incluso en papel, el ejercicio vale la pena: observa que la elección de añadir reflexión no vino de Q4 sola, sino de Q4 aplicada específicamente al paso de remediación. La reflexión rara vez es todo o nada; a menudo se añade a salidas específicas de alto impacto.

Decisión 3: Agente de investigación de mercado

La tarea. Dado un tema ("panorama competitivo en middleware de IA agéntica") y un brief de investigación (preguntas clave, requisitos de profundidad, fecha límite), el agente produce un informe de investigación. El trabajo involucra: identificar fuentes relevantes, buscar en varias bases de datos, leer y extraer de documentos, comparar afirmaciones entre fuentes, redactar hallazgos y producir un informe final.

Recórrelo tú primero y luego abre la respuesta trabajada.

Recorrer el árbol.

Q1: ¿La ruta de solución se puede definir de antemano? No. Qué fuentes consultar, qué competidores investigar y qué análisis ejecutar depende de lo que se descubra por el camino. Ruta desconocida.

Q2: N/A.

Q3: ¿La estructura de la tarea es articulable antes de ejecutar? Sí. La forma estándar de informe de investigación: recopilar datos → analizar → sintetizar → redactar → revisar. Aunque las fuentes y análisis específicos sean desconocidos, las fases principales están claras. Estructura articulable.

Q4: ¿La calidad importa más que la velocidad? Sí, con fuerza. Los informes de investigación los leen personas que toman decisiones; errores factuales y análisis débiles tienen consecuencias reales. Los criterios de calidad son parcialmente verificables: "todas las afirmaciones tienen fuente", "el análisis competitivo cubre cada actor principal", "la síntesis responde las preguntas del brief". La reflexión está justificada, especialmente sobre la síntesis y el borrador final.

Q5: ¿Hay un cuello de botella de especialización, contexto o escala? Probablemente sí por contexto. La investigación profunda exige cargar grandes cantidades de material fuente; hacerlo en la ventana de contexto de un solo agente arriesga degradación de razonamiento. Dividir en agentes que investigan-y-resumen por fuente y producen briefs enfocados, para luego componerlos, es el patrón correcto. Multiagente por razones de gestión de contexto.

Elección de patrón: sistema especialista multiagente, con planificación en la capa superior, ReAct dentro de especialistas de investigación y reflexión sobre la síntesis final. Composición de Conceptos 11, 13 y 12.

Bosquejo de topología de despliegue. Stack completo de nube más adiciones multiagente (Concepto 13):

Estructura de run padre + run por especialista en Neon (parent_run_id, agent_role)
Logs de auditoría de enrutamiento para qué especialista recibió qué fuente
Seguimiento de costos por especialista (los agentes de investigación que leen PDFs de 50 páginas pueden quemar tokens rápido)
El bridge Worker maneja herramientas de lectura de documentos compartidas entre especialistas
El agente agregador lee de una tabla compartida de Neon donde los especialistas depositan sus resúmenes

Señales de eval que vigilar.

Tres marcadores separados: calidad de investigación por especialista, exactitud de enrutamiento (¿el especialista correcto recibió la fuente correcta?), calidad de integración (¿el informe final sintetiza bien los hallazgos de especialistas?)
Divergencia plan-ejecución sobre el plan de alto nivel
Efectividad de reflexión sobre la síntesis final
Costo por salida correcta (multiagente + reflexión vuelve esto caro; rastrea y justifica)

Modo de fallo más probable en producción: los especialistas producen briefs individuales excelentes que el agregador no puede sintetizar limpiamente porque los briefs usan formatos o terminología inconsistentes. El arreglo: imponer formatos de handoff estructurados (esquemas Pydantic para la estructura de brief), para que el agregador reciba entradas con forma uniforme.

Capa operativa. Investigación de mercado es el ejemplo principal de fan-out en este curso, el patrón para el que fueron diseñadas las primitivas de control de flujo de Inngest:

Patrón de disparador fan-out: la función coordinadora dispara un evento research/competitor.research por competidor; cada uno dispara un run de función independiente. N competidores → N runs de función paralelos, todos rastreados por separado, todos durablemente independientes.
Límite de concurrencia por tenant: concurrency=[Concurrency(limit=5, key="event.data.tenant_id")] en la función de investigación de competidor evita que la solicitud "investiga 50 competidores" de un tenant monopolice el sistema.
Durabilidad por especialista: cada run de investigación de competidor tiene sus propias llamadas step.run (búsqueda web, descarga de documento, generación de brief); un fallo a mitad de investigación solo reintenta el paso fallido, no todo el run de investigación.
Agregación como función separada: cuando completan todos los runs especialistas (Inngest emite eventos "all done"), una función sintetizadora disparada por research/landscape.synthesize lee los briefs y compone el informe final. Desacoplado mediante eventos; sin estado compartido.
Visibilidad de costo por especialista: el dashboard por función de Inngest muestra gasto de tokens por competidor; los outliers (competidor X costó 5× más que los otros) son visibles de inmediato.

Recuadro de ruta simulada para la Decisión 3. Esta decisión muestra composición de patrones: multiagente no reemplaza los otros patrones; los compone. El agente de planificación usa planificación; los especialistas de investigación usan ReAct; el agente de síntesis usa reflexión. Multiagente es la topología; los patrones dentro de la topología siguen siendo los mismos cinco patrones.

Decisión 4: Agente de onboarding empresarial

La tarea. Cuando un nuevo cliente empresarial se registra, un agente ejecuta el flujo de onboarding: aprovisiona su tenant (crea cuentas, bases de datos, configuración), carga datos semilla, invita a sus administradores, agenda reuniones de kickoff y envía materiales de bienvenida. El trabajo involucra varios pasos deterministas de aprovisionamiento y algunas comunicaciones personalizadas.

Recórrelo tú primero y luego abre la respuesta trabajada.

Recorrer el árbol.

Q1: ¿La ruta de solución se puede definir de antemano? Sí. El onboarding tiene una secuencia fija: provisionar → configurar → cargar datos semilla → invitar → agendar → enviar bienvenida. Cada onboarding pasa por estos pasos en este orden. El contenido de algunos pasos se personaliza (el mensaje de bienvenida referencia el nombre e industria del cliente), pero la secuencia de pasos es invariante. Ruta conocida.

Q2: ¿El flujo de trabajo es fijo y estable entre runs? Sí. Cada cliente empresarial sigue el mismo flujo de onboarding. Estable.

Q3, Q4, Q5: N/A o no. El árbol de decisión termina en Q2 porque el flujo es fijo.

Elección de patrón: flujo de trabajo secuencial. Concepto 9.

Bosquejo de topología de despliegue. Stack de nube mínimo:

FastAPI en ACA
Neon para estado de onboarding (qué clientes están en qué paso)
R2 para documentos (PDFs de bienvenida, guías de onboarding)
Llamadas al LLM incrustadas en pasos de personalización (generación de mensaje de bienvenida, sugerencias de nombres de cuenta si las solicita el cliente)
Sin sandbox. Sin bridge Worker. Sin patrón de background worker para razonamiento agéntico de larga duración (aunque el flujo en sí podría ejecutarse como job en background para manejar escala).

Este es el despliegue que es significativamente más barato que el stack completo, porque la tarea no necesita la mayor parte de la complejidad del despliegue en la nube.

Señales de eval que vigilar.

Corrección a nivel de paso (cada paso de aprovisionamiento tuvo éxito; la extracción devolvió esquemas válidos)
Tasa de finalización de flujo (¿qué fracción de onboardings completa con éxito?)
Calidad de personalización (mensajes de bienvenida generados por LLM; Phoenix puede calificar tono y exactitud factual)
Modo de fallo: pasos de flujo aplicados a entradas equivocadas (brechas de validación)

Modo de fallo más probable en producción: una empresa con caso límite (industria inusual, requisitos especiales de cumplimiento) no encaja en el flujo estándar. El arreglo: (a) añadir ramificación explícita al flujo para el caso límite (si tienes pocos casos límite), o (b) reconocer que el flujo se está volviendo variable y considerar actualizar a ReAct + herramientas (si los casos límite proliferan). Vigila esta transición con el tiempo: los flujos suelen empezar estables y volverse gradualmente adaptativos.

Capa operativa. Onboarding empresarial es el ejemplo más limpio de flujo secuencial con Inngest en este curso: cada paso es un step.run, sin complejidad agéntica:

Trigger: TriggerEvent(event="customer/enterprise.signed_up"), se dispara cuando se cierra el trato en el CRM.
Un step.run por paso de onboarding: step.run("provision-tenant", ...), step.run("configure-defaults", ...), step.run("seed-data", ...), step.run("invite-admins", ...), step.run("schedule-kickoff", ...), step.run("send-welcome", ...). Cada paso es durable; fallo en el paso 4 → los pasos 1-3 quedan memoizados.
Sin HITL necesario: el onboarding está totalmente automatizado; no hay llamadas step.wait_for_event en la ruta estándar.
step.sleep para acciones demoradas: step.sleep("wait-2-days-before-followup", timedelta(days=2)) agenda un seguimiento que se dispara después de completar el onboarding, con cero cómputo consumido durante la espera.
Pareja con cron: una función separada disparada por cron (TriggerCron("0 9 * * *")) recorre diariamente la base de datos de clientes buscando onboardings atascados (un paso falló y agotó reintentos); la función cron dispara eventos de recuperación para los casos atascados.

Este es el despliegue sustancialmente más barato que los demás, e Inngest hace visible la disciplina de costo: el dashboard de función muestra tasas de éxito paso a paso y costos paso a paso, así que puedes ver exactamente qué paso de onboarding es el cuello de botella.

Recuadro de ruta simulada para la Decisión 4. Esta decisión importa porque es el ejemplo negativo de patrones agénticos. La tarea no necesita razonamiento agéntico. Un flujo de trabajo con llamadas al LLM incrustadas es más barato, más confiable y más fácil de depurar. No recurras a ReAct cuando un flujo funciona. Esta es la disciplina más importante que enseña el árbol de decisión.

Decisión 5: Agente de coding (ruta avanzada)

La tarea. Un agente de coding recibe una solicitud de función y produce una implementación funcional: lee la base de código existente, diseña el cambio, escribe código, escribe pruebas, ejecuta las pruebas, corrige fallos y produce una PR lista para revisión humana. La base de código es grande, los cambios pueden ser complejos y la corrección importa.

Recórrelo tú primero y luego abre la respuesta trabajada.

Recorrer el árbol.

Q1: ¿La ruta de solución se puede definir de antemano? No. El trabajo de coding involucra descubrimiento continuo: qué existe en la base de código, cómo está estructurado el código existente, qué casos límite revelan las pruebas. Ruta desconocida.

Q2: N/A.

Q3: ¿La estructura de la tarea es articulable antes de ejecutar? Parcialmente. Hay una forma clara de alto nivel: entender el requisito → entender la base de código → diseñar el cambio → implementar → probar → corregir → producir PR. Pero: en cambios complejos, la fase de diseño puede iterar (diseñar → descubrir restricción → revisar diseño → redescubrir restricción). Articulable, pero con necesidades internas de adaptación.

Q4: ¿La calidad importa más que la velocidad? Sí, muchísimo. Código que llega a producción tiene consecuencias reales. Los criterios de calidad son verificables: las pruebas pasan o fallan, los type checks pasan o fallan, el linter pasa o falla, la revisión de código identifica problemas específicos. La reflexión está muy justificada.

Q5: ¿Hay un cuello de botella de especialización, contexto o escala? Sí de verdad tanto por especialización como por contexto. El coding involucra al menos tres conjuntos de habilidades distintos: generación de código (escribir buen código), revisión de seguridad (atrapar vulnerabilidades) y documentación (explicar el cambio). Cada uno se beneficia de un agente enfocado. Multiagente justificado.

Elección de patrón: sistema especialista multiagente, con planificación arriba, ReAct + herramientas dentro de especialistas y reflexión explícita sobre salidas de código. Composición de los otros cuatro patrones.

Bosquejo de topología de despliegue. Stack completo de nube más extensiones multiagente:

Agente coordinador: recibe la solicitud de función y produce un plan con etapas (diseño → código → revisión → documentación)
Especialista programador: ReAct + herramientas (leer base de código, escribir archivos, ejecutar pruebas). Uso fuerte de sandbox (ejecutar pruebas, ejecutar código). Bridge Worker obligatorio.
Especialista revisor: ReAct + herramientas (leer salida del programador, ejecutar comprobaciones de seguridad, ejecutar linters). Uso más ligero de sandbox.
Especialista de documentación: más simple, posiblemente secuencial (extraer cambios → generar docs).
Capa de reflexión sobre la PR final del programador (¿pasan todas las pruebas? ¿coincide con el requisito?).
Runs por especialista en Neon; logs de auditoría de enrutamiento; seguimiento de costos por especialista (el programador dominará costos).

Señales de eval que vigilar. Todos los tres marcadores de multiagente, más métricas de reflexión. Enfoque particular en:

Eval de corrección de código (¿el código generado pasa las pruebas?)
Efectividad de revisión de seguridad (¿el revisor atrapó vulnerabilidades? la tasa de falsos positivos también importa)
Divergencia plan-ejecución (el plan del coordinador frente a lo que realmente se entregó)
Costo por PR (este patrón es caro; asegúrate de que se gane su costo)

Modo de fallo más probable en producción: el especialista revisor se vuelve el cuello de botella, ya sea demasiado estricto (rechaza código válido por problemas menores de estilo) o demasiado permisivo (aprueba código con bugs reales). El arreglo: criterios explícitos para las decisiones del revisor, y una eval separada que califique los juicios del revisor contra juicios de revisores humanos sobre el mismo código.

Capa operativa. El agente de coding usa cada primitiva de Inngest; este es el patrón que justifica la capa operativa completa:

Triggers: TriggerEvent(event="github/issue.assigned_to_agent"), se dispara cuando se asigna un issue; O un comando de chat en Slack dispara el evento.
Coordinación fan-out: la función coordinadora descompone la función en etapas y luego dispara eventos a funciones especialistas (coding/specialist.code, coding/specialist.review, coding/specialist.docs). Cada especialista es su propia función con su propia concurrencia y durabilidad.
step.run por edición de archivo: el especialista programador envuelve cada modificación de archivo en step.run("edit-{path}", ...) para que un fallo durante una edición multiarchivo no pierda ediciones completadas. La memoización es especialmente valiosa aquí; volver a ejecutar un cambio de código generado por LLM después de completarlo parcialmente es caro y arriesga divergir del plan original.
step.wait_for_event en merge de PR: después de que el agente produce la PR, la función se suspende mediante step.wait_for_event("await-human-merge-approval", timeout=timedelta(days=2)). El humano revisa en GitHub, aprueba; la función se reanuda para limpieza post-merge.
Concurrencia por tenant: concurrency=[Concurrency(limit=2, key="event.data.tenant_id")] en el especialista programador evita que un tenant monopolice capacidad de coding. (El coding es caro; los límites por tenant son críticos).
Prioridad para equidad por nivel: las tareas de coding de tenants Enterprise saltan delante del nivel Free en la cola (priority=Priority(run="100 - (event.data.tier_priority * 100)")).
Replay para fallo parcial: cuando el especialista revisor rechaza código por una razón corregible, el programador arregla y vuelve a disparar el evento de revisión; el dashboard de función muestra el historial de iteración por PR.
step.sleep para ventanas de seguridad: step.sleep("await-tests-stable", timedelta(hours=2)) después de hacer merge, espera 2 horas de runs de CI para confirmar que el cambio no rompió pruebas posteriores antes de que el agente marque el trabajo como completo.

Recuadro de ruta simulada para la Decisión 5. Esta es la decisión más difícil porque la tarea realmente necesita que todos los patrones se compongan juntos. El ejercicio aquí no es recordar qué patrones aplican; es ver cómo el árbol de decisión identifica sistemáticamente qué patrones componer y dónde. El agente de coding no es "avanzado" porque sea complejo; es avanzado porque la disciplina de composición de patrones requiere práctica.

Parte 6: Fronteras honestas

Concepto 17: Costo y latencia como restricciones arquitectónicas, no ocurrencias tardías

Hasta aquí, este curso ha tratado la selección de patrones como si costo y latencia fueran secundarios. En producción, a menudo son primarios. El Concepto 17 nombra explícitamente el perfil de costo y latencia de cada patrón, para que el árbol de decisión pueda recorrerse teniendo en cuenta restricciones de presupuesto.

Perfil de costo por patrón (órdenes de magnitud aproximados, suponiendo precios clase GPT-5):

Pattern	Cost per task	Cost driver
Sequential workflow	1× (baseline)	Number of LLM calls (often 1-3 per workflow)
Single agent + ReAct	3-10×	Number of ReAct iterations (model called once per loop)
Planning + ReAct execution	5-15×	Planning call + per-stage ReAct loops
Single agent + reflection	2-3× the underlying pattern	Critique + refinement passes
Multi-agent specialist	5-20×	Number of specialist runs + coordinator + integration

Las cifras son ilustrativas, no precisas. Lo que importa son las relaciones: un sistema multiagente con reflexión encima puede costar 30-60× más que un flujo de trabajo secuencial para el mismo volumen de tareas. Cuando ese multiplicador se justifica por calidad, perfecto. Cuando se justifica por estética, es una catástrofe de presupuesto esperando ocurrir.

Perfil de latencia por patrón:

Pattern	Latency	Driver
Sequential workflow	Lowest (~1-5s)	Deterministic steps + LLM calls in sequence
Single agent + ReAct	Medium (~10-30s)	One model call per loop; loops can stretch
Planning + ReAct	Medium-high (~30-90s)	Planning call + sequential stage execution
Single agent + reflection	2-3× underlying pattern	Critique + refinement add multiplicative latency
Multi-agent specialist	Variable	Parallel execution helps; coordination adds overhead

La integración con el árbol de decisión. Q4 (calidad frente a velocidad) aborda implícitamente la latencia. Q5 (especialización/escala) aborda implícitamente el costo. Pero el árbol de decisión no dice explícitamente "la respuesta es un patrón menos elaborado de lo que sugiere el árbol porque tu presupuesto de latencia es duro". Esa es una decisión de capa de restricciones encima del árbol.

La disciplina práctica: antes de recorrer el árbol de decisión, escribe tus presupuestos de latencia y costo. Si el patrón elegido por el árbol viola cualquiera de los presupuestos, tienes tres opciones:

Cambiar las restricciones. Conseguir más presupuesto, elevar la tolerancia de latencia o aceptar una entrega más lenta.
Cambiar el alcance. Reducir lo que debe hacer el sistema, para que un patrón menos elaborado pueda manejarlo.
Aceptar peor encaje. Usar un patrón menos elaborado y aceptar que ocurrirán algunos modos de fallo que el patrón más elaborado habría atrapado.

Documenta qué opción elegiste y por qué. Cuando el sistema muestre los modos de fallo que el patrón elaborado habría prevenido, querrás recordar qué trade-off hiciste.

Idea central del Concepto 17: costo y latencia son restricciones arquitectónicas, no ocurrencias tardías. Cada patrón tiene un perfil característico de costo y latencia, y los multiplicadores se componen cuando se componen patrones. Multiagente con reflexión puede costar 30-60× un flujo de trabajo secuencial para el mismo volumen de tareas (relación ilustrativa). El árbol de decisión aborda esto implícitamente mediante Q4 y Q5, pero las restricciones explícitas de presupuesto a veces anulan la respuesta del árbol; documenta la anulación y acepta conscientemente los modos de fallo resultantes.

Concepto 18: Composición de patrones, varios patrones en distintas capas

Este curso en gran medida ha tratado los patrones como si eligieras uno. Los sistemas reales suelen componer patrones en distintas capas: un agente de planificación arriba, ReAct + herramientas dentro de cada etapa del plan, reflexión sobre la salida final. Las Decisiones 3 y 5 ya lo mostraron; el Concepto 18 lo nombra como movimiento arquitectónico de primera clase.

Tres formas de composición que vale la pena reconocer:

Composición jerárquica. Un patrón de nivel superior envuelve patrones de nivel inferior. Ejemplos:

Agente de planificación (arriba) + ReAct + herramientas (dentro de cada etapa)
Coordinador multiagente (arriba) + flujos de trabajo secuenciales (dentro de especialistas)
ReAct (arriba) + flujo de trabajo secuencial (como herramienta que el agente ReAct llama cuando necesita trabajo determinista)

Composición secuencial. Los patrones se ejecutan uno después de otro, y la salida del primero alimenta al segundo. Ejemplos:

Flujo de trabajo secuencial (extraer datos estructurados) → agente ReAct (investiga los datos estructurados)
Agente ReAct (genera salida) → capa de reflexión (critica y refina)

Composición condicional. Patrones distintos manejan casos distintos, con un router que selecciona el patrón. Ejemplos:

Para solicitudes de forma conocida, enrutar a flujo secuencial; para solicitudes de forma desconocida, enrutar a ReAct
Para salidas de alto impacto, aplicar reflexión; para salidas de bajo impacto, omitirla

La regla pragmática de composición: la elección de patrón de cada capa debe justificarse con las mismas cinco preguntas, aplicadas al alcance de esa capa. El patrón de alto nivel se elige recorriendo el árbol sobre la tarea completa. El patrón de cada subcomponente se elige recorriendo el árbol sobre lo que hace ese subcomponente. No compongas patrones porque la composición suene sofisticada; compónlos porque las propiedades de la tarea de cada capa lo exigen.

El error de composición más común: añadir capas porque añadir capas parece buena ingeniería. Un agente de coding que es multiagente + planificación + reflexión en cada salida y un patrón de circuit breaker envolviéndolo todo suena riguroso; a menudo es innecesario. Prueba la composición quitando la capa superior. Si las salidas no se degradan, la capa no estaba ganándose su costo.

Idea central del Concepto 18: los sistemas reales componen patrones en distintas capas: jerárquica (un patrón envuelve otro), secuencial (la salida de uno alimenta al otro), condicional (patrones distintos para casos distintos). La elección de patrón de cada capa debe justificarse recorriendo el árbol de decisión en el alcance de esa capa. El error de composición más común es añadir capas porque las arquitecturas en capas suenan sofisticadas; prueba quitando la capa superior y comprobando si la calidad se degrada.

Parte 7: Cierre

Concepto 19: La selección de patrones como tejido conectivo en el currículo de Agent Factory

Este curso es el puente entre qué es un agente (el curso de construcción de agentes, sobre bucles de agente y herramientas) y qué hace falta para entregarlo (el curso de despliegue en la nube sobre despliegue en producción, el curso guiado por evals sobre evaluación operativa).

Sin selección de patrones, falta el tejido conectivo. Puedes construir un agente y puedes desplegarlo, pero la decisión de diseño entre ambos, qué tipo de agente para esta tarea, queda sin principio. Este curso llena esa brecha.

Las cinco preguntas parecen simples. ¿Se conoce la ruta? ¿El flujo es estable? ¿La estructura es articulable? ¿La calidad supera la velocidad? ¿Hay un cuello de botella de especialización? Pero codifican las distinciones arquitectónicas que el campo lleva cinco años trabajando. Los catálogos de patrones (ReAct, planificación, reflexión, multiagente) existen; lo que faltaba era la lógica de decisión para elegir entre ellos. El artículo de Bala Priya C llena esa brecha; este curso la extiende con la composición de despliegue y evaluación que necesitan los estudiantes de Agent Factory.

La composición de despliegue es la contribución que diferencia este curso. Pocos cursos sobre patrones agénticos enseñan qué implica cada patrón para el stack de nube:

Los flujos de trabajo secuenciales omiten por completo la capa de sandbox
ReAct con agente único usa el stack completo
Planificación + ReAct añade persistencia de plan y background workers más largos
La reflexión a menudo introduce enrutamiento de modelos multiproveedor
Multiagente exige tracing por especialista, logs de auditoría de enrutamiento y atribución de costo por rol

Estas no son preocupaciones abstractas. Son la diferencia entre un despliegue que cuesta $130/mes para una carga pequeña y uno que cuesta $400/mes para la misma carga porque el patrón fue demasiado elaborado. La selección de patrones es disciplina de costos además de disciplina arquitectónica.

La composición de evaluación es la segunda contribución. Cada patrón tiene modos de fallo característicos que tu suite de evals atrapa de forma distinta:

Flujos secuenciales: corrección a nivel de paso mediante DeepEval
ReAct: trazas de razonamiento mediante Phoenix
Planificación + ReAct: divergencia plan-ejecución como métrica personalizada
Reflexión: comparación pre/post y detección de aprobación mecánica
Multiagente: tres marcadores separados para calidad de especialistas, enrutamiento e integración

Sin evaluación consciente del patrón, la suite de evals es genérica y se pierde los fallos específicos que produce cada patrón. Este curso nombra qué buscar, patrón por patrón, para que tu suite de evals se vuelva consciente del patrón.

La frase de tesis de cierre para la ruta Agent Factory ahora se lee ligeramente distinta. El curso de construcción de agentes abrió con el bucle del agente es el motor de una empresa AI-native. El curso de despliegue en la nube cerró con el bucle del agente, desplegado a escala de producción con la separación arquitectónica correcta, observado en las superficies correctas y calificado continuamente contra una suite viva de evals, es lo que una empresa AI-native realmente ejecuta. Este curso añade el prefijo que faltaba: el bucle de agente correcto para la tarea es lo que una empresa AI-native ejecuta. Elegir la forma equivocada, sobredimensionar o quedarse corto, produce sistemas que se entregan más lento, cuestan más y se rompen en más modos de fallo. La selección de patrones es la primera decisión de diseño; todo lo demás está aguas abajo.

Qué viene después de este curso. El cierre del curso de despliegue en la nube nombró tres fronteras: comercio agente-a-agente, detalles de despliegue de Identic AI, multi-región activo-activo. Siguen siendo cursos futuros. Este curso añade una más: harnesses de prueba específicos por patrón. La suite de evals es genérica; un curso futuro podría construir generadores de pruebas específicos por patrón (un "tester de flujo de trabajo secuencial" que genera entradas que cubren las ramas del flujo; un "tester de enrutamiento multiagente" que genera entradas que sondean la lógica de enrutamiento del coordinador). Esa es una frontera real, y depende de la taxonomía de patrones de este curso como prerrequisito.

Prueba con IA, ejercicio final. Abre tu sesión de Claude Code u OpenCode. Pega:

"Acabo de completar un curso sobre selección de patrones agénticos. Elige una tarea real para la que quizá quiera construir un agente en el próximo trimestre, algo de mi trabajo real, no un ejemplo de juguete. Recorre conmigo el árbol de decisión de cinco preguntas, pidiéndome que responda cada pregunta y cuestionándome si mi razonamiento es débil. Luego dime qué patrón recomendarías, qué topología de despliegue en la nube necesitaría y qué señales de eval debería vigilar. Sé específico sobre las propiedades de la tarea, no genérico."

Lo que estás aprendiendo. El árbol de decisión solo se fija cuando se aplica a tus tareas, no a ejemplos de libro. Este ejercicio fuerza la disciplina dentro de una decisión concreta que realmente tomarás. Guarda la respuesta de la IA; revísala cuando empieces a construir el agente.

Idea central: este curso es el tejido conectivo entre diseño de agentes (bucles y herramientas) y despliegue de agentes (los cursos de despliegue en la nube y evals). El árbol de decisión de cinco preguntas codifica las distinciones arquitectónicas que la literatura ha pasado años elaborando; la capa de composición mapea cada patrón a una disciplina específica de despliegue y evaluación. La tesis de cierre: el bucle de agente correcto para la tarea es lo que una empresa AI-native ejecuta, y la selección de patrones es la primera decisión de diseño, de la que fluye todo lo demás. Para el artefacto accionable que produce este curso, consulta la plantilla de revisión de diseño de una página en la sección final antes de Referencias: imprimible, compartible con el equipo, recorre las mismas cinco preguntas en ~15-20 minutos por propuesta de arquitectura.

Hoja de referencia: los 22 conceptos y 5 decisiones, agrupados por parte

Ambas revisiones de colegas señalaron que la hoja de referencia era densa; la agrupación de abajo asigna cada fila a la parte a la que pertenece, para que puedas navegar por sección en lugar de desplazarte por 22 filas.

Parte 1: El problema de selección de patrones

#	Concepto	Idea clave
1	La selección de patrones es trabajo de diseño antes de construir	Los patrones están bien documentados; la lógica de decisión para elegir entre ellos no. La elección equivocada se encarece de forma compuesta en producción.
2	Cada patrón es una apuesta sobre la tarea	El flujo secuencial apuesta por rutas conocidas; ReAct por rutas desconocidas; planificación por estructura articulable; reflexión por criterios verificables; multiagente por necesidades reales de especialización.
3	Dos modos de fallo: sobredimensionar y quedarse corto	Sobredimensionar (más elaborado de lo necesario) es el modo famoso; quedarse corto (más simple de lo necesario) es igual de común y más sutil.

Parte 2: El árbol de decisión de cinco preguntas

#	Concepto	Idea clave
4	Q1: ¿La ruta de solución se puede definir de antemano?	Las rutas conocidas van a flujos; las rutas desconocidas van a razonamiento agéntico. Prueba con la heurística de "función Python sin llamadas a LLM".
5	Q2: ¿El flujo de trabajo es fijo y estable?	Las rutas estables van a flujo secuencial; las rutas conocidas pero variables van a flujo ramificado o a patrones agénticos.
6	Q3: ¿La estructura de la tarea es articulable?	Articulable → planificación + ejecución ReAct; no articulable → ReAct puro. Distinción forma-frente-a-contenido. El recuadro de desambiguación Q2/Q3 recorre los casos de frontera.
7	Q4: ¿Calidad > velocidad Y criterios verificables?	Ambas condiciones deben cumplirse para que la reflexión aporte valor. Fallos más comunes: aprobación mecánica, criterios vagos, violaciones de presupuesto de latencia.
8	Q5: ¿Especialización, contexto o cuello de botella de escala?	Tres afirmaciones probadas por separado, con disparadores cuantitativos cuando sea posible: >30% de errores de enrutamiento de herramientas (especialización), >10% de caída de exactitud con más contexto (desborde), >2× de exceso sobre presupuesto de latencia (escala).

Conceptos puente: de selección de patrones a implementación

#	Concepto	Idea clave
8.5	Primitivas del SDK: qué usa cada patrón	`Agent` es la unidad atómica. `Runner.run()` ejecuta el bucle. `@function_tool` expone herramientas. `handoff()` para toma de control por especialista; `as_tool()` para coordinador al mando. `output_guardrail` para reflexión. La selección de patrones es una elección sobre qué primitivas componer.
8.6	Capa operativa por patrón (Inngest como ejemplo concreto)	Los triggers despiertan la función (`TriggerEvent`, `TriggerCron`); `step.run` la vuelve durable; `step.wait_for_event` implementa puertas HITL; concurrencia/throttle/prioridad dan forma a la carga; fan-out coordina especialistas multiagente; replay maneja recuperación tras arreglos de bugs. Cuanto más elaborado el patrón, más crítica la capa.

Parte 3: Los cinco patrones en profundidad

#	Concepto	Idea clave
9	Flujo de trabajo secuencial, patrón, despliegue, evals, capa	Usa el subconjunto más pequeño del stack de nube (sin sandbox). Evals a nivel de paso, no evals de razonamiento de agente. El mapeo más directo a funciones de Inngest.
10	Agente único + ReAct, patrón, despliegue, evals, capa	Stack completo de nube, incluido bridge Worker. Las evals de trazas Phoenix son fundamentales. Un `step.run` para todo el bucle del agente.
11	Planificación + ejecución ReAct, patrón, despliegue, evals, capa	Añade persistencia de plan; background workers más largos. La divergencia plan-ejecución es la señal de eval clave. Un `step.run` por etapa.
12	Agente único + reflexión (capa adicional), patrón, despliegue, evals, capa	Se añade encima de cualquier patrón central. A menudo introduce enrutamiento de modelos multiproveedor. La aprobación mecánica es el fallo más insidioso. SDK `output_guardrail` o generador/crítico separado.
13	Sistema especialista multiagente, patrón, despliegue, evals, capa	Stack completo más tracing por especialista. Se requieren tres marcadores separados. Usa todas las primitivas de Inngest (fan-out, concurrencia por tenant, prioridad, HITL). La sobrecarga de coordinación es real.

Parte 4: Señales de fallo y revisión

#	Concepto	Idea clave
14	Las cinco señales de fallo	Bucles ReAct (falta estructura), divergencia plan-ejecución (sobreestructurado), reflexión sin mejora (criterios vagos), fallo de enrutamiento multiagente (sobreparticionado), complejo-pero-no-mejor (sobredimensionamiento acumulado).
15	Arreglos primero en el alcance más pequeño	Arreglos a nivel de prompt (condiciones de parada, especificación de criterios) antes de nivel de contrato (descripciones de herramientas, estructuras de handoff) antes de cambios arquitectónicos.
16	Cuándo se equivoca el árbol de decisión	Las propiedades de la tarea cambian post-despliegue, subtareas distintas necesitan patrones distintos, restricciones excluyen la respuesta del árbol. Recorre el árbol otra vez.
16.5	La galería de antipatrones, elecciones equivocadas comunes	Cinco antipatrones de sobredimensionamiento + tres de quedarse corto. Multiagente para contenido (→ agente único); ReAct para factura (→ flujo); planificador para depuración (→ ReAct); reflexión sobre criterios vagos (→ quitar); un agente gigante (→ multiagente); saltarse reflexión en salida verificable (→ añadir).

Parte 5: El laboratorio de decisión (cinco decisiones, tabla separada abajo)

Parte 6: Fronteras honestas

#	Concepto	Idea clave
17	Costo y latencia como restricciones arquitectónicas	Multiagente + reflexión puede costar 30-60× un flujo secuencial (relación ilustrativa). Documenta explícitamente elecciones de patrón impulsadas por restricciones.
18	Composición de patrones en distintas capas	Jerárquica, secuencial, condicional. La elección de patrón de cada capa se justifica con las mismas cinco preguntas en ese alcance.

Parte 7: Cierre

#	Concepto	Idea clave
19	La selección de patrones como tejido conectivo	El puente entre diseño de agentes (bucles y herramientas) y despliegue (el curso de despliegue en la nube). El bucle de agente correcto para la tarea es lo que ejecuta una empresa AI-native.

Las cinco decisiones (Parte 5)

#	Decisión	Patrón central + capas adicionales
1	Agente de soporte de nivel 1 de Maya	Núcleo: agente único + ReAct + herramientas (Concepto 10). Sin capas adicionales.
2	Agente de respuesta a incidentes	Núcleo: planificación + ejecución ReAct (Concepto 11). + capa de reflexión sobre pasos de remediación (Concepto 12).
3	Agente de investigación de mercado	Núcleo: sistema especialista multiagente (Concepto 13), con planificación + ReAct dentro de especialistas. + capa de reflexión sobre síntesis.
4	Agente de onboarding empresarial	Núcleo: flujo de trabajo secuencial (Concepto 9). Sin capas adicionales. El ejemplo negativo de patrones agénticos.
5	Agente de coding	Núcleo: sistema especialista multiagente (Concepto 13), con planificación + ReAct dentro de especialistas. + capa de reflexión sobre salida del programador. El caso avanzado: cada decisión arquitectónica compuesta.

Referencia rápida: las cinco preguntas, los cinco patrones

Q1: Can the solution path be defined in advance?
    Yes  → Q2
    No   → Q3 (need agentic reasoning)

Q2: Is the workflow fixed and stable across runs?
    Yes  → SEQUENTIAL WORKFLOW
    No   → Q3 (or branched workflow if few stable variants)

Q3: Is the task structure articulable before execution?
    Yes  → PLANNING + REACT EXECUTION
    No   → SINGLE AGENT + REACT + TOOLS

Q4: Quality > speed AND criteria are checkable?
    Yes  → Add REFLECTION on top of the chosen pattern
    No   → Skip reflection

Q5: Specialization, context, or scale bottleneck?
    Yes  → MULTI-AGENT SPECIALIST SYSTEM
    No   → Keep single-agent pattern

Plantilla de revisión de diseño (una página, imprimible)

*Una hoja de trabajo compartible con el equipo para aplicar el marco de este curso en revisiones de diseño. Imprime una por propuesta de arquitectura. La plantilla recorre las mismas cinco preguntas y hace visibles las mismas decisiones de composición; el valor no está en llenarla a solas, sino en tener las preguntas visibles durante una discusión.*

═══════════════════════════════════════════════════════════════════════
  COURSE ELEVEN: Agentic Architecture Design Review
═══════════════════════════════════════════════════════════════════════

Task name: _______________________________________________________

Task description (1-3 sentences):
  ________________________________________________________________
  ________________________________________________________________
  ________________________________________________________________

Reviewer(s): __________________________  Date: ____________________

───────────────────────────────────────────────────────────────────────
  CORE PATTERN (Q1-Q3)
───────────────────────────────────────────────────────────────────────

Q1. Can the solution path be defined in advance?
    [ ] YES, known        → go to Q2
    [ ] NO, adaptive      → skip to Q3
  Evidence:
    ______________________________________________________________

Q2. Is the workflow fixed and stable across runs?
    [ ] YES, stable        → CORE = Sequential Workflow → skip to Q4
    [ ] NO, variable        → continue to Q3
  Evidence:
    ______________________________________________________________

Q3. Is the task's high-level structure articulable before execution?
    [ ] YES, articulable   → CORE = Planning + ReAct execution
    [ ] NO, emergent       → CORE = Single Agent + ReAct + tools
  Evidence:
    ______________________________________________________________

  → CORE PATTERN CHOSEN: ________________________________________

───────────────────────────────────────────────────────────────────────
  ADDITIVE LAYERS (Q4-Q5)
───────────────────────────────────────────────────────────────────────

Q4. Quality > speed AND criteria are checkable?
    [ ] YES: both          → ADD Reflection layer
    [ ] NO: vague criteria → DO NOT add reflection
    [ ] NO: latency budget → DO NOT add reflection (consider human review)
  Checkable criteria (if YES):
    ______________________________________________________________
    ______________________________________________________________

Q5. Specialization, context, or scale bottleneck?
    [ ] YES: specialization (name it): _______________________________
    [ ] YES: context overflow (describe): ____________________________
    [ ] YES: parallelizable scale (quantify): ________________________
    [ ] NO: keep single agent

  → If Q5 is YES → upgrade CORE to: Multi-Agent Specialist System
    Specialist roles: ____________________________________________

───────────────────────────────────────────────────────────────────────
  FINAL ARCHITECTURE
───────────────────────────────────────────────────────────────────────

Core pattern:         ________________________________________________
+ Reflection (Y/N):   ________________________________________________
+ Multi-agent (Y/N):  ________________________________________________

───────────────────────────────────────────────────────────────────────
  IMPLEMENTATION & DEPLOYMENT
───────────────────────────────────────────────────────────────────────

SDK primitives used (Concept 8.5):
  [ ] Agent (with output_type if structured)
  [ ] Runner.run(agent, input, max_turns=__)
  [ ] @function_tool decorators on N tools (N = __)
  [ ] handoff() between agents
  [ ] Agent.as_tool() for coordinator composition
  [ ] output_guardrail (if reflection layer)

Operational envelope primitives (Concept 8.6, if applicable):
  [ ] Trigger: ___________________________________________________
  [ ] step.run per: _____________________________________________
  [ ] step.wait_for_event for: __________________________________
  [ ] Concurrency cap: ______ per ______________________________
  [ ] Fan-out for: ______________________________________________
  [ ] Priority/fairness rule: ___________________________________

Cloud deployment subset needed (Concept 9-13 sidebars):
  [ ] FastAPI on ACA (always)
  [ ] Neon Postgres
  [ ] R2 (if files in/out)
  [ ] Sandbox + Bridge Worker (if agent runs code)
  [ ] Phoenix (if agentic: any pattern except pure sequential workflow)

───────────────────────────────────────────────────────────────────────
  RISK ANALYSIS
───────────────────────────────────────────────────────────────────────

Cost class (Concept 17):
  [ ] 1× baseline (Sequential workflow)
  [ ] 3-10× (Single agent + ReAct)
  [ ] 5-15× (Planning + ReAct)
  [ ] +2-3× core (with Reflection)
  [ ] 5-20× (Multi-agent)

Latency budget check:
  Expected latency: ___________________________________________
  User-facing budget: _________________________________________
  [ ] Fits           [ ] Tight           [ ] Will not fit

Most likely failure signal to watch (Concept 14):
  [ ] ReAct loops / revisits solved work
  [ ] Plan-execution divergence
  [ ] Reflection not improving output
  [ ] Multi-agent routing failures
  [ ] System feels complex but not better
  Mitigation if it appears:
    ______________________________________________________________

Eval signals to wire (Concept 9-13 sidebars):
  ______________________________________________________________
  ______________________________________________________________

───────────────────────────────────────────────────────────────────────
  ANTI-PATTERN CHECK (Concept 16.5)
───────────────────────────────────────────────────────────────────────

If a senior engineer reviewed this choice, what would they object to?
  ______________________________________________________________
  ______________________________________________________________

Counter-argument (why our choice is right despite the objection):
  ______________________________________________________________
  ______________________________________________________________

───────────────────────────────────────────────────────────────────────
  SIGN-OFF
───────────────────────────────────────────────────────────────────────

Architecture approved for: [ ] Prototype  [ ] Pilot  [ ] Production
Approved by:    ______________________________________________________
Re-review date: ______________________________________________________

═══════════════════════════════════════════════════════════════════════

La plantilla está diseñada para recorrerse en 15-20 minutos por propuesta de arquitectura. Llenarla es la disciplina; el valor está en tener las preguntas visibles durante una conversación de equipo. Imprime una por decisión arquitectónica importante; guarda las versiones completadas en el archivo de decisiones de diseño de tu equipo.

Referencias

Bala Priya C, "Choosing the Right Agentic Design Pattern: A Decision-Tree Approach", Machine Learning Mastery, 15 de mayo de 2026, machinelearningmastery.com/choosing-the-right-agentic-design-pattern-a-decision-tree-approach. El árbol de decisión que sostiene este curso es suyo.
Yao et al., "ReAct: Synergizing Reasoning and Acting in Language Models" (2022), el paper original de ReAct.
Wang et al., "Voyager: An Open-Ended Embodied Agent with Large Language Models" (2023), ejemplo temprano de composición de planificación + ejecución.
Shinn et al., "Reflexion: Language Agents with Verbal Reinforcement Learning" (2023), formalización del patrón de reflexión.
OpenAI, "The next evolution of the Agents SDK" (abril de 2026), la actualización del SDK (harness nativo del modelo más ejecución nativa en sandbox) que vuelve entregables los patrones.
El curso de construcción de agentes (Panaversity Agent Factory): bucles de agente y el motor de una empresa AI-native.
El curso guiado por evals (Panaversity Agent Factory): desarrollo guiado por evals y la disciplina de traza a eval.
El curso de despliegue en la nube (Panaversity Agent Factory): despliegue del harness de OpenAI Agents SDK en la nube.

El curso acelerado de selección de patrones para la ruta Agent Factory: cinco preguntas, cinco patrones, señales de fallo y composición con tu despliegue, tu suite de evals y la capa operativa (Inngest). Artículo ancla: Bala Priya C, Machine Learning Mastery, 15 de mayo de 2026. Cierra la brecha de selección de patrones entre diseño de agentes (bucles de agente y herramientas) y la disciplina de producción de los cursos de despliegue y evals, compuesto con la capa operativa en todo momento, portable a cualquier stack agéntico mediante la tabla de traducción.

La versión en lenguaje claro (lee esto primero)​

📖 Si no has tomado los cursos anteriores de la ruta Agent Factory​

Tabla de traducción de plataformas: a qué corresponde cada elección de Agent Factory​

Glosario (lee una vez y vuelve cuando lo necesites)​

¿Estás listo? (requisitos previos)​

Bordes ásperos que conviene conocer desde el inicio (el alcance honesto)​

Cuatro rutas de aprendizaje​

Qué tendrás al final (resultados concretos)​

TL;DR: las cuatro afirmaciones que defiende este curso​

La forma de lo que estás aprendiendo (un diagrama, vuelve a él durante todo el curso)​

Parte 1: El problema de selección de patrones​

Concepto 1: La selección de patrones es el trabajo de diseño que viene antes de construir​

Concepto 2: Cada patrón supone algo distinto sobre la tarea​

Concepto 3: Dos modos de fallo: sobredimensionar y quedarse corto​

Parte 2: El árbol de decisión de cinco preguntas​

Concepto 4: Q1: ¿La ruta de solución se puede definir de antemano?​

Concepto 5: Q2: ¿El flujo de trabajo es fijo y estable entre runs?​

Concepto 6: Q3: ¿La estructura de la tarea es articulable antes de ejecutar?​

🔍 La confusión Q2 frente a Q3, desambiguación con ejemplos​

Concepto 7: Q4: ¿La calidad importa más que la velocidad, con criterios verificables?​

Concepto 8: Q5: ¿Hay un cuello de botella de especialización, contexto o escala?​

Concepto 8.5: Las primitivas de OpenAI Agents SDK, qué usa cada patrón​

Concepto 8.6: Consideraciones de capa operativa por patrón (con Inngest como ejemplo concreto)​

Parte 3: Los cinco patrones en profundidad​

Concepto 9: Flujo de trabajo secuencial, forma característica, despliegue y señales de eval​

Concepto 10: Agente único + ReAct + herramientas, forma característica, despliegue y señales de eval​

Concepto 11: Planificación + ejecución ReAct, forma característica, despliegue y señales de eval​

Concepto 12: Agente único + reflexión, forma característica, despliegue y señales de eval​

Concepto 13: Sistema especialista multiagente, forma característica, despliegue y señales de eval​

Parte 4: Señales de fallo y revisión de patrones​

Concepto 14: Las cinco señales de fallo (y qué significa cada una)​

Concepto 15: Arreglos dirigidos que no requieren abandonar la arquitectura​

Concepto 16: Cuándo se equivoca el árbol de decisión​

Concepto 16.5: La galería de antipatrones, elecciones equivocadas comunes y qué hacer en su lugar​

Parte 5: El laboratorio de decisión​

Decisión 1: Agente de soporte de nivel 1 de Maya​

Decisión 2: Agente de respuesta a incidentes​

Decisión 3: Agente de investigación de mercado​

Decisión 4: Agente de onboarding empresarial​

Decisión 5: Agente de coding (ruta avanzada)​

Parte 6: Fronteras honestas​

Concepto 17: Costo y latencia como restricciones arquitectónicas, no ocurrencias tardías​

Concepto 18: Composición de patrones, varios patrones en distintas capas​

Parte 7: Cierre​

Concepto 19: La selección de patrones como tejido conectivo en el currículo de Agent Factory​

Hoja de referencia: los 22 conceptos y 5 decisiones, agrupados por parte​

Referencia rápida: las cinco preguntas, los cinco patrones​

Plantilla de revisión de diseño (una página, imprimible)​

Referencias​

Ayuda de estudio con flashcards​

La versión en lenguaje claro (lee esto primero)

📖 Si no has tomado los cursos anteriores de la ruta Agent Factory

Tabla de traducción de plataformas: a qué corresponde cada elección de Agent Factory

Glosario (lee una vez y vuelve cuando lo necesites)

¿Estás listo? (requisitos previos)

Bordes ásperos que conviene conocer desde el inicio (el alcance honesto)

Cuatro rutas de aprendizaje

Qué tendrás al final (resultados concretos)

TL;DR: las cuatro afirmaciones que defiende este curso

La forma de lo que estás aprendiendo (un diagrama, vuelve a él durante todo el curso)

Parte 1: El problema de selección de patrones

Concepto 1: La selección de patrones es el trabajo de diseño que viene antes de construir

Concepto 2: Cada patrón supone algo distinto sobre la tarea

Concepto 3: Dos modos de fallo: sobredimensionar y quedarse corto

Parte 2: El árbol de decisión de cinco preguntas

Concepto 4: Q1: ¿La ruta de solución se puede definir de antemano?

Concepto 5: Q2: ¿El flujo de trabajo es fijo y estable entre runs?

Concepto 6: Q3: ¿La estructura de la tarea es articulable antes de ejecutar?

🔍 La confusión Q2 frente a Q3, desambiguación con ejemplos

Concepto 7: Q4: ¿La calidad importa más que la velocidad, con criterios verificables?

Concepto 8: Q5: ¿Hay un cuello de botella de especialización, contexto o escala?

Concepto 8.5: Las primitivas de OpenAI Agents SDK, qué usa cada patrón

Concepto 8.6: Consideraciones de capa operativa por patrón (con Inngest como ejemplo concreto)

Parte 3: Los cinco patrones en profundidad

Concepto 9: Flujo de trabajo secuencial, forma característica, despliegue y señales de eval

Concepto 10: Agente único + ReAct + herramientas, forma característica, despliegue y señales de eval

Concepto 11: Planificación + ejecución ReAct, forma característica, despliegue y señales de eval

Concepto 12: Agente único + reflexión, forma característica, despliegue y señales de eval

Concepto 13: Sistema especialista multiagente, forma característica, despliegue y señales de eval

Parte 4: Señales de fallo y revisión de patrones

Concepto 14: Las cinco señales de fallo (y qué significa cada una)

Concepto 15: Arreglos dirigidos que no requieren abandonar la arquitectura

Concepto 16: Cuándo se equivoca el árbol de decisión

Concepto 16.5: La galería de antipatrones, elecciones equivocadas comunes y qué hacer en su lugar

Parte 5: El laboratorio de decisión

Decisión 1: Agente de soporte de nivel 1 de Maya

Decisión 2: Agente de respuesta a incidentes

Decisión 3: Agente de investigación de mercado

Decisión 4: Agente de onboarding empresarial

Decisión 5: Agente de coding (ruta avanzada)

Parte 6: Fronteras honestas

Concepto 17: Costo y latencia como restricciones arquitectónicas, no ocurrencias tardías

Concepto 18: Composición de patrones, varios patrones en distintas capas

Parte 7: Cierre

Concepto 19: La selección de patrones como tejido conectivo en el currículo de Agent Factory

Hoja de referencia: los 22 conceptos y 5 decisiones, agrupados por parte

Referencia rápida: las cinco preguntas, los cinco patrones

Plantilla de revisión de diseño (una página, imprimible)

Referencias

Ayuda de estudio con flashcards