Orquestación Agéntica y Mejores Prácticas Multiagente
Una lista de verificación para diseñar arquitecturas multiagente fiables y con costes limitados: cuándo recurrir a múltiples agentes, cómo diseñar la división orquestador/trabajador, cómo delegar trabajo en paralelo, cómo elegir entre encadenamiento y enrutamiento, y las salvaguardias, recuperación de errores, evaluación y disciplina de ADR que mantienen un sistema multiagente seguro para ejecutarse en producción.
Cómo Usar Esta Lista
- Trabaja a través de los grupos en orden la primera vez que diseñes un flujo de trabajo multiagente; los grupos posteriores (salvaguardias, evaluación, ADR) asumen que ya has tomado las decisiones en los anteriores.
- Trata el Grupo A como una puerta de entrada, no como una formalidad. Si una tarea no supera la prueba de descomposición, detente ahí y construye un solo agente en su lugar.
- Utiliza esto como una lista de verificación de revisión de diseño para cualquier orquestador nuevo, no solo como una referencia única; revísala cada vez que la mezcla de tareas, el perfil de costes o la tasa de fallos de un flujo de trabajo cambien.
- Cada elemento enlaza de nuevo a la página de esta sección que explica el razonamiento y muestra código funcional.
A - Cuándo Recurrir a Multiagente
- Comienza cada tarea como un solo agente y demuestra que es insuficiente antes de dividirla. Un solo bucle de llamada a herramientas es suficiente para la mayoría de las tareas; multiagente es la excepción que tiene que ganarse su complejidad añadida, no la arquitectura por defecto.
- Recurre a multiagente cuando una tarea se descompone en subtareas independientes y paralelizable. Si puedes describir las subtareas como puntos de viñeta paralelos sin flechas entre ellos, dividir entre agentes vale la pena considerarlo; si los pasos dependen del estado intermedio de otros, mantenlos en un solo bucle.
- Recurre a multiagente cuando las subtareas necesiten acceso a herramientas o contexto especializados, no para añadir ceremonia. Una subtarea que solo debería leer archivos, o que necesita un contexto más reducido que el resto de la tarea, es un candidato legítimo para su propio agente incluso sin paralelismo, ya que el ámbito de las herramientas en el SDK de Agente de Claude se establece por agente.
B - Diseño de Orquestador/Trabajador
- Dale al orquestador un solo trabajo: distribuir y fusionar, no el trabajo subyacente en sí. Un orquestador configurado con una lista de herramientas vacía y solo con
subagentsconfigurado mantiene su rol inequívoco y evita que haga silenciosamente el trabajo de un trabajador. - Escribe la descripción de cada trabajador tan específicamente como la descripción de una herramienta. Una
SubagentConfig.descriptionvaga no da al modelo del orquestador ninguna señal fiable de cuándo se aplica ese trabajador, y omitirá o invocará para la subtarea incorrecta. - Especifica la forma exacta de la salida fusionada en el prompt del orquestador. Dejada vaga, un orquestador por defecto pegará el resultado bruto de cada trabajador uno tras otro en lugar de sintetizarlos; nombra las secciones de destino, el orden y los límites de longitud de la misma manera que especificarías el tipo de retorno de una función.
- Escala las herramientas de cada trabajador de forma independiente de las del orquestador y de las de cualquier otro trabajador. Un trabajador no hereda nada automáticamente del padre; otórgale solo lo que su trabajo específico requiere, no la unión de todo lo que el orquestador puede hacer.
C - Delegación Paralela
- Inicia un subagente por cada subtarea independiente, no un subagente haciendo varias. El aislamiento por subtarea mantiene los callejones sin salida y las llamadas exploratorias a herramientas de cada trabajador fuera del contexto de los otros trabajadores, y fuera del orquestador.
- Distribuye los trabajadores independientes concurrentemente, no secuencialmente. La distribución secuencial de subtareas que no dependen unas de otras desperdicia el paralelismo que fue la razón para delegar en primer lugar.
- Secuencia los trabajadores dependientes explícitamente cuando uno necesita la salida del otro. Forzar la distribución paralela de un par donde el segundo trabajador realmente necesita el resultado del primero produce un trabajador que está adivinando la entrada que aún no tiene.
- Haz que cada trabajador informe de un resultado final al agente coordinador, no de un flujo de estado parcial. El orquestador debería poder razonar sobre lo que encontró un trabajador sin reconstruirlo a partir de llamadas a herramientas intermedias que nunca vio.
D - Encadenamiento vs. Enrutamiento
- Usa el encadenamiento de prompts para una secuencia fija y predecible de pasos. El encadenamiento se adapta a flujos de trabajo donde el siguiente paso es siempre el mismo independientemente de la entrada, y es más simple de razonar y depurar que una alternativa dinámica.
- Usa el enrutamiento cuando el tipo de tarea varía y el camino a seguir es una decisión dinámica. El enrutamiento se adapta a tipos de tareas variables donde diferentes entradas realmente necesitan un manejo diferente, no a un flujo de trabajo que siempre son los mismos tres pasos disfrazados.
- No construyas un enrutador para un flujo de trabajo que en realidad nunca se ramifica. Una decisión de enrutamiento innecesaria añade una llamada al modelo y un modo de fallo para una elección que siempre se resolvería de la misma manera.
- No fuerces una entrada genuinamente variable a través de una cadena fija. Forzar todo a través de la misma secuencia produce pasos desperdiciados para entradas que no los necesitaban, o una cadena que maneja silenciosamente los casos para los que no fue construida.
E - Salvaguardias: Profundidad, Herramientas y Gasto
- Limita la profundidad de los subagentes. Los trabajadores que a su vez delegan en sub-trabajadores multiplican la sobrecarga de coordinación y hacen que los fallos sean mucho más difíciles de rastrear hasta una causa raíz; la mayoría de los sistemas de producción limitan la delegación a uno o dos niveles.
- Escala el acceso a herramientas al mínimo privilegio, por agente. Cada herramienta habilitada es un área de superficie adicional sobre la que un agente, orquestador o trabajador descontrolado puede actuar sin supervisión; las decisiones de escala no se transfieren automáticamente entre agentes.
- Establece un presupuesto explícito de tokens o costes por tarea, no solo por ejecución. Un paso de síntesis que lee el resultado completo de cada trabajador en el contexto puede gastar mucho más de lo que gastó cualquier trabajador individual; limita el gasto total entre la distribución y la fusión, no solo a nivel de agente individual.
- Trata la profundidad, las herramientas y el gasto como un sistema de salvaguardias, no como tres controles separados. Un agente superficial pero con muchas herramientas puede gastar tanto y causar tanto daño como uno profundo y con un alcance limitado; revisa los tres juntos cuando diseñes o audites un flujo de trabajo.
F - Recuperación de Errores
- Reintenta una llamada a herramienta fallida antes de escalarla como un fallo de tarea. Los fallos transitorios como límites de tasa o una llamada de red inestable no deberían hacer fallar toda la ejecución; un reintento limitado absorbe el caso común.
- Define un fallback para un subagente que se bloquea o agota su presupuesto de reintentos. Una herramienta más simple, un trabajador diferente o una transferencia a un humano son caminos de fallback legítimos; dejar que el orquestador espere indefinidamente no lo es.
- Aplica un patrón de disyuntor para que una dependencia fallida no se propague por todo el sistema. Una vez que un trabajador o herramienta ha fallado suficientes veces en una ventana, deja de llamarlo y muestra el fallo en lugar de reintentar indefinidamente y quemar presupuesto en algo que no se va a recuperar por sí solo.
- Registra cada fallo y la decisión de recuperación que le siguió. Sin un registro de lo que falló y lo que se activó después, no puedes distinguir una dependencia genuinamente inestable de un error sistémico en tu lógica de orquestación.
G - Evaluación Antes de Producción
- Puntúa la tasa de éxito de la tarea en un conjunto de tareas representativo antes de enviarlo. Un proceso de evaluación repetible, no comprobaciones puntuales anecdóticas durante el desarrollo, es lo que te dice si la arquitectura realmente funciona en el rango de entradas que verá en producción.
- Rastrea el coste por tarea junto con la tasa de éxito, no solo la tasa de éxito. Un diseño multiagente que tiene éxito con más frecuencia pero cuesta varias veces más por ejecución y por tarea puede no ser el compromiso adecuado para el flujo de trabajo; evalúa ambos juntos.
- Cataloga los modos de fallo, no solo un recuento de aprobados o fallidos. Comprender cómo falla un flujo de trabajo, un trabajador bloqueado, una fusión incorrecta, un caso límite omitido, es lo que te dice en qué salvaguardia o fallback invertir a continuación.
- Vuelve a ejecutar la evaluación cada vez que cambie un prompt, un modelo o el ámbito de herramientas de un subagente. Una evaluación anterior a un cambio significativo no te dice nada fiable sobre el sistema tal como está hoy.
H - Disciplina ADR
- Escribe un ADR antes de comprometerte con un orquestador multiagente para un flujo de trabajo. Documentar la contrapartida entre un solo agente y un orquestador multiagente fuerza una decisión deliberada en el momento en que se toma, en lugar de una arquitectura que se acumuló un subagente a la vez.
- Registra qué necesidad de descomposición o especialización justificó la división. Si no puedes exponer la razón específica claramente en el ADR, la prueba de descomposición en el Grupo A probablemente no se cumplió realmente.
- Revisa el ADR cuando la mezcla de tareas o el perfil de costes del flujo de trabajo cambien materialmente. Una decisión de arquitectura que fue correcta en el lanzamiento puede volverse incorrecta a medida que el volumen de tareas, el coste o los requisitos cambian, y el ADR es el registro que le dice a la siguiente persona por qué se tomó en primer lugar.
Preguntas Frecuentes
¿Cuándo sigue siendo la llamada correcta un solo agente, incluso si una tarea parece compleja?
Cuando los pasos son secuenciales y dependen del estado intermedio de otros, sin importar cuántos pasos haya. La complejidad en el razonamiento no requiere múltiples ventanas de contexto; solo la independencia genuina entre subtareas lo hace.
¿Cuál es la forma más rápida de saber si una tarea se descompone lo suficiente para multiagente?
Intenta describir las subtareas como puntos de viñeta paralelos sin flechas entre ellos. Si no puedes hacerlo sin añadir una flecha (la subtarea B necesita el resultado de la subtarea A), no es lo suficientemente independiente como para dividirla limpiamente.
¿Debería el orquestador tener herramientas propias?
Solo si necesita hacer algo más allá de distribuir y fusionar, como escribir el resultado final en un archivo. Cuando su trabajo es puramente de síntesis, una lista de herramientas vacía mantiene su rol inequívoco y evita que haga el trabajo de un trabajador por sí mismo.
¿Cuál es la diferencia entre encadenamiento y enrutamiento en la práctica?
El encadenamiento es una secuencia fija: el paso dos siempre sigue al paso uno de la misma manera. El enrutamiento es una decisión dinámica: el flujo de trabajo elige qué camino tomar basándose en la entrada. Usa el encadenamiento para flujos de trabajo predecibles y el enrutamiento para tipos de tareas variables.
¿Hasta qué profundidad debe llegar la delegación de subagentes?
Limítala a uno o dos niveles para casi todos los sistemas de producción. Una delegación más profunda, trabajadores que a su vez generan sub-trabajadores, multiplica la sobrecarga de coordinación y hace que los fallos sean mucho más difíciles de rastrear hasta una causa raíz.
¿Cuál es la forma más común en que los sistemas multiagente pierden el control del coste?
Un prompt abierto que permite al orquestador distribuir tantos trabajadores como decida que necesita, combinado con un paso de fusión que lee el resultado completo de cada trabajador en el contexto. Limita el recuento de subagentes y el gasto de tokens explícitamente en lugar de dejar la distribución abierta.
¿Qué debería desencadenar un reintento frente a un fallback frente a un disyuntor?
Reintenta un solo fallo transitorio, como un límite de tasa. Haz fallback una vez que se agote el presupuesto de reintentos o un subagente se bloquee por completo. Activa un disyuntor una vez que una dependencia haya fallado repetidamente en una ventana, para que el sistema deje de llamar a algo que claramente no se va a recuperar.
¿Qué significa realmente "evaluar antes de producción" en la práctica?
Ejecutar el flujo de trabajo contra un conjunto de tareas representativo y puntuar la tasa de éxito de la tarea, el coste y los modos de fallo como un proceso repetible, no solo comprobar que funcionó en los ejemplos que probaste manualmente durante el desarrollo.
¿Cada flujo de trabajo multiagente necesita un ADR?
Cualquier flujo de trabajo en el que elijas un orquestador multiagente en lugar de un solo agente debería tener uno. El ADR es lo que documenta la contrapartida y la necesidad específica de descomposición o especialización que justificó la complejidad añadida.
¿Cuál es el mayor error que cometen los equipos cuando adoptan multiagente por primera vez?
Recurrir a él por defecto en lugar de demostrar que un solo agente es insuficiente primero. La mayoría de las tareas siguen siendo de un solo agente; multiagente se gana su complejidad solo cuando una tarea se descompone genuinamente o necesita acceso a herramientas especializadas.
¿Puede un solo subagente romper las salvaguardias por sí solo?
Sí, si su propio ámbito de herramientas o gasto no está limitado de forma independiente. Las salvaguardias se aplican por agente, no solo en el nivel superior; un orquestador con un límite estricto y un trabajador ilimitado todavía tiene un sistema ilimitado en general.
¿Cómo se relacionan la delegación paralela y el diseño de orquestador/trabajador?
Orquestador/trabajador es la división de roles, un agente distribuye y fusiona, otros hacen el trabajo subyacente. La delegación paralela es una propiedad de cómo ocurre esa distribución: trabajadores independientes ejecutándose concurrentemente en lugar de uno tras otro. Puedes tener uno sin el otro, pero generalmente se combinan en la práctica.
Relacionado
- Bucles de Agente Único vs. Sistemas Multiagente: Un Modelo Mental - la prueba de descomposición detrás del Grupo A
- Patrones de Orquestador/Trabajador con el SDK de Agente de Claude - el diseño de distribución y fusión en profundidad
- Salvaguardias para Sistemas Multiagente: Limitando Costes y Ámbito - profundidad, acceso a herramientas y límites de gasto en profundidad
- Evaluación de la Calidad del Agente: Una Lista de Verificación para la Preparación de Producción - el proceso de evaluación detrás del Grupo G
- Plantilla ADR: Agente Único vs. Orquestador para un Nuevo Flujo de Trabajo - una plantilla para la disciplina ADR en el Grupo H
- Mejores Prácticas del SDK de Agente de Claude - las prácticas a nivel de SDK subyacentes en las que se basa esta sección
Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el SDK de Agente de Claude (última versión). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.