> Esta traducción se ofrece por comodidad. El texto normativo es el original en inglés. # Patrones de integración de IA **Especificación del Meta-Universo** **ID del documento:** MU-V2-GUIDE-009 **Título:** Patrones de integración de IA **Clase de documento:** informativo **Versión:** 2.0 (borrador) **Estado:** borrador de trabajo **Referencias normativas:** ninguna **Referencias informativas:** [AI-Agent-Guide](../07-guides/AI-Agent-Guide.md), [Contract](../04-core-concepts/Contract.md), [Projection](../04-core-concepts/Projection.md), [Event](../04-core-concepts/Event.md), [Provenance-Graph](../02-architecture/Provenance-Graph.md), [MMAS-Interchange](../02-architecture/MMAS-Interchange.md) **Copyright:** © Orkestron.AI **Licencia:** Apache-2.0 --- # 1. Propósito Esta guía da **patrones concretos** para construir agentes de IA sobre el Meta-Universo. Es el acompañante de implementación de la [guía de agentes de IA](../07-guides/AI-Agent-Guide.md): donde aquel documento explica el bucle de razonamiento y los principios, este muestra cómo cablear un agente real basado en un modelo de lenguaje - esquemas de llamada a herramientas, RAG, un Contrato aplicado dentro del bucle del agente, almacenes vectoriales y de grafo - sobre esos principios. Los patrones dan por supuesto que el agente usa el modelo de lenguaje como *motor de razonamiento*, no como almacén de conocimiento: el conocimiento, las reglas y la historia viven en modelos semánticos gestionados fuera de los pesos del modelo. --- # 2. El bucle de razonamiento, implementado Todos los patrones de aquí sirven a un mismo bucle, tomado de la [guía de agentes de IA](../07-guides/AI-Agent-Guide.md): ```text Task → Context → Meta-Models → Contracts → Projections → Reasoning → Events → Traceable Result ``` Las secciones siguientes asignan a cada etapa una técnica concreta: - **Meta-modelos** → cargados en el LLM como esquemas de llamada a herramientas y restricciones de salida estructurada (sección 3); - **Proyecciones + Sucesos** → recuperados mediante RAG sobre el significado, no sobre filas crudas (sección 4); - **Contratos** → aplicados como Contrato semántico ejecutable dentro del bucle (sección 5); - **Razonamiento + Resultado trazable** → asentados en almacenes vectoriales y de grafo (sección 6). --- # 3. Patrón: cargar un meta-modelo en un LLM Un meta-modelo se carga en el modelo de lenguaje de dos formas complementarias: - **Como esquemas de llamada a herramientas.** Cada Objeto, cada petición de Proyección y cada acción de registro de Suceso que el agente puede realizar se expone como una herramienta cuyo esquema de parámetros deriva de las definiciones [MUIF](../02-architecture/MMAS-Interchange.md) del meta-modelo. El CSN de un concepto pasa a ser el nombre canónico de la herramienta o del campo, de modo que el modelo llama a las herramientas *en el vocabulario del dominio* en lugar de inventarse uno. - **Como restricciones de salida estructurada.** Cuando el agente debe emitir una Proyección o una aserción, la salida esperada se restringe al esquema de la primitiva pertinente. El modelo rellena una forma conocida; no suelta un JSON libre que quien llama tenga luego que adivinar. Como los nombres de herramientas y de campos son CSN, el mismo agente se reorienta a un dominio nuevo cargando otro meta-modelo - el bucle no cambia, solo cambian los esquemas. --- # 4. Patrón: RAG sobre proyecciones y sucesos El RAG convencional recupera filas crudas o fragmentos de documentos. Un agente del Meta-Universo recupera **significado**: - Indexa y recupera sobre [Proyecciones](../04-core-concepts/Projection.md) - las vistas mínimas y apropiadas al contexto - en lugar de sobre registros internos crudos. El agente recibe solo lo que la tarea necesita, ya conformado para su Contexto. - Indexa y recupera sobre [Sucesos](../04-core-concepts/Event.md) y la [línea de tiempo semántica](../04-core-concepts/Event.md), para que el agente pueda recuperar *qué pasó y por qué* y reconstruir estados históricos, y no solo la instantánea actual. - Lleva al prompt la arista de procedencia de cada elemento recuperado, de modo que el contexto recuperado ya sea trazable a través del [grafo de procedencia](../02-architecture/Provenance-Graph.md). El efecto: la recuperación devuelve conocimiento interpretable y conformado por contrato, con su linaje adjunto - no texto anónimo que el modelo deba reinterpretar. --- # 5. Patrón: un contrato semántico ejecutable en el bucle del agente Un [Contrato](../04-core-concepts/Contract.md) se aplica como **Contrato semántico ejecutable** *dentro* del bucle del agente, no solo documentado a su alrededor. Al Contrato se le consulta en cada paso: - **Proyecciones permitidas**: el bucle solo pide las Proyecciones que el Contrato permite para el Propósito de la Tarea; una petición fuera de ese conjunto se rechaza antes de leer dato alguno. - **Campos ocultos**: los campos que el Contrato marca como no divulgables se filtran de las Proyecciones recuperadas antes de que lleguen a la ventana de contexto del modelo, de modo que el LLM nunca ve lo que no puede usar. - **Sucesos notificados al propietario**: las acciones que el Contrato designa como significativas emiten [Sucesos](../04-core-concepts/Event.md) inmutables que notifican al Universo propietario, de modo que las divulgaciones y las decisiones con consecuencias dejan un rastro auditable. En concreto, el contrato envuelve cada llamada a herramienta: ```text for each step in the agent loop: proposed_action ← LLM(context) contract.check(proposed_action.purpose, proposed_action.projection) → allow | deny | redact if allow/redact: result ← execute(proposed_action) # redact hidden fields if action is significant: emit Event → notify owner else: return refusal to the model with the reason ``` El Contrato es así una barrera en tiempo de ejecución: el agente *no puede* exceder sus permisos de divulgación aunque el razonamiento del modelo lo intente. --- # 6. Patrón: almacenes vectoriales y bases de datos de grafo Los dos almacenes juegan papeles complementarios en el bucle: - **Almacén vectorial**: alimenta la recuperación RAG de la sección 4; los embeddings de Proyecciones y de resúmenes de Sucesos permiten la búsqueda semántica *del significado que la tarea necesita*. Responde a "¿qué es relevante?". - **Base de datos de grafo**: guarda el [grafo de procedencia](../02-architecture/Provenance-Graph.md) y la estructura de Relaciones del meta-modelo. Responde a las preguntas estructurales de [Provenance-Graph §7](../02-architecture/Provenance-Graph.md) - justificación ("¿por qué es esto cierto?"), impacto ("¿qué se rompe si cambia X?") y dependencia - que la búsqueda por similitud no puede responder. Un agente competente usa ambos: el almacén vectorial para *encontrar* contexto candidato y el grafo para *justificarlo y acotarlo*. Recupera por similitud; verifica y traza recorriendo. --- # 7. Recorrido de una tarea de agente **Tarea:** "Redacta una recomendación de promoción para el empleado E". ```text Task : draft a promotion recommendation for employee E Context : purpose = HR review; audience = E's manager; constraint = internal only Meta-Models : Employee + Organization Meta-Models loaded as tool schemas (CSNs) Contracts : HR Disclosure Contract bound to the loop (Purpose = HR review) Projections : vector store retrieves E's Competency Projection and the Promotion-Policy Projection — already filtered of salary fields the contract hides Reasoning : the LLM applies the policy to the competency evidence; the graph store supplies the justification chain (Competency ← Reviews ← Feedback) Events : agent emits a Disclosure Event (recommendation drafted under HR Contract); owner is notified Result : a recommendation, explainable back through Context, Contract, Projections and the Provenance Graph to its source observations ``` Lo que hace fiable el resultado no es la prosa: es que toda afirmación se traza a través del [grafo de procedencia](../02-architecture/Provenance-Graph.md) hasta la evidencia que la sostiene, que el salario que el modelo nunca vio quedó excluido por el Contrato, y que el propio borrador queda registrado como [Suceso](../04-core-concepts/Event.md). Ese mismo agente, con otro meta-modelo y otro Contrato, realiza una tarea completamente distinta con las mismas garantías. --- # 8. Lista de comprobación de integración Al construir un agente sobre estos patrones, confirma que: - los meta-modelos se exponen como esquemas de llamada a herramientas con nombres CSN; - las salidas están restringidas a esquemas de primitivas; - el RAG recupera Proyecciones y Sucesos, no filas crudas; - hay un Contrato aplicado dentro del bucle (Proyecciones permitidas, campos ocultos, Sucesos notificados al propietario); - un almacén vectorial se ocupa de la relevancia y uno de grafo, de la procedencia y el impacto; - toda acción significativa emite un Suceso inmutable; - todo resultado es trazable a través del grafo de procedencia. --- # 9. Direcciones futuras Estos patrones podrían converger en un **perfil de runtime de agente** reutilizable: un generador estándar de esquemas de herramientas a partir de [MUIF](../02-architecture/MMAS-Interchange.md), una biblioteca de referencia para aplicar el Contrato semántico ejecutable, y un contrato de recuperación que ate los almacenes vectorial y de grafo a las Proyecciones y al grafo de procedencia. Junto con la negociación autónoma de federación de la [guía de agentes de IA](../07-guides/AI-Agent-Guide.md), un perfil así permitiría que cualquier agente conforme se enchufara a cualquier Universo con procedencia, límites de divulgación y explicabilidad garantizados por construcción. --- # Declaración final Construir un agente de IA sobre el Meta-Universo no va de un prompt más ingenioso. Va de cablear el modelo de lenguaje dentro de un bucle donde el dominio, las reglas, las vistas y la historia viven en modelos semánticos gestionados a su alrededor - de modo que lo que el agente recupera es significado, lo que puede divulgar está acotado por la fuerza, y lo que concluye siempre puede rastrearse hasta la evidencia que lo hizo cierto.