Anatomía de un Fabric Data Agent: las 8 partes que escribes para que responda bien

Te confieso algo incómodo: los primeros Fabric Data Agents que configuré respondían distinto a la misma pregunta según el día. El SQL era válido. El DAX era válido. Y el número, a veces, estaba mal.

Tardé varios proyectos en entender por qué. La respuesta no fue “mejor modelo” ni “mejor prompt”. Fue darme cuenta de que un Data Agent no se entrena: se escribe. Su precisión vive en partes concretas que autoras tú — y siempre son las mismas ocho.

En resumen — Crear el agente es un clic. Que responda correcto y consistente son 8 partes que escribes: rol, fuentes, instrucciones, few-shots, glosario, arquitectura, aprovisionamiento y ciclo de vida. Aquí está la anatomía, aterrizada en un ejemplo sanitizado de punta a punta.

Crear es fácil. Responder bien, no.

Un Fabric Data Agent es una interfaz de lenguaje natural gobernada sobre tus datos. El usuario pregunta; el agente elige una fuente, genera la consulta en su lenguaje (SQL, DAX, KQL o GQL), la ejecuta bajo la identidad de quien pregunta —así se respetan Row-Level Security y permisos— y devuelve una respuesta anclada en datos.

No es un chatbot con datos pegados en un prompt. No es un modelo afinado. Es una capa de generación y ejecución de consultas cuya precisión controlas por configuración. Y si la precisión es configuración, la precisión es algo que escribes.

La anatomía: 4 partes centrales, 3 alrededor

Para no quedarme en abstracto, cada regla la aterrizo en un agente completo sobre Contoso Retail: un modelo de ventas minoristas sintético (~126 mil líneas de venta en pesos mexicanos, ocho tablas). No es un ejemplo de juguete ni uno que tengas que creerme — el ejemplo completo es público y reproducible: modelo, datos, instrucciones del agente y few-shots, el mismo que uso en el resto de la serie. Cada regla que menciono la puedes abrir y repetir.

El agente Contoso Retail en acción (panel “Test data agent”): pregunta en lenguaje natural, DAX generado y ejecutado sobre el modelo ContosoRetail, y números que puedes auditar — ventas 2024 de $10,387,132 y margen de $2,039,927 MXN. Todo lo que sigue es cómo se llega a que esos números sean los correctos.

01 · La identidad no es “un asistente útil”

Es el texto de mayor palanca: vive en un campo de hasta 15.000 caracteres que el orquestador lee primero, en cada turno. Déjalo en blanco con un “eres un asistente de datos útil” y el agente tratará cada fuente como igual de válida para cada pregunta.

Contoso abre con rol y grano explícitos, nada más:

Eres un analista de ventas retail para Contoso. Respondes preguntas sobre ventas, rentabilidad, clientes, productos y tiendas usando el modelo ContosoRetail. Nunca inventas números, medidas ni campos que no estén en el modelo.

02 · Fuentes: el lenguaje lo decide la fuente

Un agente combina hasta 5 fuentes, y cada tipo trae su traductor:

La regla que aplico: si existe un modelo semántico y la pregunta es de métrica, úsalo. El modelo ya codifica aditividad, moneda, filtros y time intelligence — el agente hereda esa lógica en vez de reinventarla con un SUM sobre una columna de hechos. Contoso usa una sola fuente semántica y ocho tablas seleccionadas: no todo el workspace.

03 · Las reglas que evitan el número plausible-pero-mal

Tres reglas que parecen obvias y que casi nadie escribe:

• Aditividad. Un modelo con gusto sumará un porcentaje o promediará una tasa entre filas. En Contoso solo se suman las medidas de volumen —[Total Sales], [Total Quantity], [Total Cost], [Gross Margin]—; [% of Total Sales], [Margin %] y [Average Order Value], nunca: se recalculan en su contexto.
• El denominador con nombre. “Ventas por cliente” está mal si el denominador es la población equivocada. [Sales per Customer] divide entre [Distinct Customers] (clientes que compraron en el periodo), no entre la base total de clientes — y la regla obliga a declarar cuál usó, así el número es auditable.
• Desambiguar antes de adivinar. Ante un “muéstrame las ventas” sin periodo ni grano, el default es elegir uno y responder ocultando el supuesto. La regla lo convierte en un supuesto declarado o una pregunta corta. Lo mismo con “margen”, que es ambiguo: [Gross Margin] es el importe y [Margin %] la tasa — hay que decir cuál.

“¿Cuál fue el margen?” es ambiguo, y el agente no adivina en silencio: declara que usó [Gross Margin] (el importe, $2,039,927), no [Margin %] (la tasa). Esa línea —“el margen (Gross Margin)”— es la regla funcionando.

Y una que rinde muchísimo: declarar medidas compañeras. En Contoso, la descripción de [Total Sales] en el modelo pide reportarla junto a [Total Quantity] y [Orders] — así, una pregunta por las ventas totales puede devolver sus compañeras del mismo periodo sin pedirlas. La regla vive en el modelo, no en un prompt suelto:

EVALUATE
ROW(
  "Total Sales",    [Total Sales],
  "Total Quantity", [Total Quantity],
  "Orders",         [Orders]
)

04 · Few-shots: la asimetría que sorprende a todos

Las instrucciones dicen las reglas; los few-shots —pares pregunta→consulta— las muestran. Y mostrar generaliza donde decir no lo hace. Pero dónde los autoras depende del tipo de fuente, y aquí tropieza mucha gente:

• Lakehouse, warehouse, KQL → los ejemplos van en el propio Data Agent (panel de example queries).
• Modelo semántico → ese panel no acepta pares. El contexto vive en el modelo, vía Prep for AI: AI Data Schema (qué ve la IA), AI Instructions (reglas y DAX de ejemplo) y Verified Answers (pregunta→visual aprobado). El agente los honra todos; no los configuras en el agente.

Si pegas tus pares DAX en el panel esperando que el modelo semántico aprenda, no pasa nada. En silencio.

05 · Ontología: del negocio al campo del modelo

La ambigüedad es donde el agente se equivoca calladamente. “Rendimiento por territorio” se resuelve a una columna Territory de productos cuando el usuario quería regiones de venta — consulta válida, respuesta mal. El glosario cierra esa brecha, y no es un archivo aparte: vive en las descripciones del modelo y en Prep for AI.

En Contoso: “clientes” significa exactamente [Distinct Customers], no las filas de DimCustomer; un “desglósalo” sin dimensión cae a un juego declarado —DimProduct[CategoryName], DimStore[CountryName], DimCustomer[Country] o FactSales[Channel]—; y se advierte que los valores de dimensión están en español (Electrónica, Electrodomésticos), para que el agente no busque Electronics. Ese último detalle parece menor y evita respuestas vacías.

06 · Directo vs. orquestador

Dos arquitecturas, y conviene elegir a conciencia:

• Directo — hablas con un agente que rutea internamente entre sus fuentes. Contrato ajustado: un artefacto, un set de instrucciones, un lugar para probar y gobernar. Es mi default.
• Orquestador — un agente externo (Foundry, Microsoft 365 Copilot, Copilot Studio) trata al Data Agent como una herramienta entre varias. Compra alcance, al costo de una segunda capa que puede reinterpretar la salida.

En ambos, la autorización fluye On-Behalf-Of: el agente nunca excede los permisos de quien pregunta. Lo bueno de construir directo y limpio es que promoverlo a orquestador no exige deshacer nada — su rol se lee casi textual como la descripción de la herramienta.

07 · Aprovisionamiento: el portal nace, el código mantiene

El portal es donde el agente nace; config-as-code es donde se vuelve un producto mantenible. Serializar la configuración a Git la vuelve revisable y diffeable, y el layout mapea uno a uno con la anatomía:

Detalle que delata la asimetría del punto 04: una fuente de modelo semántico no tiene fewshots.json — porque sus ejemplos viven en Prep for AI. Y una regla de oro: los IDs de workspace/modelo son GUIDs por entorno; van como parámetros, nunca hard-coded en el repo.

08 · Lo que caduca en 2026 (y lo que no)

Históricamente, los clientes externos consumían un agente publicado vía la OpenAI Assistants API. OpenAI la retira el 2026-08-26: el código sobre ella funciona hasta esa fecha y se detiene después.

Lo importante es qué no se rompe: el agente, sus fuentes, sus instrucciones, su glosario. Caduca el protocolo de cliente, no el agente. Las salidas: el MCP endpoint (el camino evergreen), Foundry Agent Service (bajo identidad OBO) y la Responses API. Reapuntas el cliente y el agente sigue respondiendo — todo lo que lo hizo correcto sobrevive a la API que cargaba sus respuestas.

La conclusión práctica

Si trabajas con Fabric Data Agents, quédate con una idea: la precisión no está en el botón de Crear; está en las 8 partes que escribes. Y no pesan igual. Empieza por dos — la identidad y las reglas de aditividad y denominador — porque es donde más rápido se gana o se pierde la confianza en el número.

Lo demás es iteración: mira dónde se equivoca, y arréglalo en la parte que corresponde. Casi nunca es el modelo. Casi siempre es algo que no le habías escrito.

¿Quieres cada parte a fondo? La referencia completa de las 8 partes —con el ejemplo Contoso de punta a punta— vive en el repo público fabric-data-agents: este post es la historia; el repo es el manual.

¿Y cuánto pesa cada parte, en números? Eso no se supone: se mide. En Probé si el Prep-for-AI cambia las respuestas de un Fabric Data Agent monté un A/B controlado sobre una de ellas —el Prep-for-AI del modelo— con el mismo dato y la misma pregunta. El resultado me sorprendió, y la lección de método más todavía.

Referencias

• Fabric data agent — conceptos (Microsoft Learn) — qué es, configuración y capas de gobernanza
• Añadir y configurar fuentes de datos — SQL / Eventhouse / Semantic Model / Graph y sus traductores
• Buenas prácticas de modelo semántico para Data Agent — Prep for AI: AI Data Schema, AI Instructions, Verified Answers
• Source control, CI/CD y ALM para Data Agent — el layout config-as-code en Git
• Consumir un Data Agent con el Python client SDK — la caducidad 2026-08-26 y la migración al MCP endpoint