Conecta Databricks Genie con Microsoft Agent 365

Utiliza esta guía para conectar un espacio de trabajo de Databricks a Microsoft Agent 365. Después de conectarte, el Agente 365 sincroniza los agentes Genie del espacio de trabajo en el registro de agentes de Microsoft 365 y recopila su actividad de conversación con fines de observabilidad.

Note

Databricks renombró los espacios Genie como agentes Genie. Algunas API y documentación de Databricks todavía utilizan el término Genie space.

Funcionamiento de la conexión

El Agente 365 inicia sesión en el espacio de trabajo como un principal de servicio Databricks utilizando autenticación OAuth máquina a máquina (M2M). La conexión utiliza estos valores:

Campo de conexión Valor de Databricks Dónde encontrarla
URL del espacio de trabajo La URL del espacio de trabajo con solo el esquema y el host Obtén la URL del espacio de trabajo
Id de cliente ID de aplicación del principal de servicio Creación de una entidad de servicio
Secreto de cliente Un secreto OAuth para la entidad de servicio Generar un secreto OAuth

Con estas credenciales, Agente 365:

  • Enumera los agentes Genie a los que el principal de servicio puede acceder y lee sus datos.
  • Lee las conversaciones y mensajes de Genie de cada agente sincronizado cuando se selecciona Recoger datos de observabilidad del agente , y muestra la actividad en la pestaña de Actividad del agente.

El Agente 365 no hace preguntas a los agentes Genie, no ejecuta consultas SQL ni cambia agentes Genie. La única excepción es cuando un administrador elimina un agente sincronizado en Agent 365 y el principal de servicio tiene permiso de Can Manage sobre el agente Genie. En ese caso, el Agente 365 mueve el agente Genie a la papelera en Databricks.

Antes de empezar

  • Confirma que el administrador de IA de Agent 365 puede crear conexiones en el centro de administración de Centro de administración de Microsoft 365.
  • Identifica el espacio de trabajo de Databricks que contiene los agentes Genie que quieres sincronizar. Cada conexión cubre un espacio de trabajo.
  • Pide a un administrador de espacios de trabajo de Databricks que complete los pasos de Databricks en este artículo. Los administradores de espacios de trabajo pueden crear entidades de servicio, generar secretos OAuth y compartir agentes Genie.
  • Confirma que Genie funciona en el espacio de trabajo.

Obtén la URL del espacio de trabajo

  1. Inicia sesión en el espacio de trabajo de Databricks.

  2. Copie la dirección URL de la barra de direcciones del explorador.

  3. Conserva solo el esquema y el host. Elimina cualquier ruta o cadena de consulta, como /genie o ?o=1234567890123456.

    Captura de pantalla de un espacio de trabajo de Databricks abierto en un navegador, con la URL del espacio de trabajo en la barra de direcciones.

El formato de la URL del espacio de trabajo depende de la nube que aloja el espacio de trabajo:

Cloud URL de espacio de trabajo de ejemplo
AWS https://dbc-a1b2c3d4-e5f6.cloud.databricks.com
Azure https://adb-1234567890123456.7.azuredatabricks.net
Nube de Google https://1234567890123456.7.gcp.databricks.com

Los administradores de cuentas también pueden encontrar la URL del espacio de trabajo en la consola de cuentas de Databricks bajo Espacios de trabajo.

Crear un servicio principal

Crea una entidad de servicio dedicada para Agent 365 para que puedas auditar y revocar su acceso de forma independiente de otras integraciones.

  1. En el espacio de trabajo de Databricks, selecciona tu nombre de usuario en la barra superior y luego selecciona Configuración.

  2. Seleccione Identidad y acceso. Junto a Entidades de servicio, selecciona Gestionar.

  3. Seleccione Agregar service principal.

    Captura de pantalla de la página de entidades de servicio en la configuración del espacio de trabajo de Databricks, con el botón Añadir entidad de servicio.

  4. Crea una nueva entidad de servicio con un nombre descriptivo, como agent365-connector. En Azure Databricks, selecciona Añadir nuevo y luego selecciona Administrado por Databricks.

  5. Activa los permisos de acceso a Databricks SQL y acceso al Workspace. Agent 365 no necesita acceso de consumidor. Activa el acceso de administrador solo si eliges que la entidad de servicio sea administrador del espacio de trabajo.

    Puedes establecer autorizaciones cuando añades el principal de servicio, o más adelante en la pestaña de Configuraciones del principal de servicio.

  6. Abre la entidad de servicio y copia su ID de aplicación. Usa este valor como ID de cliente para la conexión.

    Captura de pantalla de la página de detalles del principal de servicio en Databricks, mostrando el ID de la aplicación en la pestaña Configuraciones.

Para obtener más información, consulte Administración de entidades de servicio.

Generar un secreto OAuth

  1. En la página de detalles del principal del servicio, selecciona la pestaña Secretos y luego selecciona Generar secreto.

    Captura de pantalla de la pestaña Secretos de un service principal de Databricks, con el botón Generar secreto.

  2. En Duración (días), introduce cuánto tiempo es válido el secreto. El máximo es de 730 días.

  3. En Ámbito, selecciona Otras APIs, selecciona Añadir ámbito y luego selecciona all-apis.

    Captura de pantalla del cuadro de diálogo Generar secreto OAuth en Databricks, con una vida útil en días y la opción all-apis en la lista Agregar ámbito.

  4. Selecciona Generar.

  5. Copia el secreto y el ID del cliente, y luego selecciona Listo.

Importante

Databricks muestra el secreto solo una vez. Guárdalo en un lugar seguro y no lo compartas por correo electrónico, chat ni solicitudes de soporte. Si pierdes el secreto, genera uno nuevo. El ID del cliente es el mismo que el ID de aplicación del principal de servicio.

El diálogo marca all-apis como no recomendable. Los derechos de la entidad de servicio y los permisos del agente Genie siguen limitando lo que el Agente 365 puede leer. Apunta la fecha de caducidad del secreto para poder renovarlo antes de que caduque.

Da acceso a la entidad de servicio a los agentes Genie

El Agente 365 sincroniza y supervisa solo los agentes Genie a los que la entidad de servicio puede acceder. Elija una de las siguientes opciones.

Comparte agentes Genie con la entidad de servicio

Esta opción se recomienda porque solo concede acceso a los agentes Genie que elijas.

  1. En el espacio de trabajo Databricks, selecciona Agentes Genie en la barra lateral y luego abre un agente Genie.
  2. Seleccione Compartir.
  3. Introduce el nombre del principal de servicio, selecciona Añadir y luego establece el nivel de permiso. Para recopilar actividad, selecciona Puede administrar.
  4. Repite estos pasos para cada agente Genie que quieras sincronizar.

El nivel de permiso determina lo que puede hacer el Agente 365:

Permiso Lo que puede hacer el Agente 365
Puede ver Sincroniza el agente con su nombre y descripción, y la nube y la región del espacio de trabajo.
Editable También lee las instrucciones y fuentes de datos del agente, que aparecen como las instrucciones y fuentes de conocimiento del agente.
Puede administrar También lee los detalles de uso compartido del agente, recoge la actividad de conversación de todos los usuarios del agente y mueve el agente a la papelera cuando un administrador lo elimine en Agent 365.

La actividad requiere Puede gestionar. Databricks devuelve las conversaciones de todos los usuarios de un agente Genie solo a los principales que tienen el permiso Puede gestionar. Con un permiso menor, el agente sincroniza, pero no aparece ninguna actividad.

Tip

Los agentes Genie heredan permisos de su carpeta de espacio de trabajo. Para compartir varios agentes Genie a la vez, guárdalos en una carpeta y compártela con la entidad de servicio.

Después de compartir un agente Genie, puede tardar uno o dos minutos antes de que la entidad de servicio pueda listarlo.

Haz que la entidad de servicio sea administradora del espacio de trabajo

Para cubrir a todos los agentes Genie en el espacio de trabajo, incluidos los agentes Genie que se crean después, activa Acceso de administrador para el principal de servicio en lugar de compartir los agentes Genie individualmente.

Caution

Los administradores del espacio de trabajo tienen control administrativo total del espacio de trabajo, incluido el permiso Puede gestionar en todos los agentes Genie. Utiliza esta opción solo si la política de seguridad de tu organización lo permite.

  1. En la página de detalles del principal de servicio, selecciona la pestaña Configuración.
  2. Selecciona Acceso de administrador y luego selecciona Actualizar. Databricks añade la entidad de servicio al grupo del espacio de trabajo admins.
  3. Para confirmar, ve a Configuración>Identidad y acceso. Junto a Grupos, selecciona Gestionar. Abre el grupo admins y comprueba que el principal del servicio esté listado en la pestaña Members.

Los cambios de permiso pueden tardar unos minutos en aplicarse.

Creación de la conexión

  1. Abra el Centro de administración de Microsoft 365.

  2. Seleccione Agentes>:Todos los agentes.

  3. En Plataformas conectadas, selecciona Gestionar.

  4. Seleccione + Conectar una plataforma.

  5. Introduce un nombre y una descripción para la conexión.

  6. En Plataforma externa, selecciona Databricks Genie. El método de autenticación es OAuth (Principal de servicio).

  7. Introduce la URL del espacio de trabajo, el ID del cliente y el secreto del cliente.

  8. Asegúrese de que se seleccione Collect agent observability data.

  9. Seleccione Comprobar autenticación.

  10. Cuando aparezca Conexión verificada correctamente, selecciona Guardar.

    Captura de pantalla de la configuración de conexión Databricks Genie en el centro de administración de Centro de administración de Microsoft 365, con la URL del espacio de trabajo, el ID del cliente y el secreto del cliente introducidos, un mensaje de Conexión verificada con éxito y Recoger datos de observabilidad del agente seleccionados.

La verificación confirma que el Agente 365 puede iniciar sesión en el espacio de trabajo y listar a los agentes Genie. Tiene éxito aunque la entidad de servicio aún no pueda acceder a ningún agente Genie.

Sincronizar agentes

Cuando guardas la conexión, se abre el panel de detalles y comienza la primera sincronización. Cuando termina la sincronización, el panel muestra **Sync

Captura de pantalla de una conexión Genie de Databricks en el centro de administración de Centro de administración de Microsoft 365, mostrando Sincronización completada y la lista de agentes Genie sincronizados.

El Agente 365 sincroniza a todos los agentes Genie a los que puede acceder la entidad de servicio. Los agentes sincronizados aparecen en el registro de agentes de Microsoft 365. Para encontrarlos, ve a Agentes>Todos los agentes y filtra Plataforma por Databricks Genie. También aparecen en un clúster de Genie de Databricks en el mapa de Agentes.

Para sincronizar después de crear o compartir más agentes Genie, abre la conexión y selecciona Sincronizar agentes.

Verificar actividad

  1. En Databricks, abre un agente Genie sincronizado y hazle unas preguntas. Sáltate este paso si el agente ya ha tenido conversaciones recientes.

  2. En el Centro de administración de Microsoft 365, abre el agente desde la lista de agentes sincronizados de la conexión o desde Agentes>Todos los agentes.

  3. Selecciona la pestaña Actividad. Cuando se recopila actividad, Sesiones muestra una o más.

    Captura de pantalla de la pestaña Actividad de un agente sincronizado de Databricks Genie en el centro de administración de Microsoft 365, mostrando sesiones, excepciones, tiempo de ejecución del agente y un gráfico de sesiones a lo largo del tiempo.

La actividad puede tardar un tiempo en aparecer tras una conversación. Databricks no proporciona las identidades de usuario de Microsoft Entra, así que Usuarios Activos muestra N/A. Para consultar las definiciones de métricas, consulte Observabilidad de agentes de terceros (Frontier).

Rotar o revocar el acceso

Para rotar el secreto del cliente:

  1. En Databricks, genera un nuevo secreto OAuth para la entidad de servicio. Un principal de servicio puede tener hasta cinco secretos, así que puedes crear el nuevo secreto antes de borrar el anterior.
  2. En el Centro de administración de Microsoft 365, abre la connection y selecciona Editar. Introduce el nuevo secreto del cliente, selecciona Verificar autenticación y luego guarda la conexión.
  3. En Databricks, elimina el antiguo secreto de la pestaña Secretos de la entidad de servicio.

Para revocar el acceso:

  • Para bloquear el acceso a un agente Genie específico, elimina la entidad de servicio de la configuración de compartición del agente Genie.
  • Para detener todo acceso, elimina los secretos OAuth de la entidad de servicio o elimina la entidad de servicio del espacio de trabajo.

Troubleshoot

Síntoma Causa probable Resolution
Verificar autenticación falla El ID del cliente o el secreto es incorrecto o incluye espacios adicionales, el secreto ha caducado o se ha eliminado, o la URL del espacio de trabajo pertenece a otro espacio de trabajo Copia los valores de nuevo, genera un nuevo secreto si es necesario e introduce la URL del espacio de trabajo solo con el esquema y el host.
La verificación tiene éxito, pero ningún agente o solo algunos agentes se sincronizan La entidad de servicio no puede acceder a los agentes de Genie, o los agentes se compartieron hace unos momentos Comparte los agentes de Genie con la entidad de servicio o haz que sea un administrador del espacio de trabajo. Espera uno o dos minutos y luego selecciona Sincronizar agentes.
Los agentes no muestran instrucciones ni fuentes de conocimiento La entidad de servicio solo tiene permiso Can View Concede Can Edit o Can Manage en el agente Genie, y luego vuelve a sincronizar.
Los agentes se sincronizan, pero la actividad no muestra sesiones Recoger datos de observabilidad del agente está desmarcado, la entidad de servicio no tiene Can Manage, nadie ha utilizado el agente o el procesamiento sigue en curso Selecciona Recoger datos de observabilidad del agente en la conexión, concede Puede gestionar, interactúa con el agente y vuelve a comprobar más tarde.
Los agentes Genie no están disponibles en Databricks Las funciones de IA impulsadas por partners están desactivadas para la cuenta o el espacio de trabajo Pide a un administrador de cuentas de Databricks que active funciones de IA impulsadas por socios.
El secreto de cliente se ha perdido Databricks muestra un secreto solo una vez Genera un nuevo secreto y actualiza la conexión.

Prueba las credenciales fuera de Agent 365

Si la verificación sigue fallando, un administrador de Databricks puede probar las credenciales directamente. Establece las variables de entorno DATABRICKS_CLIENT_ID y DATABRICKS_CLIENT_SECRET, y luego solicita un token de acceso al espacio de trabajo. Sustituye <workspace-host> por el host de la URL del espacio de trabajo.

curl --request POST "https://<workspace-host>/oidc/v1/token" \
  --user "$DATABRICKS_CLIENT_ID:$DATABRICKS_CLIENT_SECRET" \
  --data "grant_type=client_credentials&scope=all-apis"

Una respuesta exitosa es un objeto JSON que contiene un valor access_token y un token_type de Bearer. Para comprobar a qué agentes Genie puede acceder el principal de servicio, establece la variable de entorno DATABRICKS_TOKEN en el valor access_token y luego lista los agentes Genie:

curl --request GET "https://<workspace-host>/api/2.0/genie/spaces" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN"

No guardes ni compartas el token de acceso.

Para problemas de conexión que no sean específicos de Databricks Genie, consulta Solucionar problemas de plataformas conectadas.

  • Última actualización o