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, una Card o una Nota, con su procedencia preservada y su estatus como evidencia externa (no Knowledge) mantenido explícito.Cuándo usarlo
- Un Record o una Card 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
| Ítem | Estado |
|---|---|
Interruptor maestro del Broker (DRIFTLESS_BROKER_ENABLED) | Gated, apagado por defecto en producción |
Lane externa (DRIFTLESS_BROKER_ROLLOUT) | Gated, apagada por defecto |
Lecturas de Notion (records, page-content, index, import) | Beta, read-only |
Escrituras del Broker (invoke de una op de escritura) en producción | Not available |
Objetos involucrados
| Objeto | Rol en este workflow |
|---|---|
| Connection | Un link autorizado a un proveedor; el Broker lo opera. |
| Capability | Una cosa que una Connection puede hacer; solo una ready es utilizable. |
| Operation | Una lectura o escritura con nombre que el Broker puede invoke o inspect. |
| Connector document | Contenido de página materializado en un objeto propio de Driftless con una cita. |
| Record / Card / Nota | Donde aterriza la evidencia externa. |
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”.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: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)
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.Inspecciona la operación que piensas correr
Lee la spec completa antes de llamar nada: input schema, efecto (
read / write), riesgo, idempotencia y criterion.Elige la lectura correcta
Las lecturas difieren en si tocan al proveedor en vivo y en qué, si algo, crean en Driftless. Elige deliberadamente:
| Lectura | ¿Toca al proveedor en vivo? | Crea en Driftless |
|---|---|---|
records | No, lee el mirror/cache | Nada |
page-content | Sí | Nada |
index | Sí | connector documents |
import | No, lee el mirror | Records de Collection |
retrieve de contexto | No, nunca consulta un proveedor | Nada |
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.Camino de escritura conceptual (gated)
Una escritura seguiría la misma forma gobernada, y vale entenderla aunque no sea invocable en producción hoy: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
| Momento | Qué deberías ver |
|---|---|
broker connections vacío | Ambiguo: sin rollout, o sin grant, no “nada conectado”. |
| Una capability utilizable | Status ready en broker capabilities. |
broker records | Filas desde el mirror, paginadas por cursor. |
broker page | El texto acotado y citable de una página, leído en vivo. |
| Un intento de escritura en producción | Rechazado: ninguna operación de escritura es invocable. |
Knowledge write-back
La evidencia externa actualiza el estado operacional; no se vuelve Knowledge al entrar:- Un valor actual va en el Record o la Card, 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.
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
retrievetraiga 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.
- No asumas que el GitHub App puede
invoke. Observa; una GitHub Broker Connection para escrituras no está shipped.
Troubleshooting
broker connectionsestá 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
gatedodisabled. Está registrada pero retenida por rollout, un grant faltante o un toggle. No es utilizable hasta que llega aready. - 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
| Capacidad | Estado |
|---|---|
Lecturas de Notion (records, page-content, index, import, retrieve tras index) | Beta, read-only |
Escrituras del Broker (invoke de una op de escritura) en producción | Not available |
| Connection y lecturas de HubSpot | Internal (gated) |
| Google Drive, Google Docs | Stub (not available) |
| GitHub App (observación de PR y push) | Available (superficie aparte) |
| GitHub Broker Connection (escrituras) | Not available |
Referencia relacionada
- Integraciones y Connections - setup, la cadena de conectado-a-utilizable y disponibilidad por proveedor.
- Broker - acciones, gates y semántica de lectura/escritura.
- Conector de Notion - el único conector de producción de punta a punta.
- CLI: Integraciones y Broker - la superficie de comandos.
- Operar una Collection - donde aterrizan los records importados y la evidencia citada.