Puntos clave
- Controla la UX compartida del shell con feature flags del producto, no con ramas por id de agente.
- Lleva el alcance, los iniciadores, los prefijos de exportación y las listas de acceso como datos de overlay por agente.
- Deja que la SPA pinte un payload de catálogo autorizado; no analices JWT para decidir la visibilidad.
- Publica los agentes especializados como packs y configuración para que el core siga libre de código fijo por equipo.
- Amplía la CI con una matriz de flags y roles, no con copias bifurcadas del shell.
- Valida antes del merge las declaraciones de acceso de los overlays frente a las reglas de autorización de la API.
Los shells multiagente se pudren cuando cada asistente nuevo se convierte en un if-else sobre ids de agente. Los microtextos se bifurcan. Los prefijos de exportación se bifurcan. Las comprobaciones de acceso se bifurcan. Pronto la SPA es un catálogo hecho a medida que finge ser un producto.
Abierto por defecto, con overlays. Los feature flags del producto controlan la UX compartida. Las filas de overlay por agente llevan las diferencias. La SPA nunca se inventa la política a partir de un JWT. El core se mantiene limpio porque los agentes especializados son datos, no bifurcaciones del código.
Modelo con nombre: abierto por defecto, con overlays
- Feature flags del producto: las superficies compartidas (diseño del chat, citas, exportación, chips de seguimiento) están abiertas por defecto y se pueden cambiar sin borrar un agente.
- Overlays por agente: las etiquetas de alcance, los prompts iniciales, los prefijos de exportación y las listas de acceso viven como datos de fila bajo esos flags.
- API de catálogo / autorización: la API devuelve lo que este llamador puede ver; la SPA solo pinta esa lista.
- Regla: el comportamiento compartido es una funcionalidad del producto. Las diferencias entre agentes son datos de overlay. La política se queda en la API.
Figura 1. Abierto por defecto, con overlays. Los flags controlan la UX compartida. Las filas de overlay llevan las diferencias entre agentes. La API de catálogo decide qué puede mostrar la SPA.
Contexto y restricción
Los catálogos de agentes suelen crecer más rápido de lo que la UX compartida puede absorber. Cada caso especial "rápido" para un asistente le enseñó al siguiente ingeniero que escribir cosas fijas en el código era lo normal. Los feature flags más las filas de overlay recuperaron un único shell con muchos agentes.
Si los iniciadores, los nombres de exportación y las listas de acceso viven en el código junto a los ids de agente, cada equipo quiere una bifurcación. Si viven en filas de overlay controladas por flags, el core sigue siendo aburrido y el catálogo sigue siendo honesto. La autorización sigue perteneciendo a la API; los overlays describen lo que la API ya permite mostrar al shell.
La figura 2 es la superficie de Learn para gestionar feature flags. Trátala como la postura del producto para las superficies compartidas, no como un sitio donde codificar en React las preferencias de cada equipo.
Figura 2. La UX compartida del shell es una funcionalidad del producto. Las diferencias entre agentes van en filas de overlay que la API ya autoriza. Fuente: Microsoft Learn: gestionar feature flags.
La figura 3 es el interruptor para crear un flag. Los flags controlan superficies. Los roles de la aplicación siguen decidiendo qué puede mostrar el catálogo.
Figura 3. Los feature flags controlan superficies. Los roles de la aplicación siguen decidiendo qué puede mostrar el catálogo. La SPA no debería inventarse la política a partir de JWT. Fuente: Microsoft Learn: gestionar feature flags.
Diseño
1. UX compartida abierta por defecto detrás de flags
El diseño del chat, los paneles de citas, las opciones de exportación y los chips de seguimiento son funcionalidades del producto. Contrólalos con flags para poder desactivar una superficie sin borrar un agente. Los flags sirven para la postura del producto, no para codificar en React las preferencias de cada equipo.
2. Filas de overlay por agente, no por shell bifurcado
Cada fila de agente puede llevar etiquetas de alcance, prompts iniciales, prefijos de exportación y listas de acceso. Las diferencias entre despliegues deberían elegir qué filas se cargan, no reescribir el shell. Los overlays escalan; las bifurcaciones multiplican el soporte. La figura 4 muestra la forma de la fila.
Figura 4. La fila de overlay como datos. El alcance, los iniciadores, los prefijos de exportación y las listas de acceso viajan con el agente. Elegir filas no es reescribir el shell.
3. Listas de acceso sin arqueología de JWT en la SPA
La API de catálogo devuelve lo que este llamador puede ver. La SPA pinta esa lista. Decodificar roles en el navegador para filtrar ids fijos duplica la política y acaba desviándose. Un único payload de acceso es mejor que tres copias de cadenas de roles. La figura 5 muestra el reparto de responsabilidades.
Figura 5. La API de catálogo es responsable de la visibilidad. Un React que decodifica JWT y filtra ids de agente fijos es la forma en que la política se aleja de la API.
4. Los microtextos se quedan bajo los toggles padre
El tono y los textos de ayuda de una funcionalidad van con su feature flag, no repartidos junto a los ids de agente. Si no, corriges una errata en cuatro ramas y te dejas la quinta. Los toggles padre mantienen los textos revisables.
5. El core se queda libre de agentes especializados
Los packs especializados llegan como datos y configuración. El repo del core no debería necesitar un pull request cada vez que se añade un agente especializado para un equipo. Si la lista de PR del core es sobre todo de ids de agente, has invertido la arquitectura.
6. Amplía las pruebas con una matriz de flags
Prueba solo generales, solo especializados, flag desactivado y flag activado. No mantengas una suite de pruebas separada por cada shell bifurcado. Cuando un flag cambie su valor por defecto, la CI debería avisarte antes que un release.
Cómo se llevan bien los overlays y la autorización
Los overlays no son un segundo sistema de autorización. Decoran un catálogo que ya está autorizado. Si la lista de acceso de una fila no coincide con la comprobación de roles de la API, gana la API y la fila está mal. Construye un validador que haga fallar la CI cuando las declaraciones de acceso de un overlay superen lo que los roles pueden conceder. La configuración que promete de más es un fallo de seguridad con una cara amable de JSON.
Migración desde ids fijos en el código
Haz inventario de cada rama sobre id de agente. Clasifica cada una como funcionalidad del producto, campo de overlay o caso realmente único que debería ser un flag. Mueve los campos a filas. Sustituye las ramas por comprobaciones de flags. Borra las listas de ids muertas. Guarda un ADR breve para que el siguiente ingeniero no vuelva a meter "solo un if" para un agente favorito. Los agentes favoritos también son filas.
Operabilidad para la guardia
Cuando un prompt inicial está mal, la guardia debería editar datos de overlay o una configuración con flag, no publicar un hotfix del shell. Cuando una funcionalidad falla para todo el mundo, cambia el flag padre. Separa esos runbooks. Mezclar "arreglar un agente" con "desactivar las citas para todos" en la misma ruta de pánico es la forma de tumbar la superficie equivocada.
Errores comunes
Catálogos de if-else. Cada id de agente enseña un caso especial nuevo.
Analizar JWT en React. La política se aleja de la API. La figura 5 hace visible ese fallo.
Textos bifurcados. La misma funcionalidad, cinco redacciones y ningún responsable.
Ramas por equipo. Un shell se convierte en muchas aplicaciones.
Sopa de flags sin responsables. Nadie sabe qué significa "true" en producción.
Pruebas por bifurcación. La velocidad muere y crece el miedo al merge.
Úsalo tal cual o adáptalo
Úsalo tal cual
- La UX compartida del shell se controla con feature flags del producto, no con ramas por id de agente.
- Los overlays por agente llevan como datos el alcance, los iniciadores, los prefijos de exportación y las listas de acceso.
- La SPA consume payloads de catálogo autorizados; no se analizan roles de JWT para la visibilidad de los agentes.
- Los agentes especializados se publican como packs y configuración; el core sigue libre de agentes fijos por equipo.
- La CI se amplía con una matriz de flags y roles, no con shells bifurcados.
- Las declaraciones de acceso de los overlays se validan frente a las reglas de autorización de la API.
Adáptalo antes de usarlo
Los flags y los overlays añaden superficie de configuración. Los ids fijos en el código parecen más rápidos con los primeros agentes y se hunden cuando crece el catálogo. Los catálogos gobernados por la API necesitan pruebas a nivel de API; el análisis de roles en el navegador necesita conocimiento tribal. La responsabilidad sobre los flags y la disciplina al nombrarlos son obligatorias; los flags sin nombre se convierten en minas. Un core limpio con overlays exige trabajo de empaquetado al principio y elimina para siempre el impuesto de las bifurcaciones.
Referencias principales: la guía de feature flags de Azure App Configuration y, cuando aplique, la documentación de Microsoft Foundry o de la API de tu catálogo de agentes en Microsoft Learn. Acompaña la documentación de los flags del producto con el ADR de autorización para que los toggles nunca se conviertan en una puerta trasera.
Controla la UX compartida con flags. Describe los agentes como overlays. Deja la política en la API. Prueba la matriz. El shell debería sentirse como un solo producto aunque el catálogo tenga muchos especialistas.