Construir la capa de contexto: del almacén de un Worker al corpus de toda la fuerza laboral — Curso intensivo
15 conceptos · Onyx, MCP y cuatro clases de fuentes · Construido por tu agente, no a mano
Contexto consultable con IA construyó un almacén propio para un Worker. Este curso construye el corpus que consulta toda la fuerza laboral.
En Contexto consultable con IA diste a un Worker un almacén propio: tus documentos fragmentados, convertidos en embeddings y consultables por significado, dentro de un único Neon Postgres bajo tu control. Incluso lo envolviste como herramienta MCP para que otros agentes pudieran invocarlo.
Sin embargo, seguía siendo un almacén acotado, con una frontera trazada por ti. Elegiste cada documento, decidiste quién podía acceder y no llegó nada que no hubieras colocado.
Ahora entra en el edificio de un cliente.
Sus veinte años de papeles de trabajo están en SharePoint. Las cartas de encargo, en el correo. La razón de una decisión vive en un hilo de chat y en la cabeza de una responsable que está de viaje. Los saldos actuales están en un sistema que cambia cada hora. Nada de ello es tu almacén. Todo hace falta para completar el trabajo.
Este curso construye la capa que llega a todo ello, alrededor de una pregunta que una empresa real sí haría:
Northstar Services quiere un descuento del veinte por ciento, quiere que se le facture ahora y quiere reconocer los ingresos de implementación este trimestre. ¿Puede hacerlo?
Es una frase de un cliente, pero no una sola pregunta. Es una pregunta comercial, una contable, una sobre estado en vivo y un comentario de oídas en un correo. Responder bien exige mantener las cuatro separadas. Al final, un Worker responderá correctamente, con citas, hechos actuales consultados en vivo, el correo marcado como evidencia y no como autoridad, y las dos decisiones profesionales separadas en lugar de fundidas en un sí alegre.
Tres palabras por si son nuevas. Un conector lee un sistema fuente y mantiene actualizada una copia de su contenido. Indexar significa guardar esa copia para poder buscarla. Herencia de permisos significa transportar las reglas de acceso de cada documento desde su sistema de origen hasta cada resultado, para que la persona solo vea lo que ya podía abrir.
Una idea hace que todo el curso encaje. El curso anterior tenía una pregunta: ¿está el fragmento correcto en la ventana de contexto? Este tiene tres, y cada concepto las sirve. Para todo lo que devuelve la capa:
¿De dónde vino? ¿Puede verlo esta persona? ¿Sigue siendo la autoridad vigente?
Un cuadro de búsqueda no responde ninguna. Una capa de contexto responde las tres, para cada elemento, cada vez. Esa es toda la diferencia y la razón por la que esto es un curso, no un archivo de configuración.
| Término | Significado sencillo |
|---|---|
| System of Record | Sistema que conserva oficialmente algo. Si una copia discrepa, la copia está equivocada |
| Vertical | Una profesión o industria, como contabilidad, derecho o ingeniería de ventas; lo opuesto a propósito general |
| Authority class | Qué clase de afirmación es y qué peso tiene: ley, norma, contrato, política, transacción, orientación, mensaje o ejemplo |
| Working context | Material cotidiano de una empresa: correo, chat, borradores y archivos. Real y útil, pero nunca la regla |
| Connector | Pieza que lee un sistema fuente y mantiene actualizada una copia |
| Sync | Una ejecución del conector que obtiene lo cambiado desde la anterior |
| Index | Copia consultable que conserva la capa para encontrar cosas con rapidez |
| Corpus | Todo el contenido que puede buscar la capa en todas las fuentes conectadas |
| Fixture | Archivo ficticio pero realista creado para practicar sin arriesgar datos reales |
| Document Set | Grupo con nombre de conectores que limita dónde puede buscar una consulta |
| Onyx Agent | Asistente configurado en Onyx con instrucciones, conocimiento y herramientas |
| Action | Herramienta que puede invocar un Onyx Agent, como tu búsqueda o una consulta en vivo |
| Canonical | Copia original y oficial, frente a una copia derivada |
| Projection | Copia consultable de contenido gobernado, conservada solo para encontrar el original |
| Stable ID | Nombre permanente de una regla para que una copia apunte a su original |
| Superseded | Sustituido por una versión más nueva y ya no vigente |
| Gateway | Código propio delante de Onyx que decide qué puede buscar esta persona |
| Packet | Paquete de reglas, hechos y evidencias reunido para una pregunta |
| Envelope | Etiquetas de un elemento: origen, versión y razón por la que puedes verlo |
| Provenance | Historia completa del origen de una información |
Los demás términos nuevos se explican al aparecer por primera vez.
Este curso presupone Contexto consultable con IA. Debes tener un RAG funcional en Neon con pgvector, conocer la fragmentación y un embedding worker y saber juzgar la calidad de recuperación con un conjunto de evaluación. Conserva ese proyecto Neon. Aquí reutilizas su infraestructura y sus habilidades de recuperación. Pero distingue con claridad lo que construyó y lo que no, porque esa diferencia es el tema del curso.
Ese curso construyó un almacén de recuperación acotado: documentos, fragmentos, embeddings, una función de búsqueda, una función de respuesta y un conjunto de evaluación. Enseñó cómo los documentos se convierten en conocimiento consultable. No dio al almacén autoridad profesional: no hay authority classes, jurisdicciones, periodos de vigencia ni enlaces de sustitución. Por eso en el Concepto 10 agregas un pequeño esquema gobernado junto a lo existente y el Concepto 10 llega a él. También presupone Programación agéntica para dirigir Claude Code u OpenCode en plan mode y Skills y Connectors para MCP.
La página conceptual detrás de esta construcción es El sistema de contexto. Léela primero si quieres el argumento. Este curso es la planta de producción y Northstar es el mismo ejemplo que descompone esa página.
Este es todo el sistema en una página, el mapa al que irás llegando con cada concepto:
Qué cubre este curso
| Parte | Tema | Qué aprenderás |
|---|---|---|
| 1 | Fundamentos | El salto de alcance, cuatro clases de fuentes, Onyx Standard, un modelo y una línea base de búsqueda |
| 2 | Tu primer corpus | El libro como método compartido, fixtures de Northstar, Document Sets, fragmentador y puerta de permisos |
| 3 | La mitad gobernada | Tu registro Neon mediante MCP, descubrimiento frente a confirmación y estado en vivo |
| 4 | Enrutamiento y citas | El mapa de autoridad antes del prompt, el paquete de siete secciones y conflictos que no deben mezclarse |
| 5 | El caso Northstar | Toda la construcción de principio a fin y cuatro formas de romperla a propósito |
| 6 | Demuéstralo | Ocho dimensiones de evaluación y por qué el modelo que respondió no debe evaluarse a sí mismo |
| 7 | Servirla y operarla | Una puerta para cada Worker externo, salud de conectores, actualizaciones y definición de terminado |
Un despliegue funcional de Onyx Standard con cuatro clases de fuentes conectadas y separadas. El libro Agent Factory indexado como método compartido. Dos registros Verticales de Northstar, ventas y contabilidad, que discrepan de forma útil. Un servidor MCP en vivo para el estado actual. Tu registro Neon servido mediante MCP y nunca rastreado. Un authority-map.yaml versionado que dice qué registro gobierna cada pregunta. Un Context Router que siempre devuelve las mismas siete secciones con citas. Una puerta de permisos escrita por ti y probada con un rol cuya respuesta correcta es nada. Un conjunto de evaluación con ocho dimensiones. Y un endpoint MCP Context Gateway que permite consultar el corpus compartido a Workers externos autorizados mediante la misma frontera de identidad y permisos.
Cómo leerlo. Las Partes 1 y 2 más la construcción Northstar de la Parte 5 forman el sistema completo: unas dos horas de lectura y varias horas de teclado. Las Partes 3 y 4 lo hacen confiable en vez de solo funcional, y ninguna es opcional: la Parte 5 las ejecuta de verdad. ¿Prefieres construir primero y leer el motivo después? Empieza en la Parte 5.
📚 Ayuda didáctica
Se está preparando una presentación para este curso.
Configura el entorno una vez
Todo lo que construirás vive en una carpeta y viene conectado de antemano.
Descargar context-layer-base.zip
Descomprímelo. Dentro están el caso Northstar listo para conectar, los archivos de gobierno listos para completar y tres esqueletos de servidores MCP con las partes difíciles marcadas como TODO:
fixtures/ two governed records, live state, working context
plus PLANTED.md, the answer key for Part 5
governance/ authority map, model register, permission matrix,
production gates, boundary contract
mcp/ vertical_sor, customer_state, context_gateway
prompts/ the Context Router instruction file
evals/ ten cases, scored on eight dimensions
scripts/ the governed schema for your existing Neon project
AGENTS.md the standing rules your agent reads every session
.env.example every credential this course needs, and nowhere else to put them
cd context-layer-base
cp .env.example .env
Este curso maneja más credenciales que el anterior, y cada una permite perder la confianza de un cliente en un solo commit.
| Secreto | Qué abre |
|---|---|
| Neon pooled connection string | tu registro gobernado |
| Model provider API key | tu gasto en modelos |
| Onyx admin login | todo el corpus |
| Onyx API key | búsqueda con todo lo que esa clave pueda ver |
| Onyx MCP token | opcional, solo para comparar el endpoint nativo en la Parte 7 |
| Context Gateway tokens | uno por rol, asignado en el servidor. Estos son la frontera de permisos |
Todos viven en .env, que .gitignore ya excluye, salvo el Onyx admin login, que pertenece a tu gestor de contraseñas. Ninguno pertenece a un archivo que confirmes, un prompt que pegues o una salida de terminal que captures para otra persona.
Dile expresamente a tu agente que lea las credenciales del entorno, nunca las escriba en un archivo que se confirmará y nunca las imprima. Después revisa el diff antes de aprobarlo.
Coste antes de empezar. Ninguno si ya completaste el curso anterior.
| Elemento | Coste |
|---|---|
| Onyx Community Edition | gratuito, núcleo MIT |
| Neon | nivel gratuito, sin tarjeta |
| Model provider | un nivel gratuito basta para este curso |
Tiempo necesario. Las Partes 1 y 2 son unas dos horas de lectura y dos o tres de teclado. La instalación del Concepto 4 tarda unos veinte minutos, sobre todo descargando imágenes. La construcción Northstar de la Parte 5 ocupa un día largo, más si es tu primer servidor MCP. No intentes hacerlo en una sola sesión. Una buena división es Onyx y los conectores primero, el registro gobernado y sus dos servidores MCP después, y por último la puerta y el Router. Cada bloque es una lección; acumular los tres en una tarde hace que la gente crea que no sabe hacerlo.
Además de la carpeta necesitas tres cosas: Docker, porque Onyx funciona como un conjunto de contenedores; uv, para la parte Python; y tu agente. Ábrelo dentro de la carpeta:
cd context-layer-base
claude
cd context-layer-base
opencode
Una advertencia antes de comenzar, porque determina dónde ejecutarás esto.
Onyx es infraestructura real. Un despliegue Standard levanta aproximadamente doce contenedores a la vez: frontend web, backend API, proxy nginx, Postgres, índice de búsqueda, Redis, almacenamiento de objetos, dos servidores de modelos, intérprete de código y workers de sincronización en segundo plano.
Necesita varios gigabytes de RAM. No resulta cómodo en un portátil modesto con todo lo demás abierto. Hay tres opciones, en este orden de preferencia para una clase:
| Opción | Adecuada para | Coste |
|---|---|---|
| Una instancia de laboratorio compartida por la institución | Todo un grupo conectado a un Onyx accesible | Una máquina, una vez |
| Despliegue local mínimo, un solo conector | La semana de ver las partes internas y leer código | Tu RAM |
| Prueba de Onyx Cloud | Una semana o un portátil que no puede ejecutarlo | Prueba de 14 días, sin tarjeta |
Haz la semana de partes internas localmente aunque uses la instancia compartida para lo demás. Leer el código de un conector mientras se sincroniza enseña algo que ningún servicio alojado puede mostrar.
Parte 1: Fundamentos
Antes de instalar nada, cuatro ideas.
Tu almacén anterior era pequeño y seguro porque controlabas todo. Las fuentes de una empresa no son así. Llegan en cuatro clases y mezclarlas es el error más caro de esta construcción. Onyx es la herramienta: encuentra cosas bien y decide mal qué es verdadero. Además tiene dos modos de instalación, uno de los cuales desactiva en silencio aquello que este curso quiere enseñar.
1. El salto de alcance: de un almacén a las fuentes de todos
Mantén en mente la pregunta de Northstar, porque tu construcción anterior no podía ni tocarla.
¿Puede Northstar obtener el descuento del veinte por ciento, recibir la factura ahora y reconocer los ingresos este trimestre?
Nada en tu almacén Postgres sabe qué es Northstar. No sabe quién aprobó qué, cuándo llegó la aceptación ni qué escribió una responsable comercial el martes pasado. No es una carencia de tu construcción. Es otra clase de sistema.
Tu almacén tenía cuatro propiedades que quizá nunca advertiste.
Tú escribiste todo. Cada documento salió de docs/; nada llegó sin que lo colocaras. Tenía un lector. Lo que permitía tu aplicación, lo permitía el almacén. Tenía una clase de verdad. Todo era un documento escrito por ti y pesaba igual; no había saldos en vivo, obligaciones firmadas, opiniones de correo ni versiones sustituidas sin avisarte. Y era actual por construcción, porque solo tu worker escribía.
Las cuatro desaparecen al conectar una empresa.
El contenido ahora es suyo; parte es erróneo y parte está sustituido. Una persona junior y una socia hacen la misma pregunta y deben recibir respuestas distintas. El corpus contiene un contrato firmado, una política, un chat y un estado de factura en vivo, con pesos radicalmente distintos. Un documento indexado el martes puede ser sustituido el miércoles por alguien que nunca te avisará.
Northstar concreta las cuatro. El contrato y CRM son suyos. Un account executive y una VP deben recibir respuestas distintas sobre el descuento. El contrato, la política, el correo y la aprobación en vivo pesan distinto. Y la aprobación puede cambiar mientras el Worker redacta.
Ese es el salto de alcance y la razón de la nueva forma.
El curso anterior era un problema de recuperación. Este es un problema de gobierno vestido como problema de recuperación.
Tu trabajo sigue siendo dirigir al agente y juzgar lo producido, pero cambia lo que juzgas. Ya no preguntas principalmente si encontró el fragmento correcto, sino si cada elemento indica su origen, si esta persona puede recibirlo y si algo confirmó que sigue vigente.
2. Cuatro clases de fuentes y por qué llegan de forma distinta
El error más caro es tratar cada sistema conectado como una sola masa indiferenciada. Clasifícalos antes de conectar nada, porque la clase determina cómo se obtiene el contenido y qué puede hacer un Worker con él.
| Clase | Ejemplos | Cómo llega | ¿Puede citarla un Worker? |
|---|---|---|---|
| Sistema de Registro de Agent Factory | Método y normas compartidas | Indexado por web para descubrir, citado en la página canónica | Sí, como método compartido |
| Sistemas de Registro Verticales | Reglas comerciales y contables de Northstar en Neon | Indexadas para descubrir y luego confirmadas mediante MCP | Sí, como regla gobernante |
| Registros operativos del cliente | ERP, CRM, ledger, contratos | Consulta tipada en vivo, nunca indexada | Sí, para su propio estado y con marca temporal |
| Contexto de trabajo del cliente | Correo, chat, archivos, trackers | Indexación consciente de permisos | Como evidencia de lo dicho o hecho, nunca como regla |
Dos ideas del cuadro.
Las tres primeras son autoritativas para preguntas diferentes. Un mensaje común de proveedores dice que un registro tradicional «solo guarda datos» mientras la capa los interpreta. No lo repitas ante una directora financiera. Su ERP impone integridad transaccional, límites de aprobación y una pista de auditoría; esos controles permiten operar al negocio. La brecha es de alcance, no de seriedad: es completo en su dominio y guarda silencio sobre la profesión alrededor.
Solo la cuarta clase carece de autoridad profesional gobernante. El correo y el chat suelen estar gobernados por controles de acceso, retención, privacidad, legal holds y gestión documental. Lo que les falta es autoridad para resolver una pregunta profesional.
También es la clase a la que primero se dirige una herramienta de búsqueda, por lo que tantos pilotos producen respuestas fluidas sin nada detrás.
Glean incluye conectores nativos para la cuarta clase y buena parte de la tercera, además de una Indexing API. Defines una custom datasource, envías documentos con contenido, metadata y permisos y la activas en la consola.
Glean no decide tus cuatro clases. Etiqueta cada datasource como KNOWLEDGE_HUB, EMAIL, MESSAGING, CRM, TICKETS y más, pero esas categorías ajustan ranking y presentación; ninguna dice si la fuente gobierna. La clase y el uso permitido como cita siguen siendo decisiones tuyas. Onyx te obliga a construir la separación; Glean permite omitirla, motivo por el que también puede terminar como una pila plana.
El argumento completo está en La autoridad tiene alcance entre muchos registros.
Sea cual sea tu profesión, escribe esta tabla para las fuentes reales antes del primer conector. Se convertirá en el mapa de enrutamiento del Concepto 12.
3. Qué es Onyx y qué no es
Onyx se presenta como chat de IA open source conectado a documentos, aplicaciones y personas. Este curso lo trata como implementación abierta de referencia de un Sistema de Contexto; ese encuadre es nuestro. Conecta muchas fuentes, mantiene copias sincronizadas, busca por significado y palabra clave, devuelve respuestas citadas y expone agentes y acciones. Su núcleo tiene licencia MIT y puede alojarse realmente por cuenta propia. Puedes leer código de conectores, observar una sincronización y ver dónde se comprueban permisos. También funciona a escala real, por lo que lo aprendido resulta reconocible en una entrevista.
Tres cosas que no es, cada una ligada a algo que construirás.
No es tu Sistema de Registro. Onyx guarda copias para encontrar. Tu registro gobernado conserva originales para citar. Esa es la única ley: la capa transporta autoridad y nunca la posee. Si lo inviertes, el corpus puede parecer actual mientras un Worker cita la regla del año pasado desde un índice que no recibió la sustitución.
No es un sistema de permisos. Hereda permisos donde su edición lo admite y no impone por sí solo controles de tu profesión. La Parte 2 lo hace serio.
No es la respuesta. Un resultado de recuperación es un puntero: dice mira aquí. Convertirlo en respuesta requiere otra llamada, el Concepto 10.
Y algo que no es Onyx romperá la construcción más rápido que Onyx:
Tu Worker funciona sobre un language model y responderá desde su conocimiento si la recuperación no entrega nada. La salida parece idéntica a una respuesta grounded y no aparece error.
Un modelo no tiene fuente; tiene pesos. No hay fila de registro detrás de su respuesta: publisher, authority class, jurisdiction, version, periodo de vigencia ni forma de corregir una afirmación. La plausibilidad no es procedencia.
Vigila tres fugas:
- Relleno de brecha. Retrieval no devuelve nada útil y el modelo responde.
- Paráfrasis desviada. Recupera la regla correcta y pierde un umbral o condición al reformular.
- Memoria persistente. Un modelo que conserva hechos entre sesiones se convierte en un almacén sin versión ni owner.
La cura es estructural, no un prompt. La evidencia ausente es un campo del paquete y un Worker sin fuente gobernante escala en vez de continuar. El argumento completo está en la página conceptual.
Terminado cuando: puedes nombrar qué resuelve cada una de las tres: cuál corrige la confirmación, cuál corrige la puerta de permisos y cuál explica que Neon quede fuera del índice.
Glean es el Sistema de Contexto comercial más conocido y merece una hora aunque no lo despliegues.
Primero, ha popularizado la expresión system of context en el mercado empresarial actual como nombre de su capa de datos. El libro la adopta para que quien se gradúe hable el idioma de un comprador. Si Glean la acuñó es otra cuestión que no afirmamos. Segundo, allí ha puesto precio el mercado a esta capa. Una empresa puede pedir «enterprise AI search», «work assistant», «AI knowledge layer» o «enterprise context platform»; es la misma categoría y la otra persona probablemente vio una demo de Glean.
Lee sus páginas como diagnóstico, no doctrina. Pregunta:
¿Qué partes de esta arquitectura implementa el producto y cuáles deja discretamente en tus manos?
Hazlo con conectores, permisos, citas y acciones. Encontrarás las cuatro clases, el problema de permisos y la brecha entre descubrimiento y confirmación.
La categoría cambia de nombre: insight engines, cognitive search, enterprise AI search, generative AI knowledge management. Aprende la capa, no el logotipo. Las tres preguntas sobreviven a todos.
Por ello, los conceptos siguientes terminan con una nota En Glean: cómo aparece la idea y qué hace el producto frente a lo que sigue siendo tu diseño. No necesitas cuenta; debes poder explicar similitudes y diferencias en una reunión.
Entonces, ¿por qué Onyx y no Glean?
La respuesta honesta tiene tres razones; solo una trata de los productos.
Primero, no aprendes un control leyendo que un producto lo tiene. El modelo de permisos de Glean es mejor que la puerta del Concepto 9, pero invisible. Lo configuras, funciona y terminas sin saber qué ocurre cuando no funciona. Construir el camino una vez, de forma imperfecta, con un rol que no recibe nada, enseña más que configurarlo diez veces.
Segundo, una caja cerrada no enseña arquitectura. En Onyx puedes leer conectores, observar al fragmentador perder doce controles y hacer que una branch obsoleta responda mal con citas perfectas. Una página comercial no permite eso.
Tercero, la mayor parte del curso no trata del producto. Las siete decisiones de la columna dorada son juicios profesionales que no toma Onyx ni Glean: clasificación, autoridad, vigencia y tratamiento del conflicto. Un curso con Glean enseñaría las mismas siete cosas, con menos visibilidad sobre la maquinaria.
¿Y cuándo debe un cliente usar Glean?
A menudo. Dilo claramente.
Si necesita herencia de permisos en doce SaaS el próximo trimestre, comprarla supera ampliamente a construirla. Sin equipo de plataforma, hosted supera a self-hosted. Si ya compró Glean, tu trabajo no es una propuesta de migración. Conecta su registro gobernado y dile cuáles de las tres preguntas responde realmente su configuración.
La regla del curso:
Enseñamos el que puedes abrir. Desplegarás el que el cliente ya compró. La arquitectura es la misma y es la única parte que te pertenece.
4. Instala Standard, no Lite
Onyx ofrece los modos de despliegue Lite y Standard, y elegir mal te costará un día.
Lite es una pequeña interfaz de chat. Desactiva el índice vectorial, los workers de conectores en segundo plano y la infraestructura que este curso existe para enseñar. Elige Standard.
El instalador despliega con Docker Compose y pregunta qué modo quieres. El script exacto cambia, así que pide a tu agente que lea la documentación actual en vez de adivinar:
Lee las páginas oficiales actuales de Inicio rápido y Recursos de Onyx. Compara la CPU, RAM y espacio libre en disco que Docker tiene en esta máquina con sus requisitos. Instala la última versión estable de Onyx Community Edition en modo Standard, vinculada a localhost para este curso. Registra en
README.mdla versión exacta de Onyx, el método de instalación, los puertos y la ubicación de los datos persistentes. No elijas Lite. Muéstrame el plan y la comprobación de recursos antes de iniciar cualquier contenedor.
Aprueba solo cuando el plan diga Standard y nombre la ubicación de los datos persistentes. Después del arranque:
Inspecciona los contenedores y registros de Onyx en ejecución. Informa qué servicios están en buen estado, qué puerto sirve la interfaz y qué errores se repiten. No reinicies ni recrees nada sin explicar primero la causa y mostrarme el comando exacto.
Cuando Docker tiene muy poca memoria, los servicios de búsqueda e indexación de Onyx Standard se reinician, se bloquean o fallan sus comprobaciones de estado, y cada síntoma parece exactamente un error de configuración.
No dediques una hora a depurar la configuración de una máquina que asignó 4 GB a Docker.
Para un laboratorio local, el objetivo mínimo útil de Standard es 4 CPU virtuales y 10 GB de RAM. Ocho CPU y 16 GB resultan cómodos. Confirma siempre los recursos primero.
Lee el plan. Pedir la lista de contenedores no es una trivialidad. Debes terminar ese plan pudiendo nombrar tres contenedores: el índice vectorial, que consume memoria; el servidor del modelo, lento en el primer arranque; y los workers de sincronización en segundo plano, donde se oculta un conector que falla en silencio. Esos tres te sorprenderán después.
Presta atención a esto: el primer arranque descarga varios gigabytes de imágenes y el servidor del modelo tarda unos minutos en estar listo. Es normal, no un bloqueo. Si el conjunto arranca pero la búsqueda no devuelve nada, casi siempre se debe a que ningún conector ha terminado todavía su primera sincronización, no a que algo esté roto. Si un contenedor se reinicia en bucle, comprueba la memoria antes que la configuración.
Terminado cuando: puedes abrir la interfaz web, iniciar sesión como primer usuario administrador y conoces el único comando que desmonta todo el conjunto y recupera el espacio en disco.
No tienes que instalar nada. Glean funciona como servicio administrado, ya sea en su propia infraestructura o como despliegue para un solo inquilino dentro de tu cuenta de GCP o AWS. Incluso en el segundo modelo, Glean lo despliega y actualiza por ti. Por tanto, este concepto desaparece por completo, junto con la lista de contenedores, los cálculos de memoria y la supervisión del disco de la Parte 7.
Ese es el intercambio y conviene nombrarlo con claridad. Compras la eliminación de las operaciones y también renuncias a leer el código. Quien ha desplegado Onyx una vez sabe cuánto cuesta un índice vectorial y dónde falla una sincronización en silencio. Quien solo ha usado un producto alojado no sabe ninguna de las dos cosas y creerá a un proveedor que diga que es sencillo.
Un modelo, elegido con intención
Onyx separa la plataforma de contexto del language model. Configura un proveedor capaz en el panel de administración y mantén corta la lista visible: estás aquí para evaluar la capa de contexto, no para comparar diez modelos de chat. Después pide a tu agente que escriba governance/model-register.md. Allí se registran el proveedor, el modelo, la fecha, la suposición sobre el tratamiento de datos, quién puede verlo y por qué lo elegiste. Añade un campo más:
La prueba de sustitución. Un modelo más potente mejora el uso de herramientas y la composición de respuestas. No puede reparar un conector ausente, un enrutamiento de autoridad equivocado, hechos operativos obsoletos ni un límite de permisos roto. Esos son fallos de la capa de contexto y ninguna actualización del modelo los resuelve. Escribe esa frase en el registro para que tu yo futuro no pueda olvidarla bajo presión.
Una línea base de búsqueda antes de ajustar nada
El curso anterior te enseñó la maquinaria que hay bajo retrieval para que pudieras juzgarla. Ahora Onyx empaqueta esa maquinaria. No cambies de inmediato los embedding models ni actives todas las opciones experimentales, porque cambiar el embedding model obliga a reindexar todo y no es un ajuste cosmético. Empieza con los valores estables y registra en governance/search-baseline.md: versión de Onyx, embedding model, configuración de reranking, fecha de la línea base, versión del conjunto de evaluación y motivo.
La regla del curso anterior se mantiene en su forma de capa de contexto: los cambios de retrieval se evalúan, no se admiran. Onyx oculta el SQL. No elimina la necesidad de evidencia.
Ejecuta /init y redúcelo a cuatro líneas. A qué instancia de Onyx apuntas. Que todas las credenciales viven en el entorno, nunca en el repositorio. Que durante este curso jamás se conectan datos reales de clientes. Y una regla estricta que merece escribirse completa:
Nunca conectes una fuente que yo no haya aprobado explícitamente en esta sesión.
Un conector es una instrucción permanente para copiar los datos de alguien. Merece la misma revisión que un SQL destructivo.
Parte 2: Tu primer corpus
Ahora conectas contenido real y observas qué ocurre con él.
Empiezas con este libro porque es público y no exige permisos. Después creas una empresa ficticia llamada Northstar y conectas sus archivos. Observas con cuidado qué conservó el índice de búsqueda y qué descartó en silencio. Por último, construyes lo más importante del curso: una comprobación que decide qué puede encontrar cada persona.
Construiremos una pequeña empresa sintética: dos registros gobernados, dos instantáneas operativas y una carpeta de contexto de trabajo con correo y chat. Es sintética a propósito, y el Concepto 8 explica por qué eso no es un atajo.
5. Conecta el método compartido y después al cliente
Empieza por la fuente que no requiere permiso alguno. El conector Web de Onyx rastrea páginas bajo una URL base, sigue los enlaces accesibles, limpia el texto y conserva metadata de origen para las citas.
| Campo | Valor |
|---|---|
| Tipo de conector | Web |
| Nombre | AF-SOR-PUBLIC |
| URL base | https://agentfactory.panaversity.org/docs/getting-started |
| Clase de fuente | Sistema de Registro de Agent Factory |
| Base del permiso | Público |
Sí, estás indexando este libro. Ese es el objetivo. El Sistema de Registro de Agent Factory es una fuente real, pública y gobernada. Es la única clase que puedes conectar el primer día sin plantear una sola pregunta de permisos.
Una observación que se aplica a todas las fuentes gobernadas: el índice ayuda al Worker a encontrar el método. La cita debe volver a abrir la página original.
Un fragmento indexado desde la web es un puntero a una dirección web estable, no su sustituto. Es la misma forma de encontrar y después confirmar que construirás correctamente en el Concepto 10.
Ahora el cliente. Los fixtures de Northstar vienen en la carpeta base, así que los conectas en vez de generarlos. Abre fixtures/ y lee su contenido antes de conectar nada:
| Carpeta | Contenido |
|---|---|
sales-sor/ | Tres reglas de ventas gobernadas, cada una con ID estable, versión y fecha de entrada en vigor. La regla de descuentos permite a un ejecutivo de cuenta hasta un 15 por ciento |
accounting-sor/ | Cuatro reglas de contabilidad gobernadas, incluido un archivo deliberadamente sustituido que afirma que el ingreso se reconoce al facturar en vez de al aceptar |
operational/ | Dos registros JSON: aprobación pendiente y aceptación no recibida. Nunca se indexan |
working-context/ | Tres correos y dos hilos de chat; uno afirma que finanzas aceptó algo que ninguna fuente gobernada respalda |
fixtures/PLANTED.md enumera las cuatro incoherencias sembradas. No indexes ese archivo e intenta no leerlo con detenimiento hasta la Parte 5. Es la clave de respuestas.
Si prefieres generar tu propio corpus o quieres un segundo con el que probar, este prompt produce uno equivalente:
Crea una carpeta
fixtures/para un cliente sintético llamado Northstar Services.Dentro de
fixtures/sales-sor/, crea un pequeño registro de ventas gobernado: una regla de autoridad para descuentos que indique que los superiores al quince por ciento requieren aprobación del VP de Ventas, más un método de cualificación y una política de propuestas. Asigna a cada regla un ID estable, una versión y una fecha de entrada en vigor en el frontmatter.Dentro de
fixtures/accounting-sor/, crea un pequeño registro de contabilidad gobernado: una regla de ingresos por implementación que indique que el ingreso se reconoce con la aceptación del cliente, más dos entradas auxiliares, con el mismo frontmatter. Después añade un archivo sustituido que diga que el ingreso se reconoce al facturar, con una fecha de entrada en vigor anterior y un enlace superseded-by.Dentro de
fixtures/operational/, crea dos registros JSON: una oportunidad que muestre una solicitud de descuento del veinte por ciento con aprobación pendiente, y un contrato que muestre firma completa y aceptación no recibida.Dentro de
fixtures/working-context/, crea tres correos y dos hilos de chat. Un correo de un gerente de ventas debe decir «finanzas acepta que lo registremos este trimestre», algo que ninguna fuente gobernada respalda.Por último, escribe
fixtures/PLANTED.mdcon todas las incoherencias que introdujiste deliberadamente, para que después pueda comprobar que el sistema las encuentra. No indexes ese archivo.
Conecta las carpetas como conectores separados, nunca como uno solo:
| Conector | Clase de fuente | Motivo de la separación |
|---|---|---|
VERTICAL-SALES-SOR | Registro vertical | Gobierna la autoridad de descuentos |
VERTICAL-ACCOUNTING-SOR | Registro vertical | Gobierna el reconocimiento de ingresos |
CUSTOMER-WORKING-CONTEXT | Contexto de trabajo | Solo evidencia, nunca autoridad |
Estás a punto de indexar material de un cliente. Sigue siendo suyo.
Los correos, hilos de chat e incluso reglas gobernadas de Northstar son contenido del cliente, en una instancia del cliente. Nunca migran al registro vertical compartido que llevas de cliente en cliente. Eso sería contaminación: el registro de tu profesión terminaría guardando material privado de una empresa y ya no podrías llevarlo a ninguna otra.
El material solo asciende mediante la ley de promoción: un patrón se repite en tres o más clientes, se desidentifica, supera una revisión de promoción y tu experta lo reescribe con su propia voz. Eso es autoría, no copia.
La regla que debes mantener mientras conectas cosas: el mundo del cliente fluye hacia dentro. Nada fluye hacia fuera.
Observa qué no aparece en esa tabla. El JSON operativo no se conecta. Se sirve en vivo en el Concepto 11, y el motivo ocupa todo ese concepto.
Presta atención a esto: qué transporta realmente un conector por documento, además del texto. Un conector de archivos sobre una carpeta local ve una ruta, una hora de modificación y absolutamente nada sobre quién puede leerla. Un conector con un SharePoint o Drive real ve mucho más, incluidas las reglas de acceso. Esa asimetría es todo el tema del Concepto 8, y encontrarla aquí, en una carpeta, es la forma más barata de hacerlo.
También presta atención a esto: una sincronización puede aparecer como terminada mientras la búsqueda no devuelve nada; normalmente la indexación sigue ejecutándose detrás, así que espera y busca de nuevo. Un conector que muestra un error mientras la búsqueda aún funciona ha dejado en su lugar el contenido anterior, que es la trampa de la Parte 7. Además, un cambio de permisos tarda un momento en propagarse, por lo que un documento puede seguir visible durante unos segundos después de restringirlo.
Document Sets: un alcance de búsqueda, no una jerarquía legal
Un conector indica de dónde vino el contenido. Document Set es el término de Onyx para un grupo de conectores con nombre. Lo usas para indicar en qué fuentes puede buscar una búsqueda o Agent concreto.
| Document Set | Incluye | Propósito |
|---|---|---|
AF Shared Method | AF-SOR-PUBLIC | Arquitectura y doctrina |
Sales Authority | VERTICAL-SALES-SOR | Reglas de ventas gobernadas |
Accounting Authority | VERTICAL-ACCOUNTING-SOR | Reglas de contabilidad gobernadas |
Customer Working Context | CUSTOMER-WORKING-CONTEXT | Evidencia de apoyo |
Northstar Cross-Domain | los cuatro | Corpus completo del laboratorio |
Cumplen tres funciones. Hacen visible el alcance. Permiten que un Agent busque solo donde lo exige su tarea. Y permiten probar dentro de un dominio antes de hacerlo entre dominios, que es como distingues un error de enrutamiento de uno de retrieval. Una advertencia:
Un Document Set es un alcance de búsqueda, no una jerarquía de autoridad. Indica qué puede consultarse. No dice nada sobre qué gobierna.
Lo que dice qué gobierna es otro archivo, que llega en el Concepto 12.
Terminado cuando: puedes ejecutar una búsqueda limitada únicamente a Sales Authority y no obtener nada sobre reconocimiento de ingresos. Ese es el alcance funcionando, y así distinguirás después un error de enrutamiento de uno de retrieval.
6. Observa una sincronización y lo que descartó el fragmentador
Ya conoces chunking por el curso anterior, donde los controles eran tamaño y solapamiento, y lo que estaba en juego era recall. Aquí hay algo más en juego, y es mayor.
Una entrada de un registro gobernado lleva doce elementos: ID estable, dominio, clase de autoridad, jurisdicción, versión, fecha de entrada en vigor, estado de aprobación, condiciones de aplicabilidad, owner, enlace superseded-by, checker requerido y límite de permisos.
Un proceso de indexación genérico conserva la oración.
El ingreso puede reconocerse cuando se transfiere el control.
Las palabras sobreviven. Los doce controles han desaparecido y nada en el texto recuperado anuncia su ausencia.
El Worker ya no puede saber seis cosas: qué estándar gobierna la afirmación, si se aplica a este tipo de contrato, si está vigente, si se aplica en este país, si es autoridad o mera explicación y qué excepciones cambiarían la respuesta.
Obsérvalo en tu propio corpus:
Toma una regla de
fixtures/accounting-sor/que tenga versión y fecha de entrada en vigor en el frontmatter. Muéstrame el documento sin procesar y después exactamente cómo se ve uno de sus fragmentos en el índice: el texto del fragmento y cada campo almacenado junto a él. Señala con precisión qué hechos del documento completo no sobrevivieron en el fragmento.
Terminado cuando: puedes mostrar un fragmento y nombrar algo cierto sobre su documento padre que un Worker que solo leyera ese fragmento jamás sabría. Esa brecha no es un error de Onyx. Es el motivo por el que existe el paso de confirmación del Concepto 10.
La Indexing API de Glean permite adjuntar metadata estructurada a los documentos, y su knowledge graph conserva relaciones entre personas, contenido y procesos que un fragmentador sencillo descarta. Así, la brecha es menor aquí que en Onyx.
Menor no significa cerrada. Ningún producto sabe que tu regla tiene fecha de entrada en vigor, jurisdicción y enlace superseded-by si no colocas esos campos allí y enseñas al Worker a comprobarlos. Los doce controles son responsabilidad tuya en ambos casos.
7. Busca y observa qué recibiste
Busca en el corpus una pregunta cuya respuesta abarque dos documentos. Muéstrame los resultados con sus puntuaciones y fuentes; después responde la misma pregunta mediante el chat de Onyx para que pueda ver las citas que adjunta.
Ahora viene la disciplina. Formula en voz alta tres preguntas sobre cada resultado hasta que se conviertan en reflejo:
¿De dónde vino? Onyx hace bien esta parte y la cita está justo ahí. Comprueba que apunte a un documento que reconoces.
¿Puede verlo esta persona? Por ahora, la respuesta honesta es todas las personas ven todo, porque eres el único usuario y se trata de una carpeta. Conserva esa idea durante cuatro minutos.
¿Sigue gobernando? Onyx no puede decírtelo. Encontró un documento que coincide con tus palabras. Que ese documento sea el vigente es una pregunta que ninguna puntuación de similitud puede responder. Pruébalo: busca el tema del archivo contable sustituido incluido en los fixtures que conectaste en el Concepto 5 y observa qué versión aparece.
Un resultado de retrieval es un puntero, no una respuesta. Todo lo que aparece en las Partes 3 y 4 existe para convertir punteros en respuestas que defenderías.
Sé preciso sobre los elementos a los que se aplica. El conocimiento gobernado tiene un original al que volver, por lo que un resultado que lo encuentra es un puntero. El contexto de trabajo no lo tiene: no existe una versión canónica de lo que dijo un gerente el martes, y el correo recuperado es el elemento. Lo que mantiene honesto al contexto de trabajo son las otras dos preguntas: si esta persona puede verlo y si se transporta como evidencia en vez de como regla.
Terminado cuando: has buscado el tema del archivo contable sustituido y has visto qué versión apareció primero. Fuera cual fuera, ahora sabes que Onyx no la eligió por su vigencia.
8. Herencia de permisos y el límite de Community Edition
Este es el concepto más importante del curso y el que más se omite, porque omitirlo facilita todo durante unas seis semanas.
Las reglas de acceso de un documento viven en su sistema de origen. Un canal privado es privado. Una carpeta restringida es restringida. Cuando tu capa copia ese documento, debe copiar también las reglas de acceso y volver a comprobarlas en cada consulta para la persona concreta que pregunta. El permiso se hereda, nunca se inventa. El permiso viene antes que el modelo explica por qué se trata de una cuestión de control y no solo de privacidad.
Si te equivocas, habrás construido algo peor que una filtración: un sistema que resulta útil para filtrar información. Una persona júnior formula una pregunta razonable y recibe, en primer lugar y con un resumen amable, el memorando de compensación que nunca tuvo permiso para abrir. Nadie atacó nada. La capa simplemente hizo su trabajo con las reglas equivocadas.
Onyx Community Edition basta para aprender conectores, indexación, retrieval, citas, agentes y acciones. Por sí sola, no basta para demostrar fidelidad de permisos entre usuarios en producción.
La documentación de Onyx enumera los conectores con sincronización de permisos, que heredan permisos de usuario de sistemas externos, junto con los grupos de usuarios, RBAC y permisos basados en grupos, como funciones de Onyx Cloud y Enterprise Edition, no de Community Edition autoalojada. También menciona los despliegues que necesitan herencia de permisos desde sistemas externos como motivo para pasar a Enterprise.
Por tanto, en un laboratorio que use solo Community Edition, cada estudiante ve el mismo corpus. No puedes representar la demostración en la que un rol restringido pregunta y no recibe correctamente ningún resultado. Si tu cohorte usa durante la configuración la prueba de Onyx Cloud, sí puedes hacerlo, y merece la pena dedicar una semana a observar cómo una sincronización real de control de acceso realiza por sí sola el trabajo que estás a punto de hacer manualmente.
Este es el concepto en el que el producto comercial está claramente por delante, y conviene reconocerlo sin ponerse a la defensiva.
Glean lee la lista de control de acceso de cada sistema conectado junto con el contenido y aplica los permisos que ya existen en la fuente. Si no puedes abrir un archivo en Drive ni leer un canal de Slack, no aparece en tus resultados ni llega a una respuesta escrita para ti. Su Indexing API expone el mismo modelo para tu propio contenido, con permisos por usuario y grupo en cada documento y un endpoint checkdocumentaccess para verificarlos.
Así que en Glean configuras esto. En Onyx Community Edition lo construyes, y ese es el Concepto 9.
Construirlo una vez ofrece una educación mejor. Comprarlo suele ser una decisión de producción mejor. Saber cuál de esas dos frases se aplica a la situación que tienes delante es la habilidad real.
Hay tres formas de afrontarlo, y este curso elige la primera.
Aplica tú mismo la comprobación de permisos en tu propio límite. Escribes ese código y lo controlas por completo. Implementar una comprobación de acceso también enseña mucho más que configurar una. Este es el Concepto 9.
Lee el código de ee/. Está disponible para consulta aunque no tenga licencia MIT. Estudia cómo se implementa realmente la herencia de ACL desde una fuente real sin desplegarla.
Usa una prueba o una licencia durante un laboratorio. Una semana, una demostración y después vuelve a Community Edition.
De todo esto se desprende una regla que no admite negociación mientras aprendes.
Hasta que tu despliegue haya superado el conjunto de pruebas de permisos del Concepto 9, no conectes un corpus real. Ni el Drive de tu empresa, ni el de un cliente, ni tu propia bandeja de entrada. Una capa que nunca se ha probado con permisos no es un sistema parcial: es uno rápido, apuntado a las reglas equivocadas.
9. Construye la puerta y pruébala con un rol que no recibe nada
Como Community Edition no limita los documentos por usuario, construyes la puerta una capa más arriba, delante de retrieval. También es el lugar correcto en producción: en tu propio límite puedes demostrar qué ocurrió.
Una nota de honestidad antes de escribirla. Estás a punto de inventar los permisos de estos fixtures, justo lo contrario de la regla que acabas de aprender. Es una propiedad del laboratorio, no del diseño. Una carpeta local no transporta reglas de acceso que puedan heredarse, así que alguien debe declararlas; en un despliegue real, ese alguien es el sistema de origen. Aquí, tus etiquetas sustituyen una herencia que no puedes demostrar en Community Edition, y en governance/production-gates.md anotas que sigue pendiente.
La forma es sencilla y el orden lo es todo.
1. Resolve identity who is asking
2. Resolve permissions what may this identity see, per source
3. Filter eligible docs remove everything else, BEFORE retrieval
4. Retrieve and rank search only what remains
5. Assemble the answer with citations
6. Resolve action rights separately, at the tool boundary
El orden inseguro es el que parece natural: recuperar todo, entregárselo completo al modelo y después indicarle que no mencione lo que el lector no puede ver.
Un pasaje oculto dentro del contexto del modelo no está oculto.
Constrúyela:
governance/permission-matrix.csv ya incluye una fila por fuente. Es el archivo que aplica esta puerta y el que después entregas a una persona revisora.
Añade una capa de acceso delante de retrieval de Onyx. Define tres roles del lado de Northstar:
account_executive,sales_manageryvp_sales. Etiqueta cada fixture con el rol mínimo que puede leerlo. Los tres pueden leer la regla de autoridad de descuentos. Solosales_managery superiores pueden leer el hilo de aprobación de precios y el correo del gerente que dice «regístralo este trimestre». Después escribe una funciónsearch(query, role). Debe filtrar por rol el conjunto de documentos elegibles antes de llamar a Onyx, nunca después. Devuelve cada resultado con su fuente y el motivo por el que ese rol tenía permiso para verlo. Muéstrame la ruta de código donde ocurre el filtrado y demuestra que ningún documento no elegible llega al modelo.
Después, la prueba que importa más que cualquier benchmark de retrieval:
Construye un conjunto de pruebas de permisos: una fila por rol y pregunta, que registre qué puede ver ese rol en la fuente, qué devolvió la capa y si aprobó o falló. Incluye el caso importante de Northstar: pregunta qué dijo el gerente de ventas sobre registrarlo este trimestre como
account_executive, donde la respuesta correcta es absolutamente nada. Ejecuta la prueba y muéstrame la tabla.
Terminado cuando: los tres roles devuelven exactamente lo que pueden ver y el account_executive que pregunta por el correo del gerente no recibe nada. Una capa que nunca devuelve nada no se ha probado.
Observa qué protegió esa única prueba. El correo del gerente es el rumor sobre el que gira todo el caso Northstar. Un ejecutivo de cuenta que pueda recuperarlo puede citar la opinión de su propio gerente como si fuera una decisión de finanzas.
Después escribe dos cosas: qué es cierto hoy en el laboratorio y qué seguiría exigiendo producción.
Primero, governance/permission-matrix.csv. Una fila por fuente. Registra quién puede leerla, cómo se aplica el permiso y si está lista para producción:
source,student,teacher,production_employee,permission_mechanism,production_ready
Agent Factory SoR,read,read,read,public,yes
Sales fixture,read,read,not applicable,class-authorized,no
Accounting fixture,read,read,not applicable,class-authorized,no
Operational fixture,read,read,not applicable,synthetic MCP,no
Working context fixture,read,read,not applicable,synthetic files,no
Y governance/production-gates.md, la lista que entregas a una persona revisora de seguridad:
# Production permission gates
- [ ] Source permissions are synchronised or enforced before retrieval.
- [ ] Individual identity reaches live MCP and API tools.
- [ ] Search, chat, Agents, and external MCP clients enforce the same boundary.
- [ ] Revoked source access disappears within the accepted time window.
- [ ] A red-team test proves one user cannot retrieve another user's document.
- [ ] Connector credentials are encrypted and operationally protected.
La finalidad de escribir ambos documentos es que la limitación de Community Edition se convierta en una puerta explícitamente abierta y no en una suposición oculta. Esa distinción separa un laboratorio de una responsabilidad legal.
En la mayoría de los ámbitos, un fallo de permisos es un problema de privacidad. En una profesión regulada llega más lejos, y conviene ser preciso porque la versión imprecisa del argumento es incorrecta.
La segregación de funciones trata sobre combinaciones de capacidad, no de visibilidad: crear un asiento contable y también aprobarlo, originar una transacción y también conciliarla. Por sí solo, el acceso de lectura no suele ser una combinación de ese tipo, y afirmar que tu capa de contexto «rompe la segregación de funciones» hará que pierdas la discusión con una persona responsable de control.
La exposición real se encuentra una capa más abajo. El control de acceso es la base sobre la que se sostiene el resto del entorno de control. Por eso las personas auditoras tratan unos controles generales de TI débiles como motivo para dudar de los controles de aplicaciones que dependen de ellos. La revisión periódica de acceso de una firma certifica que una persona concreta posee un conjunto específico de derechos. Después, tu capa entrega a esa persona contenido que esos derechos nunca concedieron. No se robó nada, no se infringió formalmente ninguna regla documentada y ahora la revisión certifica una imagen que no es cierta.
Ese es el argumento que debes presentar; es exacto y más sólido. Una capa de contexto que concede acceso efectivo fuera del modelo de derechos no rompe un control. Invalida en silencio la revisión que certifica todos ellos.
Parte 3: La mitad gobernada
Buscar te da un puntero. No te da una respuesta.
En esta parte añades la segunda mitad. Tu propia base de datos Neon recibe una pequeña tabla gobernada de reglas, cada una con versión y fecha. Después la sirves como herramienta, para que un Worker pueda tomar una regla encontrada en el índice y preguntar al original: ¿sigue siendo esta la regla? Los números vivos, como si llegó una aprobación, se consultan de nuevo cada vez.
10. Sirve tu registro mediante MCP y el patrón de dos llamadas
Todo lo anterior ha sido la mitad de descubrimiento indexada. Ya incluye conocimiento gobernado, porque indexaste dos registros verticales y el propio libro. Pero todo llegó como una copia consultable, y una copia es un puntero.
Ahora llega la mitad canónica y viva, que se comporta de una forma completamente distinta.
Primero, da autoridad al registro
Tu proyecto Neon contiene documentos, fragmentos y embeddings. Todavía no contiene una regla que puedas citar ante una persona responsable de control, porque el curso anterior no necesitaba construirla. Añade junto a lo existente un pequeño esquema gobernado. Es el arranque del que depende el resto de esta parte:
La carpeta scripts/ de la base contiene el esquema necesario. Léelo antes de ejecutar el prompt, para aprobar algo que has visto.
En nuestro proyecto Neon existente, sobre una branch
dev, crea un esquemagovernedcon una tablarule. Columnas:stable_id,domain(sales o accounting),authority_class,jurisdiction,version,effective_from,effective_to,approval_status,superseded_by,ownerybody. Carga en ella las reglas de ventas y contabilidad de Northstar desdefixtures/, incluida la regla contable sustituida cuyo enlacesuperseded_byapunta a la vigente. Muéstrame las filas antes de confirmar la branch.
Nueve de esas columnas son los doce controles del Concepto 6, ahora reales en vez de descritos.
Ambas profesiones viven en una tabla, separadas por una columna domain. Eso mantiene sencillo el servidor de demostración y hace visible el trabajo de enrutamiento del Concepto 12, porque el Worker debe elegir un dominio antes de confirmar nada.
Después, sírvelo
La regla contable de Northstar dice que el ingreso por implementación se reconoce con la aceptación del cliente. Tiene versión y fecha de entrada en vigor, y en los fixtures existe un archivo sustituido que dice algo distinto. Todo este concepto existe para que un Worker cite la regla correcta.
Tu almacén del curso anterior ya funciona: un pequeño Postgres en Neon, con pgvector activado, tus documentos dentro y una branch dev sobre la que lo construiste. Nada de eso cambia aquí. Lo que cambia es quién llega hasta él.
No es una carpeta que deba rastrearse. Nunca apuntes un conector hacia él. Es una fuente a la que debes preguntar, igual que en la Parte 6 del curso anterior:
La carpeta mcp/vertical_sor/ de la base contiene un esqueleto FastMCP con estas tres herramientas esbozadas y las partes difíciles marcadas como TODO. Léelo primero y después pide a tu agente que lo complete.
Envuelve nuestro registro gobernado alojado en Neon en un servidor FastMCP llamado
vertical-sor. Cada herramienta recibe un argumentodomain, sales o accounting, para que un servidor demuestre ambas profesiones. Incluye tres herramientas de solo lectura; observa que el estado vivo del cliente no es una de ellas:
search_rules(domain, query)returns candidate rules with their stable IDsconfirm_rule(domain, stable_id)returns the full current entry with authority class, jurisdiction, version, effective period, approval status, and superseded-by linkvalidate_action(domain, action)checks a proposed action against that domain's rules and returns approved or refused with the blocking rule Use the pooled Neon connection string from the environment, connect with a read-only role, and serve over Streamable HTTP in stateless mode, meaning it keeps no MCP session between requests, so any request can be answered without the one before it. Show me the tool list and the docstrings before writing code.
Por qué un servidor y no dos. En producción, el registro de cada profesión puede ser un sistema separado y propiedad de otra parte; el argumento domain es donde aparecería esa separación. Para un curso intensivo, un servidor mantiene claro el recorrido. Existe exactamente un lugar donde puede confirmarse una regla de cualquiera de las dos profesiones. Las copias indexadas en Onyx son proyecciones: copias consultables que se conservan solo para que el Worker pueda encontrar el original. Cada fragmento proyectado mantiene su stable_id, domain y version, para que la llamada de confirmación tenga algo que consultar.
Comprueba dos detalles de Neon en el plan, porque ambos suelen funcionar en un laboratorio y causar problemas en producción. El servidor debe usar el connection string pooled, cuyo host termina en -pooler, porque una capa de contexto abre muchas conexiones breves y el endpoint directo no está diseñado para ello. Además, debe conectarse con un rol read-only, no con el propietario de las tablas. Así, ningún argumento de herramienta podrá cambiar el registro que debe citar.
Stateless HTTP es un argumento de ejecución en FastMCP, no del constructor. FastMCP("vertical-sor", stateless_http=True) era válido en FastMCP 2.x, pero produce TypeError en 3.x; además, 2.x es la forma que un modelo probablemente recordará. La forma actual es:
from fastmcp import FastMCP
mcp = FastMCP("vertical-sor")
if __name__ == "__main__":
mcp.run(transport="http", host="127.0.0.1", port=8101, stateless_http=True)
El servidor responde entonces en /mcp, no en el host sin ruta. Ese detalle cuesta una hora cuando un cliente no logra conectarse. Pide a tu agente que compruebe ambos puntos en la documentación actual de FastMCP antes de aprobar su plan.
Mantén también el hábito de las branches. Cuando cambies el esquema del registro durante este curso, hazlo en una branch de Neon y previsualízalo, igual que antes. Una branch también es la forma más barata de ejecutar la demostración de copia obsoleta que aparece más adelante. Bifurca el registro, deja que la bifurcación quede obsoleta a propósito, apunta discovery hacia ella y después elimina la branch.
Observa la lista de herramientas. search_rules y confirm_rule son dos llamadas donde un diseño ingenuo usaría una, y esa separación es el objetivo.
Discovery pregunta: ¿dónde podría existir información relevante? Optimiza recall, similitud y velocidad. Su salida es un puntero.
Confirmation pregunta: ¿qué fuente es oficialmente aplicable a esta decisión? Comprueba dominio, clase de autoridad, jurisdicción, versión, fecha de entrada en vigor y estado de aprobación. Su salida es una respuesta.
La secuencia queda fijada y nunca se ejecuta al revés:
search discovers → you route → the record confirms → the Worker cites
Puedes indexar páginas gobernadas para discovery, y hacerlo resulta útil. Un estudiante que no logra encontrar la regla está peor que quien encuentra una copia. Lo que nunca debe ocurrir es confiar en la copia. La doctrina es Discovery no es confirmación.
Ahora conecta las dos llamadas. Escribe
governing_rule(question), que llame asearch_rules, tome el ID estable del mejor candidato, llame aconfirm_ruley devuelva la entrada confirmada. Si la entrada confirmada está sustituida, sigue el enlace y confirma su sucesora. Después demuestra el fallo que evita mediante la regla central del caso: crea una branch de Neon de nuestro registro, cambia en la branch default la regla de ingresos por implementación de aceptación a facturación para que la otra branch quede obsoleta, apuntasearch_rulesa la branch obsoleta mientrasconfirm_rulepermanece en la vigente y pregunta cuándo pueden reconocerse los ingresos de Northstar. Muéstrame ambas respuestas una al lado de la otra. Elimina después la branch.
Terminado cuando: has visto a la branch obsoleta responder con seguridad al facturar y a la llamada de confirmación corregirlo a con la aceptación.
Una respuesta permite a Northstar registrar ingresos este trimestre y la otra no. Esa es toda la diferencia que este curso existe para enseñar. Esta demostración es lo más valioso del curso.
Aquí el producto no lo hace por ti, y esta es la nota más importante de la página.
Glean indexa y recupera de forma excelente, y sí transporta una señal de vigencia: un owner puede verificar una página; el resultado muestra entonces una insignia que indica quién la verificó y cuándo, y una página que ha dejado de ser válida puede marcarse como obsoleta. Es un recordatorio humano adjunto a un documento. No representa las clases de autoridad, jurisdicciones, periodos de vigencia ni enlaces de sustitución de tu profesión, porque son propiedades de tu registro gobernado, no de una plataforma de búsqueda. Por tanto, un despliegue de Glean puede devolver la regla sustituida con citas perfectas, fidelidad total de permisos y una insignia verde de verificación, y seguir equivocado.
La llamada de confirmación debes construirla tú con cualquiera de los dos productos. Los Agents de Glean pueden alcanzar tu herramienta confirm_rule mediante un servidor MCP remoto igual que un Agent de Onyx, aunque al escribir esto esa ruta está en beta y vive en el paso plan-and-execute de un agente en vez de una selección de un solo paso. Nada cambia en el diseño.
11. El estado vivo se consulta cada vez
Saldos, estado de aprobación, elementos abiertos, versiones actuales. Nada de ello fue redactado, nada es estable y todo es exacto. Si lo indexas, produces una copia aproximada y envejecida de aquello cuyo valor completo consiste en estar actualizado.
La regla cabe en una oración y pertenece al registro de diseño de cada proyecto:
Si un valor obsoleto pudiera cambiar la conclusión, el permiso, un pago, una presentación o una acción del cliente, consúltalo en vivo.
Estos son los tres modos de retrieval, la doctrina comprimida de toda la capa:
| Información | Cómo se alcanza |
|---|---|
| Contexto de trabajo | Indexación consciente de permisos |
| Conocimiento gobernado | Índice de discovery, confirmado antes de utilizarlo |
| Registros y acciones actuales | Consulta tipada en vivo mediante MCP o una API |
Indexa el contexto de trabajo. Descubre el conocimiento gobernado. Consulta en vivo la verdad actual.
Observa que una fuente suele necesitar dos modos. Un documento contractual se indexa para encontrar sus cláusulas. Después se consulta en vivo el sistema de contratos para confirmar que la versión encontrada sigue siendo la activa.
El formato y la longitud no deciden nada. El riesgo de obsolescencia lo decide todo.
Glean puede obtener datos recientes en el momento de la consulta para algunos sistemas conectados, en vez de depender únicamente de la copia indexada. Eso cubre automáticamente una parte.
Una parte no es todo. Qué campos son críticos por su vigencia en tu profesión es un juicio que ninguna plataforma puede hacer por ti, y es el que escribiste antes en tu registro de diseño. La regla de decisión te acompaña entre productos.
Sirve los dos registros operativos de Northstar mediante el servidor customer-state, separado de
vertical-sor:get_opportunitydevuelve el estado de aprobación yget_contract_statedevuelve el estado de aceptación. Mantenerlos separados materializa las cuatro clases de fuente, porque un registro vertical gobierna reglas y uno operativo posee el estado. Después pregunta ¿podemos reconocer el ingreso? dos veces: una respuesta desde una instantánea indexada y otra desde la llamada en vivo, cambiando entre ambas la aceptación de no recibida a recibida. Muéstrame las dos respuestas con sus marcas de tiempo.
Terminado cuando: la respuesta indexada y la respuesta en vivo no coinciden, y puedes indicar con precisión cuál pondrías ante una persona responsable de control.
Parte 4: Enrutar y citar
Una pregunta del cliente suele esconder varias preguntas profesionales.
Esta parte enseña al Worker a separarlas, enviar cada una al registro que la gobierna y etiquetar todo lo que obtiene. También enseña el hábito más difícil: cuando dos fuentes discrepen, muestra ambas. No las alises hasta formar una sola oración cómoda.
12. Enrutamiento de autoridad: qué registro gobierna esta pregunta
El trabajo profesional plantea muchas clases de preguntas: qué debe decidirse, qué acción está permitida, qué checker corresponde y qué evidencia falta. Pero para ensamblar contexto, la mayoría de las solicitudes de evidencia se reducen a tres formas, cada una con su propio recorrido.
| La pregunta | La fuente | El recorrido | Lo que devuelve |
|---|---|---|---|
| ¿Cuál es la regla? | Un Sistema de Registro | Discovery y después confirmation | Verdad gobernada, citada con clase, jurisdicción y versión |
| ¿Cuál es el número? | El sistema que lo posee | Consulta tipada | Un valor actual exacto, con marca de tiempo |
| ¿Qué se dijo sobre este caso? | Contexto de trabajo | Retrieval consciente de permisos | Evidencia, nunca la regla gobernante |
Un Worker que no distingue qué pregunta formula responderá las tres de la misma manera, y el tercer recorrido engullirá en silencio los dos primeros.
Hay un paso más, que aparece antes de todos ellos cuando un cliente utiliza más de un registro gobernado. Una firma mediana puede tener un registro contable, uno de ventas y uno de RR. HH., construidos por tres personas distintas y ninguno por ti. Por eso el enrutamiento resuelve primero qué profesión es dueña de esta pregunta y después qué fuente dentro de ella. Preguntar si puede reconocerse un ingreso es una pregunta contable, aunque todas sus palabras procedan de una conversación de ventas.
Escribe el mapa antes que el prompt
El modelo no debe inventar qué fuente gobierna a partir del fragmento que haya quedado primero. La tabla de enrutamiento es un artefacto versionado que escribes, revisas y conservas antes. governance/authority-map.yaml viene en la carpeta base con las rutas vacías. Complétalo:
version: 1
updated_at: 2026-07-31
routes:
shared_method:
questions: [architecture, Agent Factory doctrine, implementation method]
governing_source: AF-SOR-PUBLIC
sales.discount_authority:
questions: [requested discount, approval threshold, proposal permission]
governing_source: VERTICAL-SALES-SOR
confirm_with: vertical-sor.confirm_rule(domain=sales)
current_state_tool: customer-state.get_opportunity
accounting.implementation_revenue:
questions: [revenue recognition, implementation acceptance, quarter-end treatment]
governing_source: VERTICAL-ACCOUNTING-SOR
confirm_with: vertical-sor.confirm_rule(domain=accounting)
current_state_tool: customer-state.get_contract_state
rules:
- working_context may support what was said or requested, but never governs a professional conclusion
- indexed governed knowledge is discovered, then confirmed at the source before it is relied on
- current state must be confirmed live before any action
- conflicts are surfaced, never silently merged
- missing authority or evidence becomes an explicit gap
Cada nombre es uno que ya creaste: los conectores del Concepto 5 y las herramientas de los Conceptos 10 y 11. Es deliberado. Un mapa de enrutamiento cuyas fuentes no resuelven a nada que el sistema pueda llamar es un diagrama, no un router.
El archivo es sencillo porque su trabajo también lo es. Convierte una pregunta empresarial imprecisa en decisiones profesionales con nombre, cada una con una fuente gobernante nombrada. En producción, este mapa puede vivir en un registro gobernado o dentro de un Sistema de Registro Vertical. El curso usa YAML para que la decisión pueda inspeccionarse y versionarse desde la primera hora.
Construye una función
route(question)que leagovernance/authority-map.yaml, clasifique una pregunta en sus decisiones profesionales y nombre la fuente gobernante y la de estado actual para cada una. Devuelve la decisión de enrutamiento como datos estructurados con un motivo; no te limites a llamar una herramienta. Después ejecútala sobre la pregunta de Northstar y muéstrame la tabla de enrutamiento para que pueda comprobar su razonamiento, no solo sus respuestas.
Presta atención a esto: devolver la decisión en vez de actuar inmediatamente es lo que permite revisarla. Un router que solo produce respuestas no puede auditarse.
Terminado cuando: la pregunta de Northstar produce al menos dos decisiones enrutadas, una de ventas y otra contable, y cada una nombra su fuente gobernante antes de que ocurra cualquier retrieval.
13. Procedencia y el sobre de citas
Cada elemento material que devuelve la capa transporta un sobre: un conjunto de etiquetas que viaja con el texto e indica de dónde vino y si puedes confiar en él. Sin ese sobre, un paquete es un montón de texto. Con él, es evidencia revisable.
| Campo | Por qué importa |
|---|---|
| Sistema de origen | Identifica quién posee la información |
| ID estable | Permite que una persona revisora vuelva a obtener el elemento exacto |
| Clase de autoridad | Ley, estándar, contrato, política, transacción, guía, mensaje o ejemplo |
| Alcance | Qué pregunta, cliente, jurisdicción y caso gobierna |
| Versión y periodo de vigencia | Impide que reglas retiradas regresen en silencio |
| Recuperado o sincronizado en | Muestra la vigencia del elemento |
| Base del permiso | Muestra por qué este lector podía recibirlo |
Y la regla que mantiene honesta una respuesta fluida:
Un Worker puede leer cualquier contexto de apoyo permitido y relevante para la tarea. Nunca puede presentar ese contexto de apoyo como la regla que gobierna la respuesta.
Un correo puede citarse como evidencia de que un cliente pidió algo. Un papel de trabajo anterior puede citarse como evidencia de cómo trató la firma algo el año pasado. Ninguno de los dos es nunca el requisito.
El paquete es un contrato de salida
Un Agent de Onyx es un asistente configurado: instrucciones sobre su comportamiento, conocimiento que puede buscar y Actions, herramientas que puede llamar. Crea uno llamado Northstar Context Router.
Ahora llega una parte fácil de hacer mal y que desharía en silencio el Concepto 9.
El movimiento obvio consiste en adjuntar Northstar Cross-Domain directamente al Agent. Funciona de inmediato, pero también crea dos recorridos de retrieval, uno de los cuales rodea la puerta que acabas de construir:
SAFE user -> permission gate -> filtered Onyx search
BYPASS user -> Onyx Agent -> the whole attached Document Set
El conocimiento adjunto de un Agent se convierte en su alcance consultable. Si adjuntas el conjunto multidominio, el Agent puede leer cualquier elemento que contenga para cualquier persona, sin importar lo que diga tu puerta.
Por tanto, el Router no recibe conocimiento sensible al rol. Solo recibe Actions.
Dale exactamente cinco Actions y nada más:
| Action | Qué hace |
|---|---|
search_permitted_context(query) | Tu gateway. Resuelve el rol de quien llama a partir de la credencial que transporta la Action, aplica los Document Sets o etiquetas permitidos y después llama a la búsqueda de Onyx |
confirm_rule(domain, stable_id) | Confirmación canónica desde vertical-sor |
get_opportunity(id) | Estado vivo de la oportunidad, con marca de tiempo, desde el servidor customer-state |
get_contract_state(id) | Estado vivo del contrato, con marca de tiempo, desde el mismo servidor |
validate_action(domain, action) | Comprueba una propuesta contra las reglas gobernantes |
Construye una Action
search_permitted_contextque envuelva la API de búsqueda de Onyx. Lee el rol desde la credencial configurada para la Action, nunca desde un argumento de herramienta; deriva de ese rol los Document Sets y etiquetas permitidos, los aplica como filtros de búsqueda y solo entonces emite la consulta. Devuelve los resultados con el motivo por el que se permitió cada uno. Después crea el Northstar Context Router sin ningún Document Set adjunto, únicamente con esta Action y las cuatro herramientas MCP.
Importa dónde ejecutas la comparación de roles. Una Action transporta una credencial configurada y, por tanto, un rol; un único Router no puede formular la misma pregunta como dos personas distintas. Es una propiedad del cableado, no una carencia del diseño, y todos los hosts tienen la misma restricción. Demuestra la puerta en el gateway, que es donde realmente se resuelve la identidad:
Pide al gateway algo que solo
vp_salespueda ver: una vez con el token devp_salesy otra con el deaccount_executive, y muéstrame ambos resultados juntos. Después muéstrame al Router respondiendo la misma pregunta mediante la Action e indica con qué rol habla y cómo lo sabes.
La regla subyacente cabe en una oración y es la misma de antes, aplicada una capa más arriba:
Todo retrieval indexado pasa por el gateway. Si un componente puede buscar sin atravesarlo, la puerta es decorativa.
De forma predeterminada, un agente de Glean se ejecuta con la identidad de quien lo invocó, por lo que solo ve y hace lo que esa persona ya podía ver y hacer. El desvío que acabas de cerrar manualmente no surge de la misma forma. Glean también ofrece una identidad de agente, con la que el agente usa credenciales de servicio limitadas por una persona administradora en vez de tomar prestada la identidad del usuario. Observa su efecto: reduce el alcance de un agente desatendido a lo que se autorizó; no sirve para ampliarlo.
Dos cosas siguen siendo tuyas. El contrato de salida de siete secciones, porque una forma fija y revisable es una decisión de diseño que ningún producto impone. Y el enrutamiento de autoridad, porque decidir que una pregunta sobre ingresos pertenece a contabilidad y no a ventas es conocimiento profesional, no una función de plataforma.
Ahora proporciona al Router un archivo de instrucciones en prompts/context-router.md que termine con esta forma fija:
Return exactly these sections:
## Decisions involved
## Governing authority
## Current facts
## Supporting context
## Conflicts and gaps
## Permitted next steps
## Citations
Esas siete secciones son el paquete de contexto, y la forma fija hace más trabajo del que parece.
Onyx no tiene un objeto de base de datos llamado Context Packet. Lo implementas como un contrato de salida estable para una tarea. Como la forma nunca cambia, se derivan tres consecuencias. Una persona revisora puede recorrer cualquier respuesta en segundos. Un harness de evaluación puede comprobar cada sección por separado. Y una sección ausente resulta visible en vez de desaparecer en silencio. Una sección vacía de Conflicts and gaps significa que el router comprobó y no encontró ninguno. Si el encabezado no existe, significa que nunca lo buscó.
Además, el paquete es temporal a propósito. Los hechos actuales pueden cambiar. Los permisos del lector pueden cambiar. La versión aplicable puede ser sustituida. Por eso se reconstruye cada vez en lugar de almacenarse en caché.
Construye el ensamblador detrás de ese contrato. Dada una pregunta enrutada, reúne las reglas confirmadas, los valores vivos y el contexto de apoyo permitido, y completa cada sección con elementos que transporten todo su sobre, separando visualmente la verdad gobernada de la evidencia. Después muéstrame la misma respuesta dos veces: como objeto estructurado y como prosa que leería una persona.
Terminado cuando: todos los encabezados están presentes aunque su contenido esté vacío, y puedes señalar una afirmación y rastrearla hasta una fuente, una versión y una base de permiso.
El ensamblador trabaja con un presupuesto, porque las ventanas de contexto son finitas y cada token gastado en un mensaje obsoleto no se dedica a la regla gobernante. Por eso, seleccionar y comprimir es trabajo legítimo. También es donde se rompe con mayor frecuencia la regla de procedencia. Una compresión que elimina una marca de versión, mezcla dos fuentes en una oración o borra una clase de autoridad no ha ahorrado tokens: ha convertido evidencia en texto.
Comprime la prosa. Nunca comprimas la procedencia.
14. El conflicto es un resultado, no un fallo de retrieval
Esto separa un Sistema de Contexto de una buena herramienta de búsqueda. Una herramienta de búsqueda no tiene postura sobre el desacuerdo. Un sistema profesional debe tenerla.
Recuerda las incoherencias ya sembradas en los fixtures que conectaste en el Concepto 5. Ve a encontrarlas.
Un conflicto tiene exactamente tres resultados:
- Resuelto por alcance. Las fuentes responden preguntas distintas y ambas son correctas en la suya. Ventas dice que el acuerdo se cerró en junio; contabilidad dice que el ingreso no puede reconocerse hasta la aceptación; ninguna está equivocada.
- Resuelto por autoridad. Una fuente aplicable gobierna y la jerarquía indica cuál.
- Sin resolver. El Worker escala, con la evidencia conflictiva ya organizada.
Lo que nunca debe ocurrir es una cuarta opción, que es lo que hace de forma predeterminada un resumidor normal: mezclar las fuentes en una oración fluida que ninguna fuente dijo realmente.
Incorpora detección de conflictos en el ensamblador. Cuando dos elementos recuperados discrepen en un punto material, no los resumas juntos. Mantenlos separados con sus sobres intactos; decide si el conflicto se resuelve por alcance o autoridad y, si no es así, produce un escalamiento que indique qué fuentes discrepan, qué dice cada una, qué prueba de autoridad aplicaste y qué queda abierto. Después ejecútalo contra las incoherencias de
fixtures/PLANTED.mdy muéstrame si detectó cada una.
Terminado cuando: el sistema encuentra por sí solo el memorando sustituido y el mensaje de chat contradicho, y su escalamiento parece algo que podrías reenviar a un socio sin editar.
No hace desaparecer el desacuerdo. Lo vuelve revisable.
Ni Onyx ni Glean aplican automáticamente tu mapa de autoridad ni tus reglas de conflicto. Retrieval devuelve los pasajes coincidentes. Decidir si dos se contradicen y cuál gobierna es un juicio profesional que vive en tu mapa de autoridad y en las instrucciones del router.
En todo caso, un motor de retrieval más potente hace que esto sea más difícil de advertir, porque produce una respuesta más fluida y segura sobre el mismo desacuerdo.
Los tres resultados y el motivo por el que resuelto por alcance aparece primero están en El conflicto es un resultado, no un fallo de retrieval.
15. Actuar y registrar: cerrar el ciclo
Encontrar no es lo mismo que hacer, y entre ambos hay cinco trabajos distintos.
the layer finds → the Worker reasons → the governing record validates
→ the tool acts → the owning system records
Ese tercer paso es el que todo el mundo elimina.
Una aprobación de descuento se comprueba contra el registro de ventas antes de que el CRM la escriba. Un asiento contable se comprueba contra el registro contable antes de que el ERP conserve el borrador.
Así, el registro gobernante no es solo el lugar donde se leyó la regla. Es donde la acción propuesta se comprueba contra ella. Esa comprobación convierte una regla en algo real y no meramente consultivo.
De aquí se derivan dos reglas, ambas absolutas:
La capa de contexto nunca debe convertirse en un segundo sistema transaccional ni en una forma de escribir eludiendo un registro gobernado.
Leer, recomendar, preparar y ejecutar son concesiones distintas. Un Worker puede ser excelente en retrieval y no tener ninguna autoridad de ejecución. El acceso no es permiso.
Conecta la herramienta
validate_action(domain, action)del Router a la ruta de recomendación. Recibe una acción propuesta, la comprueba contra las reglas de ese dominio en el registro gobernado y devuelve un borrador aprobado o una negativa que nombre la regla bloqueante. Nunca debe ejecutar. Después muéstrame un caso en el que retrieval fuera correcto, el razonamiento fuera correcto y aun así la acción se rechazara.
Glean admite acciones con puntos de control human-in-the-loop, de modo que un paso puede requerir aprobación antes de ejecutarse, y las acciones respetan los permisos de la persona usuaria.
Eso cubre la mitad de aprobación. No cubre la de validación: comprobar una acción propuesta contra las reglas de tu profesión antes de pedir a nadie que la apruebe. validate_action es responsabilidad tuya en ambos productos, porque solo tu registro gobernado contiene la regla con la que se comprueba.
Terminado cuando: la recomendación de descuento es rechazada por la regla de aprobación del registro de ventas y la negativa nombra la regla, en lugar de decir que el modelo no estaba seguro.
Parte 5: El caso Northstar de principio a fin
Ahora construyes todo, en orden, y después lo rompes a propósito.
Romperlo no es un ejercicio adicional. Un sistema que falla de forma visible es seguro. Uno que falla en silencio con una respuesta errónea, fluida y segura es peligroso. Esta parte te muestra cómo se ve un fallo silencioso para que después puedas reconocerlo.
Este es todo el curso convertido en una construcción: desde una instancia vacía hasta una respuesta citada y correctamente rechazada.
El caso. El ejecutivo de cuenta solicitó un descuento del veinte por ciento. El CRM indica que la aprobación está pendiente. El contrato firmado permite facturar con la firma. El Sistema de Registro Contable reconoce los ingresos de implementación con la aceptación del cliente. El registro operativo del contrato indica que la aceptación no se ha recibido. Un correo del gerente de ventas dice que finanzas acepta registrarlo este trimestre.
La pregunta.
¿Puede Northstar recibir el descuento del veinte por ciento, ser facturado ahora y reconocer los ingresos de implementación este trimestre?
Paso 1. Planifica. Entra en plan mode con un modelo potente:
Construye la capa de contexto completa de Northstar: Onyx Standard con las cuatro clases de fuentes conectadas y separadas; un esquema
governeden nuestro proyecto Neon que contenga las reglas de ambos dominios; el servidor MCPvertical-sorcon herramientas de búsqueda, confirmación y validación, además de las herramientas de estado vivo; los cinco Document Sets;governance/authority-map.yaml; uncontext-gatewayque resuelva la identidad y aplique los conjuntos permitidos antes de cualquier búsqueda en Onyx; y el Context Router sin ningún Document Set adjunto, solo Actions. Muéstrame el plan, los límites de los componentes y la lista de herramientas antes de escribir código.
Paso 2. Lee el plan antes de aprobarlo. Hay seis comprobaciones, las mismas que este curso existe para que adviertas.
- ¿Se filtran los permisos antes de retrieval y no después?
- ¿Pasa cada recorrido de retrieval por el gateway, incluido el del propio Router? No debe haber un Document Set adjunto directamente al Agent ni un rol que llegue como argumento de herramienta.
- ¿Son discovery y confirmation dos llamadas separadas?
- ¿Se consulta el estado operativo en vivo, sin ninguna ruta que lo indexe?
- ¿El router conserva separados los elementos en conflicto en vez de resumirlos juntos?
- ¿Se alcanza el registro Neon mediante MCP, sin ningún conector cerca de él?
Si alguna respuesta es no, devuélvelo antes de que exista una línea de código.
Pasos 3 a 7. Ejecuta por puntos de control. Cambia a un modelo más económico para la construcción rutinaria.
Inicia Onyx Standard, conecta
AF-SOR-PUBLICy muéstrame una respuesta citada obtenida del libro.
Conecta los dos fixtures de Sistemas de Registro Verticales y el de contexto de trabajo como tres conectores separados. Muéstrame los recuentos de documentos y confirma que el JSON operativo no se conectó.
Crea el esquema
governeden Neon y carga las reglas de ambos dominios, incluida la regla contable sustituida. Iniciavertical-sory el servidor customer-state, y demuestra queconfirm_ruledevuelve algo quesearch_rulespor sí sola no devuelve.
Crea los cinco Document Sets, escribe
authority-map.yaml, construyecontext-gatewayy crea el Context Router sin conocimiento adjunto, únicamente con sus cinco Actions.
Ejecuta el conjunto de pruebas de permisos mediante el gateway, una fila por rol, incluida la pregunta cuya respuesta correcta para
account_executivees nada. Después ejecuta la misma pregunta directamente contra la búsqueda de Onyx para mostrar qué retiene el gateway, y una vez mediante el Router para confirmar que este llega a Onyx solo por esa ruta.
Paso 8. Formula la pregunta. Un paquete que aprueba hace cinco cosas: llama a ambas herramientas en vivo; cita ambos Sistemas de Registro Verticales después de confirmarlos; marca el correo del gerente solo como evidencia de apoyo; mantiene las decisiones de ventas y contabilidad en secciones separadas; y llega a dos negativas independientes en lugar de un sí mezclado.
Las dos negativas son estas: el descuento no puede aprobarse a ese nivel mientras la aprobación esté pendiente, y los ingresos no pueden reconocerse mientras falte la aceptación. Facturar con la firma sí está permitido, y decirlo con precisión forma parte de una respuesta que aprueba. Rechazarlo todo es tan incorrecto como aprobarlo todo.
Esto es aproximadamente lo que devuelve, abreviado. Tu redacción será distinta; su forma no debe serlo.
## Decisions involved
1. Sales: may an account executive grant 20 percent?
2. Accounting: may implementation revenue be recognised this quarter?
3. Contract: are the billing terms enforceable now?
## Governing authority
- SALES-DISC-001 v2, effective 2026-01-01, approved. Discounts above 15 percent
require VP Sales approval. [Vertical Sales SoR, confirmed 14:22]
- ACC-REV-001 v3, effective 2026-04-01, approved. Implementation revenue is
recognised at customer acceptance. [Vertical Accounting SoR, confirmed 14:22]
Supersedes ACC-REV-002, which said billing. Not applied.
## Current facts
- Opportunity NS-4471: discount 20 percent, approval PENDING. [CRM, read 14:22]
- Contract NS-2026-11: signed, acceptance NOT RECEIVED. [Contract system, read 14:22]
## Supporting context
- Email, sales manager, 2026-07-28: "finance is fine with booking it this quarter."
Evidence of what was said. Not authority. [Working context, permitted: vp_sales]
## Conflicts and gaps
- The email asserts a finance position no governed accounting source supports.
Unresolved by authority: escalate. Nothing in the corpus records a finance decision.
## Permitted next steps
- Route the 20 percent discount to VP Sales for approval.
- Bill at signature. Permitted by the signed contract.
- Do not recognise implementation revenue until acceptance is recorded.
## Citations
- SALES-DISC-001 v2 · ACC-REV-001 v3 · NS-4471 · NS-2026-11 · email 2026-07-28
Lee lo que hace la forma. Cada afirmación gobernada lleva versión y hora de confirmación. La regla sustituida se nombra y se marca explícitamente como no aplicada, en lugar de estar ausente en silencio. El correo aparece etiquetado en su propia sección y vuelve a aparecer en Conflicts and gaps porque afirma algo que ninguna fuente gobernada respalda. Además, los tres veredictos se mantienen separados: una negativa, un permiso y otra negativa.
Paso 9. Rómpelo a propósito. Hay cinco pruebas de fallo; el comportamiento esperado es la lección real:
| Prueba | Comportamiento esperado |
|---|---|
| Editar el correo para afirmar que el descuento fue aprobado, mientras el CRM sigue pendiente | Muestra un conflicto y conserva el CRM como estado operativo actual |
Apuntar search_rules a la branch obsoleta de Neon | Confirmation lo corrige y la respuesta obsoleta queda visiblemente equivocada |
| Detener el servidor MCP customer-state | Indica que el estado actual no puede confirmarse y rechaza una conclusión sobre estado actual |
| Eliminar las reglas de ventas del alcance permitido del gateway | Nombra la autoridad gobernante ausente en vez de sustituirla por el correo del gerente |
| Adjuntar directamente al Router el Document Set multidominio | La puerta queda eludida y un rol restringido ve contenido restringido. Desconéctalo y observa cómo vuelve la respuesta correcta |
Terminado cuando: has visto una respuesta segura, fluida, bien citada y completamente incorrecta producida por un sistema que omitió una llamada de confirmación. Nadie lo olvida.
Paso 10. Guarda la línea base. Ejecuta todos los casos de evals/questions.yaml y guarda las respuestas sin procesar, las citas, la evidencia de llamadas a herramientas, el aprobado o fallo por dimensión, la limitación conocida de permisos de Community Edition y las versiones exactas de Onyx y del modelo.
Parte 6: Demuéstralo
Tu curso anterior formuló una pregunta de prueba: ¿encontró la búsqueda el texto correcto?
Eso no basta aquí. Esta capa falla de formas que una prueba de búsqueda no puede ver. Puede encontrar el pasaje correcto de la regla del año pasado. Puede mostrar a una persona algo que no debería ver. Puede responder desde una copia antigua de un número. Por eso pruebas ocho cosas diferentes, y cada fallo debe nombrar qué parte se rompió.
Tu conjunto de evaluación de RAG formulaba una pregunta: ¿devolvió retrieval los fragmentos correctos? La mayoría de los fallos de una capa de contexto no son fallos de retrieval, así que necesita otro conjunto y otro cuadro de puntuación.
evals/questions.yaml incluye diez casos ya escritos. Ábrelo y lee estos seis con atención, porque cada uno prueba una etapa diferente:
version: 1
cases:
- id: inventory-01
question: What sources contain Northstar discount information?
expected:
must_find: [Sales SoR, CRM, draft proposal]
must_not_treat_as_authority: [draft proposal]
- id: sales-01
question: Can the account executive approve a 20 percent discount?
expected:
governing_source: Sales SoR
live_tool: get_opportunity
conclusion: no, VP Sales approval is required and remains pending
- id: accounting-01
question: Can implementation revenue be recognised this quarter?
expected:
governing_source: Accounting SoR
live_tool: get_contract_state
conclusion: no, acceptance has not been received
- id: stale-01
question: When is implementation revenue recognised?
expected:
prefers_current_version: true
flags_superseded: true
- id: conflict-01
question: Finance should be fine with booking it, right?
expected:
working_context_is_not_authority: true
conflict_visible: true
- id: gap-01
question: Which executive approved the discount?
expected:
answer: not established
no_guess: true
Puntúa cada ejecución en ocho dimensiones, nunca por lo bien que suene la prosa:
| Dimensión | La pregunta para aprobar |
|---|---|
| Inventario | ¿Encontró todas las clases de fuentes relevantes para la tarea? |
| Enrutamiento | ¿Identificó cada decisión profesional y su dominio? |
| Autoridad | ¿Se apoyó en la fuente gobernante correcta, confirmada en el origen? |
| Vigencia | ¿Llamó a la herramienta en vivo cuando importaba el estado actual? |
| Permiso | ¿Permaneció dentro del corpus y la autoridad de acción permitidos para la persona usuaria? |
| Conflicto | ¿Mostró el desacuerdo en vez de mezclarlo? |
| Brechas | ¿Indicó qué faltaba en vez de adivinar? |
| Cita | ¿Puede una persona revisora volver a abrir cada regla y elemento de apoyo? |
Ejecuta manualmente la primera línea base mediante el Agent y guarda las salidas. Después automatiza:
Construye un harness de evaluación contra nuestra instancia de Onyx en ejecución mediante la API oficial actual. Lee
evals/questions.yaml, envía cada pregunta al Northstar Context Router, guarda la respuesta sin procesar, las citas y la evidencia de llamadas a herramientas, y después produce un cuadro de puntuación Markdown para las ocho dimensiones. Usa comprobaciones deterministas siempre que sea posible. No califiques automáticamente la corrección profesional con el mismo modelo que respondió. Conserva las comprobaciones de autoridad y conclusión como comparaciones explícitas con los valores esperados.
Esa última instrucción es la que debes defender. Un modelo que juzga a otro puede ayudar a resumir fallos. Nunca debe sustituir en silencio las reglas y los hechos esperados que tú escribiste.
Definición de terminado: el caso multidominio aprueba todas las dimensiones excepto la fidelidad de permisos en producción, que sigue siendo una puerta explícitamente abierta.
Parte 7: Servir a toda la fuerza laboral y operar la capa
Una capa que solo funciona dentro de una ventana de chat no está terminada.
El último paso de construcción la abre para que otras herramientas que ya usan tus colegas alcancen el mismo corpus, con las mismas reglas sobre quién ve qué. Después viene la parte que nadie documenta: qué hace falta para mantenerlo funcionando cuando personas reales dependen de ello.
Hasta ahora, las personas y los Agents de Onyx han usado el corpus dentro de la interfaz de Onyx. La arquitectura solo se convierte en lo que promete su nombre cuando Workers externos consultan el mismo corpus en vez de construir copias privadas.
Onyx funciona en ambas direcciones, y esta es la parte a la que la mayoría de las construcciones nunca llega:
Hay dos formas de hacerlo, y solo una conserva tu límite de permisos.
El servidor MCP nativo de Onyx es la ruta rápida. Actívalo en tu configuración autoalojada, genera un token y apunta un cliente hacia él. Su herramienta de búsqueda recibe una consulta y filtros por tipo de fuente, nombre de Document Set y límite temporal; un recurso asociado enumera los conjuntos que ese token puede alcanzar.
Lee esa lista con cuidado, porque transmite justo lo contrario de tranquilidad. El filtro de Document Set existe, pero lo elige el cliente. Nada en el servidor deriva el alcance del rol de quien llama, así que un cliente que puede nombrar su propio alcance puede nombrar otro distinto o no indicar ninguno.
Por tanto, un Worker conectado directamente al MCP nativo de Onyx busca fuera de tu puerta. En Community Edition, sin herencia de permisos de origen por debajo, eso significa que busca en todo.
Usa el endpoint MCP nativo de Onyx para lo que realmente es: una herramienta de administración, una demostración sobre un corpus público o una ruta de producción, pero únicamente después de demostrar la fidelidad de permisos mediante un despliegue Enterprise o una capa de autorización propia equivalente.
No describas el acceso MCP directo de Community Edition como si transportara el mismo límite de permisos de usuario. No lo hace.
El servidor Context Gateway MCP es la ruta que mantiene el límite. Es el mismo gateway que construiste antes, ahora expuesto hacia fuera:
Claude Code · OpenCode · your Digital FTE
|
Context Gateway MCP
resolves identity
applies permitted sets and tags
routes authority, confirms, fetches live
|
Onyx
Envuelve nuestro gateway como un servidor MCP propio llamado
context-gateway. Expónsearch_permitted_context,confirm_rule,get_opportunity,get_contract_stateyvalidate_action, para que un Worker externo nunca necesite llegar a otro servidor. Sírvelo mediante Streamable HTTP.Para la identidad, usa bearer tokens asignados en el servidor a roles. Emite un token por rol, coloca la asignación en el entorno del servidor y lee el rol desde el token en cada solicitud. Un rol nunca debe llegar como argumento de herramienta.
En concreto, la asignación consiste en tres líneas de configuración y todo el límite de permisos depende de ella:
ACCOUNT_EXECUTIVE_TOKEN -> account_executive
SALES_MANAGER_TOKEN -> sales_manager
VP_SALES_TOKEN -> vp_sales
El cliente proporciona un bearer token en el transporte MCP. El servidor asigna ese token a un rol. El cliente nunca nombra su propio rol, porque un cliente que puede hacerlo no tiene límite alguno.
Todo lo anterior ha funcionado sobre http:// porque se ejecutaba en tu máquina. En cuanto el gateway sea accesible desde otro lugar, ese bearer token es todo el límite de permisos y viaja como texto sin cifrar. Coloca TLS delante, emite un token por persona en vez de uno por rol y asigna caducidad a los tokens. Un token con forma de rol que nunca caduca es una contraseña compartida con un cargo profesional.
Un servidor HTTP FastMCP responde en /mcp salvo que cambies la ruta, así que registra esa dirección y no el host sin ruta. Conéctalo igual que cualquier servidor MCP HTTP:
claude mcp add --transport http context-gateway http://YOUR_GATEWAY_HOST:8102/mcp \
--header "Authorization: Bearer $ACCOUNT_EXECUTIVE_TOKEN"
Añade un bloque remoto a opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"context-gateway": {
"type": "remote",
"url": "http://YOUR_GATEWAY_HOST:8102/mcp",
"headers": { "Authorization": "Bearer {env:ACCOUNT_EXECUTIVE_TOKEN}" },
"enabled": true
}
}
}
Nunca confirmes el token en git. OpenCode sustituye variables de entorno con {env:NAME}, de modo que el token permanece en tu shell y solo su nombre aparece en el archivo. Después, desde fuera de Onyx:
Usa el servidor MCP
context-gatewaypara encontrar la regla que gobierna un descuento del veinte por ciento para Northstar. Devuelve el título de la fuente, el enlace canónico, la versión confirmada y el pasaje exacto. No respondas desde tu propia memoria.
Ejecuta otra pregunta que necesite ventas y contabilidad. El Worker externo puede hacer varias búsquedas y ensamblar su propio paquete; los clientes variarán. Esa variación no es lo importante.
Después ejecuta la prueba esencial: formula la misma pregunta mediante el gateway como account_executive y como vp_sales, y confirma que los dos Workers reciben resultados distintos. Si no es así, tu gateway resuelve la identidad desde algo que controla el cliente y has construido un límite de permisos que cualquier cliente puede cruzar.
Esta es la respuesta más sólida de Glean al problema de esta parte. Su servidor MCP nunca elude el modelo nativo de identidad y permisos. Actúa como adaptador de protocolo: autentica a la persona usuaria final, asigna esa identidad a una persona usuaria de Glean y ejecuta cada llamada como esa persona, de modo que cada búsqueda, chat y llamada de documento se comprueba con permisos igual que si se hubiera ejecutado dentro de Glean. Las personas administradoras eligen qué herramientas expone cada servidor.
Ese es el límite que tu context-gateway reproduce manualmente. Constrúyelo una vez de todos modos, porque el día que la plataforma de un cliente no lo ofrezca sabrás exactamente qué falta y qué se necesita para proporcionarlo.
Una capa de contexto no está completa porque una interfaz de chat pueda buscar en ella. Está completa cuando cada persona y Worker de IA autorizado alcanza el mismo inventario gobernado desde su propia superficie de trabajo, con la misma identidad de origen y el mismo límite de permisos.
Esa es la diferencia entre una aplicación e infraestructura compartida. Es el momento en que tu capa deja de ser una función del producto y se convierte en algo sobre lo que funciona la empresa.
Operarla
Una capa de contexto cambia a diario porque los sistemas que la rodean cambian a diario. El trabajo de producción no consiste en «desplegar una vez». Consiste en salud de conectores, fidelidad de permisos, vigencia, medición y actualizaciones controladas.
Operaciones de conectores
Registra nueve cosas para cada conector: owner, clase de fuente, propietario de las credenciales, frecuencia de actualización y depuración, momento en que comenzó la indexación, recuento esperado de documentos, última sincronización correcta, obsolescencia aceptable y ruta de escalamiento.
Onyx muestra los conectores como indexed, scheduled, indexing, paused o in error, y conserva el historial de intentos. Esta es la trampa: un conector con error no elimina necesariamente el contenido ya indexado. Es excelente para la disponibilidad y peligroso para la vigencia, porque la búsqueda sigue funcionando mientras el corpus queda obsoleto en silencio. Tus alertas deben distinguir entre la búsqueda sigue funcionando y el corpus está actualizado. No son la misma alarma.
Disciplina de versiones y actualizaciones
El instalador puede actualizar un despliegue existente. Nunca trates una actualización de un comando como una actualización sin revisión. Sigue ocho pasos, en orden:
- Registra la versión actual.
- Lee las notas de versión.
- Haz copias de seguridad de los volúmenes persistentes y la configuración.
- Exporta la configuración de conectores, modelos, Agents, Actions y permisos.
- Ejecuta la línea base de evaluación.
- Actualiza primero una instancia que no sea de producción.
- Vuelve a ejecutar las mismas evaluaciones.
- Compara recuentos de conectores, citas, llamadas a herramientas y latencia.
Cambios de embeddings e índices
Cambiar el embedding model exige reindexar. Trátalo exactamente como una migración de esquema. Clona el despliegue cuando sea posible. Indexa un corpus representativo. Ejecuta las evaluaciones de autoridad y retrieval. Compara recall, calidad de citas, latencia, coste y almacenamiento. Aprueba solo una mejora medida.
Planificación de recursos
Para un laboratorio local, el objetivo mínimo útil de Standard son 4 CPU virtuales y 10 GB de RAM; se prefieren 8 CPU y 16 GB o más. El dimensionamiento de producción depende principalmente del volumen indexado, la concurrencia de consultas, las opciones de embeddings y reranking y la carga de actualización. Supervisa de cerca el disco, porque el índice de búsqueda puede bloquear escrituras cerca de los umbrales de saturación.
La definición de terminado en producción
La capa está lista para datos empresariales reales únicamente cuando se cumplen todas estas condiciones:
- Cada fuente está clasificada como método compartido, autoridad vertical, estado operativo o contexto de trabajo.
- Cada conector tiene owner, fuente canónica, expectativa de actualización y alerta de fallo.
- El enrutamiento de autoridad está versionado y revisado por expertos del dominio.
- El conocimiento gobernado se confirma en su fuente antes de utilizarse.
- Los hechos operativos actuales se confirman en vivo cuando es necesario.
- Los permisos de origen se sincronizan o aplican antes de retrieval.
- Las acciones MCP y API conservan la identidad individual y el privilegio mínimo.
- Los conflictos y la evidencia ausente permanecen visibles.
- Las citas vuelven a abrir la fuente o el registro canónico.
- Las evaluaciones multidominio aprueban en cada versión.
- Se han probado las copias de seguridad y la restauración.
- Existe una ruta de rollback para actualizaciones y cambios de retrieval.
- El Sistema de Contexto no puede escribir eludiendo el Sistema de Registro aplicable.
El puente hacia un Digital FTE
Ahora tienes dos mitades de lo mismo. El curso anterior dio a un Worker conocimiento propio. Este curso le dio acceso al conocimiento que posee la empresa, con permiso, procedencia y confirmación adjuntos.
Un Digital FTE aparece cuando rodeas ese Worker con un contrato de éxito y lo apuntas a un resultado. Su retrieval es lo que construiste aquí. Su autoridad es lo que dice tu registro gobernado. Su fiabilidad no es una propiedad del modelo.
Adónde ir después
- El argumento detrás de esta construcción: El Sistema de Contexto
- El registro al que se conecta esta capa: Diseñar el Sistema de Registro Vertical
- Hazlo fiable: Desarrollo guiado por evaluaciones
- Conviértelo en una unidad de trabajo: Construir un Digital FTE
- Ponlo junto a las personas: Equipos humano-agente
Las ocho reglas, en un solo lugar
Ahora has construido todas estas reglas. Se mantienen para cualquier profesión, cliente y producto, incluidos los que todavía no existen.
| # | La regla |
|---|---|
| 1 | La autoridad nunca se mueve. La capa transporta citas hacia el registro. Ni ella ni el modelo se convierten jamás en la fuente citada |
| 2 | La relevancia no es autoridad. El enrutamiento se resuelve antes de confiar en cualquier pasaje |
| 3 | El permiso se hereda, nunca se inventa, y se aplica antes del modelo |
| 4 | La vigencia se decide por campo. Indexa el contexto de trabajo, descubre conocimiento gobernado y consulta en vivo la verdad actual |
| 5 | La procedencia viaja con cada elemento, y la compresión nunca la elimina |
| 6 | El conflicto se conserva y escala, nunca se mezcla |
| 7 | El contexto de trabajo nunca se convierte en silencio en autoridad gobernante. La promoción es autoría, revisada y registrada |
| 8 | Discovery no es confirmation. Un resultado de búsqueda es un puntero y el registro gobernante confirma |
Imprime esta tabla. Es la parte del curso que sobrevivirá a Onyx, Glean y aquello que sustituya a ambos.
El hilo conductor nunca cambia; solo se vuelve más estricto. El curso anterior decía: información correcta, momento correcto y fuera la información irrelevante. Este añade las tres preguntas que lo hacen defendible.
¿De dónde vino? ¿Puede verla esta persona? ¿Sigue gobernando?
Responde las tres sobre cada elemento, cada vez, y habrás construido algo que una profesión puede respaldar.