Saltar al contenido principal

Conectores Personalizados

Beak AI incluye conectores para una extensa lista de plataformas empresariales (consulte Fuentes de Datos del Sistema). Esta página cubre la otra mitad: conectar una aplicación que no está en esa lista, sin esperar a un nuevo lanzamiento del producto.

Un conector se describe ahora mediante un manifiesto — una definición única que indica cómo autenticarse, qué campos de conexión mostrar y qué colecciones de registros pueden ingerirse. Registre un manifiesto y el conector aparece de inmediato en el selector de conectores de Studio.

Antes de comenzar​

Necesita:

  • URL base de la API — el endpoint de la aplicación, p. ej. https://acme.example.com.
  • Credencial — una entrada en el Almacén de Credenciales que la API acepta.
  • Accesibilidad de red — el entorno de Beak AI debe poder alcanzar esa URL. Los sistemas autoalojados en una red privada necesitan que la configuración egress_allow_private del tenant esté habilitada; consulte a su administrador.
  • Permiso de conector — connectors:manage. Solo los administradores lo poseen, ya que un conector determina qué URLs llamará el servicio de ingesta.

Paso 1 — Crear la fuente de datos​

  1. Vaya a Fuentes de Datos → Crear Fuente de Datos.
  2. Elija el tipo Sistema y seleccione su conector.
  3. Complete los campos de conexión y elija la credencial.
  4. Guardar.

Los campos mostrados provienen del manifiesto del conector, por lo que un conector recién registrado genera su propio formulario sin necesidad de actualizar Studio.

Paso 2 — Detectar qué puede sincronizarse​

Abra la fuente de datos guardada y encuentre la sección Recurso, luego haga clic en Detectar automáticamente.

Beak AI sondea la API e informa lo que encuentra:

  1. Busca una descripción de API publicada — un documento OpenAPI/Swagger en una ruta convencional, o un documento de servicio OData.
  2. Si no existe ninguno, ingrese una o más rutas de endpoint para muestrear (p. ej. /api/v2/tickets, /api/v2/users) y haga clic en Detectar datos.

Para cada colección que encuentra, Beak AI muestrea registros en vivo e informa:

ReportadoQué significa
Registros enDónde en la respuesta se encuentran los registros (p. ej. $.data, $.value)
CamposCada campo encontrado, con su tipo y con qué frecuencia está vacío
PaginaciónCómo la API recorre los resultados por páginas
IncrementalEl campo que indica cuándo se modificó por última vez un registro. Se registra para uso futuro — las sincronizaciones aún no filtran por él (ver Paso 3)

Las colecciones que no pueden sincronizarse se listan igualmente, junto con el motivo — para que siempre vea todo lo que expone la API, no una vista filtrada.

Cada colección se marca como Sincronizable o No sincronizable.

Nota: La detección lee una pequeña muestra de la API. No ingiere nada, no modifica el sistema fuente y no cambia su fuente de datos — solo informa lo que expone la API.

La detección es un informe de solo lectura, no una configuración. Le indica qué ofrece la API del conector, para que sepa qué está disponible antes de decidir qué debe ingerir esta fuente de datos. Deliberadamente no rellena el campo Recurso, porque los dos valores son cosas diferentes: una colección detectada se nombra según su ruta URL (/api/v2/tickets se reporta como api_v2_tickets), mientras que Recurso debe coincidir con el tipo de recurso configurado para ese conector (ticket). Copiar el nombre detectado en el campo guardaría un valor que la canalización de sincronización no puede resolver.

Por eso, use la detección para decidir qué sincronizar y luego establezca Recurso con el tipo de recurso que declara el conector y haga clic en Guardar recurso.

Paso 3 — Sincronizar​

Use Sincronizar ahora desde la lista de fuentes de datos, o establezca un programa recurrente desde la página de Conocimiento en Agent Runtime (solo administradores). Las opciones de frecuencia van desde cada 6 horas hasta mensual, o cualquier expresión cron personalizada con una vista previa en vivo de la próxima ejecución.

Cada sincronización es una actualización completa​

Una sincronización vuelve a leer el recurso completo y luego reemplaza los registros anteriores de la fuente de datos con lo que acaba de leer. Por eso, cada ejecución deja exactamente una copia de cada registro tal como existe en el sistema fuente en ese momento:

  • Los registros editados se corrigen — un ticket actualizado no queda junto a su versión anterior.
  • Los registros eliminados desaparecen — un registro eliminado en el origen deja de ser recuperable.
  • Las sincronizaciones repetidas no se acumulan — ejecutar dos veces produce el mismo recuento, no el doble.

Nota: Obtener todo y reemplazar todo es una sola decisión, no dos. Reemplazar tras una lectura parcial eliminaría los registros que la lectura omitió, por lo que una ejecución que obtiene menos que el recurso completo nunca realiza el reemplazo.

Si un límite de seguridad interrumpe una ejecución, los registros leídos se conservan, la ejecución se reporta como incompleta y los registros anteriores se mantienen en su lugar en lugar de ser reemplazados.

Las sincronizaciones incrementales — leer solo lo que cambió — aún no están disponibles. Cuando un conector expone un campo de último cambio, Beak AI lo detecta y lo registra, de modo que no se pierde historial cuando el modo llegue; simplemente no se usa hoy para filtrar una obtención. Deben cumplirse dos condiciones por proveedor: la API debe tener un filtro de último cambio, y ese filtro debe cubrir ediciones y no solo creaciones. Un filtro que cubre solo creaciones nunca volvería a leer silenciosamente un registro editado — un modo correcto vale más que dos donde uno tiene pérdidas silenciosas.

Qué ocurre con los datos​

Cada registro se convierte en un documento legible breve, se incrusta y se almacena en el almacén vectorial del tenant. Los agentes lo recuperan semánticamente — un agente al que se le pregunta "¿alguien ha reportado que la VPN cae esta semana?" coincide por significado, no por palabras clave.

De forma predeterminada, un registro se representa como líneas Campo: valor, lo que funciona para cualquier aplicación sin configuración. Para una mejor recuperación, un conector puede definir una plantilla de documento:

Ticket #{id}: {subject}

Status: {status}
Requester: {requester_name}

{description}

Los campos elegidos como metadatos se convierten además en filtros, de modo que un agente puede limitarse a (por ejemplo) solo tickets abiertos.

Nota: Cualquier tipo de registro es válido — tickets, activos, usuarios, grupos, contratos, órdenes de compra. No existe una lista fija de tipos de entidad admitidos.

Solución de problemas​

SíntomaCausa y solución
"Sin recurso configurado" en la fuente de datosAún no se ha guardado un recurso. La sincronización fallará hasta que se haga. Elija uno de la lista de Recursos, o escriba el tipo de recurso del conector si este aún no declara sus recursos.
La sincronización falla aunque hay un recurso guardadoEl valor guardado no coincide con un tipo de recurso configurado para ese conector. Debe ser el tipo de recurso del conector (p. ej. ticket), no un nombre de colección detectado (p. ej. api_v2_tickets).
La detección no encuentra nadaLa API no publica ninguna especificación en una ruta convencional. Ingrese las rutas de endpoint directamente.
Una colección muestra "No accesible"Por lo general, la credencial carece de permiso para ese endpoint, o la ruta devuelve algo distinto a una lista de registros. El motivo reportado lo aclara.
La detección está bloqueadaLa URL resuelve a una dirección privada y el tenant no ha habilitado los endpoints privados. Consulte a un administrador sobre egress_allow_private.
Una colección requiere "soporte del motor"La API pagina los resultados de una forma aún no soportada (por ejemplo, una URL de continuación dentro del cuerpo de la respuesta). Esa colección aún puede configurarse para sincronizarse — comuníquelo al soporte.
La sincronización reporta incompletaUn límite de seguridad detuvo la ejecución (límite de página, registro o tamaño). Los registros leídos se conservan y la ejecución indica qué límite se alcanzó; los límites de un tenant son configurables.

Mejores Prácticas​

  • Detecte en lugar de escribir — deje que Beak AI informe la ruta del registro y el campo incremental en lugar de ingresarlos manualmente; una ruta de registro incorrecta produce una sincronización que tiene éxito con cero registros.
  • Ajuste el programa al recurso — cada sincronización vuelve a leer el recurso completo, por lo que una colección grande con un programa de cada 6 horas representa una carga real sobre los límites de la API del sistema fuente. Comience con una frecuencia menor y ajústela una vez que sepa cuánto dura una ejecución.
  • Limite el alcance de la credencial — solo lectura, y únicamente sobre las colecciones que pretende ingerir.
  • Empiece con una sola colección — confirme que los registros se ven correctamente en las respuestas del agente antes de agregar más.
  • Revise el contenido de un registro — todo lo ingerido se vuelve recuperable por cualquier agente al que esté vinculada la fuente de datos. Los campos con aspecto de credencial se omiten automáticamente, pero el contenido sensible para el negocio no.
  • Sincronice con un programa, no manualmente — un programa recurrente mantiene a los agentes actualizados; las sincronizaciones ad hoc se desactualizan.

Páginas Relacionadas​