Skip to main content
A veces la evidencia que necesita un record vive en una herramienta que Driftless no posee: una página de Notion, un record en otro sistema. El Broker es cómo una Collection alcanza esa evidencia mediante una Connection gobernada y auditada, la lee y la aterriza en la primitiva correcta, sin nunca tratarla como Knowledge ni como un retrieve normal de contexto. Esta guía te da un camino read-only ejecutable y un camino de escritura conceptual claramente marcado, porque las escrituras no están disponibles de forma general hoy.
El Broker está gated. Está apagado por defecto en producción (DRIFTLESS_BROKER_ENABLED), la lane externa OAuth/MCP es un interruptor aparte (DRIFTLESS_BROKER_ROLLOUT), y los callers externos además necesitan un grant por principal. El único conector de producción es Notion, Beta y read-only. Ninguna operación de escritura es invocable en producción (el registry de política de operaciones va vacío).

​
Resultado

Un hecho externo específico tirado hacia el objeto que lo necesita: el contenido de una página de Notion leído en vivo y escrito en un Record o una Nota, con su procedencia preservada y su estatus como evidencia externa (no Knowledge) mantenido explícito.

​
Cuándo usarlo

  • Un Record tiene una brecha de información concreta, y la respuesta vive en una herramienta externa conectada.
  • Ya confirmaste que el hecho no está en Driftless (ningún Topic, ningún Record existente, ningún connector document lo cubre).
  • Quieres la evidencia en estado operacional, citada, no promovida en silencio al Knowledge del equipo.

​
Disponibilidad y prerrequisitos

El setup (conectar un proveedor) ocurre en el dashboard o la CLI, nunca por MCP, y es un flujo privilegiado liderado por un humano. Un caller externo OAuth/MCP además necesita el rollout abierto y un grant que coincida; un caller interno (una API key propia o una sesión de dashboard) se salta el gate de grant pero igual necesita el resto.

​
Objetos involucrados

​
Antes de empezar

Comprueba si la superficie del Broker es siquiera alcanzable para ti. Una lista vacía es ambigua: puede significar “sin rollout” o “sin grant”, no “nada conectado”.
Si esto no devuelve nada, detente y resuelve el gate (rollout o grant) antes de asumir que el proveedor está desconectado. Una Connection saludable muestra el status synced.

​
Context preflight

El trabajo externo igual empieza con el contexto del equipo. Lee el Knowledge del objeto de trabajo antes de salir a buscar más:
Una Connection también puede llevar su propio criterion: slugs de topics de Knowledge adjuntos con broker criterion <provider> --add <slug>. El Broker nunca lee el contenido del topic; apunta al slug, y tú lo lees con tus tools de contexto antes de una operación riesgosa. Solo después de que este contexto confirme una brecha real y específica sales afuera. No tires el proveedor entero; trae el único hecho que el trabajo necesita.

​
Workflow paso a paso

​
Camino read-only (ejecutable)

1

Confirma que la capability está ready

Una capability registrada no es una utilizable. Lee el capability directory y usa solo una capability cuyo status sea ready.
gated y disabled son los estados que más fácil se confunden con disponible: la capability es real pero el entorno o tus grants la mantienen cerrada.
2

Inspecciona la operación que piensas correr

Lee la spec completa antes de llamar nada: input schema, efecto (read / write), riesgo, idempotencia y criterion.
3

Elige la lectura correcta

Las lecturas difieren en si tocan al proveedor en vivo y en qué, si algo, crean en Driftless. Elige deliberadamente:
records devuelve un modelo sincronizado desde el mirror; page-content lee una página en vivo y acotada, con una cita. El retrieve de contexto normal nunca consulta un proveedor, así que no es cómo alcanzas data externa fresca.
4

Aterriza la evidencia en la primitiva correcta

Escribe lo que encontraste en estado operacional, no en Knowledge: un field del Record o una Nota independiente citada a su fuente.

​
Camino de escritura conceptual (gated)

Una escritura seguiría la misma forma gobernada, y vale entenderla aunque no sea invocable en producción hoy:
La forma completa: inspect de la operación, lee su criterion, confirma que el grant la cubre, pasa una idempotency key para que un reintento sea un replay manual seguro, invoke (la ejecución es inline, no hay cola de aprobación), lee el correlation id devuelto desde el ledger de auditoría, y recuerda que las escrituras nunca hacen auto-retry. Después de correr, verifica el resultado contra el proveedor. Nada de esto está disponible en producción mientras el registry de política de operaciones va vacío; trata el bloque de arriba como ilustrativo, no como una llamada viva.

​
Estados esperados

​
Knowledge write-back

La evidencia externa actualiza el estado operacional; no se vuelve Knowledge al entrar:
  • Un valor actual va en el Record, citado a la fuente.
  • Una identidad compartida descubierta afuera se vuelve o actualiza una Entity.
  • Una observación que vale conservar se vuelve una Nota, no un Topic, salvo que una persona la revise después.
  • La procedencia se preserva solo hasta donde la superficie lo soporta: un connector document lleva una cita, procedencia y frescura y se lee como trust: "external"; para una lectura cruda, cita tú el page id o record id en la Nota.
Un snapshot de proveedor es evidencia externa, nunca verdad institucional. Se queda como estado operacional o Nota citada. No lo integres en Knowledge porque vino de una herramienta que se ve confiable.

​
Qué no hacer

  • No confundas conectado con utilizable. Una Connection OAuth saludable es el primer peldaño; la capability debe estar ready, el rollout abierto y un grant presente.
  • No trates la data externa como Knowledge. Los connector documents son opt-in en el retrieve, llevan trust: "external" y nunca son Knowledge.
  • No esperes que retrieve traiga data externa en vivo. Lee solo tablas propias de Driftless (Topics y connector documents), nunca un proveedor.
  • No escribas ni despliegues una operación que el Broker no lista. Reporta la capability faltante; nunca escribas un script para llenar la brecha.

​
Troubleshooting

  • broker connections está vacío contra una connection saludable. La lane externa está cerrada (rollout: off) o ningún grant coincide con tu principal. Los grants los gestiona owner/admin; un caller interno se salta el gate de grant.
  • Una capability muestra gated o disabled. Está registrada pero retenida por rollout, un grant faltante o un toggle. No es utilizable hasta que llega a ready.
  • Una lectura devuelve vacío en vez de un error. Por diseño: cuando la lane está cerrada o ningún grant coincide, las lecturas devuelven un resultado vacío, así que trata el vacío como “revisa los gates”, no “sin data”.

​
Límites y truth states

​
Referencia relacionada