Conexión de un agente de IA a Microsoft Teams

Importante

Esta característica está en versión preliminar pública.

En esta página se muestra cómo integrar agentes de inteligencia artificial con Microsoft Teams mediante la autenticación "en nombre de" de OAuth. Esta integración permite que los agentes de Databricks interactúen con los usuarios a través de Microsoft Teams a la vez que mantienen el acceso seguro y delegado por el usuario a los recursos de Databricks.

Información general

La conexión de un agente de Databricks a Microsoft Teams requiere coordinación entre tres plataformas: Databricks, Azure y Microsoft Teams. En un nivel alto, complete los pasos siguientes:

1. Crear un agente en Databricks: Crear e implementar un agente de IA en un endpoint de servicio.
2. Configuración de recursos de Azure: configure Azure Bot Service, Azure App Service y configure las opciones de autenticación de OAuth.
3. Crear una directiva de federación de OAuth: habilite el intercambio de tokens seguro entre el identificador de Entra de Microsoft y Databricks.
4. Implementar el código del bot: implemente el código de aplicación que conecta Teams con el agente de Databricks.
5. Probar la integración: compruebe que los usuarios pueden autenticarse e interactuar con el agente a través de Teams.

Requisitos

Antes de comenzar, compruebe que tiene:

• Privilegios de administrador del área de trabajo para crear conexiones de Catálogo de Unity e implementar agentes
• Acceso a una suscripción de Azure en la que puede crear recursos
• Permisos de administrador de Databricks para crear directivas de federación de OAuth
• Acceso a un área de trabajo de Microsoft Teams para realizar pruebas

Paso 1. Creación de un agente de IA en Databricks

Cree un agente de INTELIGENCIA ARTIFICIAL en Databricks que procese consultas de Microsoft Teams. Este agente actúa como la inteligencia básica del bot de chat y controla las siguientes tareas:

• Procesa consultas de usuario desde Teams
• Interactúa con los servicios de Databricks para la recuperación y el cálculo de datos
• Devuelve respuestas relevantes a la interfaz de Teams.

Para crear un agente, consulte Creación de agentes de IA en el código. Después de crear el agente, impleméntelo en un punto de conexión de servicio.

Tenga en cuenta la dirección URL del punto de conexión de servicio porque la necesita al configurar las variables de entorno de la aplicación web de Azure.

Paso 2. Configuración de recursos de Azure

La integración requiere recursos específicos de Azure para admitir la autenticación e implementar los componentes del bot de Teams.

Cree los siguientes recursos de Azure para admitir la integración del bot de Microsoft Teams. Todos los recursos deben estar en la misma región de Azure.

Nota:

Guarde el identificador de aplicación de Microsoft, el identificador de inquilino de la aplicación y el secreto de cliente a medida que cree estos recursos porque los necesita para los pasos de configuración posteriores.

Creación de un grupo de recursos

1. Vaya a Azure Portal.

2. Haga clic en Crear un recurso.

3. Busque Grupo de recursos y selecciónelo.

   Importante

   Todos los recursos de Azure que cree deben estar en la misma región que el grupo de recursos.

Configure el grupo de recursos:

1. Elija la suscripción de Azure.
2. Escriba un nombre para el grupo de recursos.
3. Seleccione una región de Azure (por ejemplo, Este de EE. UU.).
4. Haga clic en Revisar y crear y, a continuación, haga clic en Crear.

Crear un plan de App Service

1. En Azure Portal, haga clic en Crear un recurso.
2. ** Busque App Service Plan y selecciónelo.

Configure el plan de App Service:

1. Elija la suscripción de Azure.
2. Seleccione el grupo de recursos que ha creado.
3. Escriba un nombre para el plan de App Service.
4. Seleccione Linux como sistema operativo.
5. seleccione la misma región que la del grupo de recursos.
6. En Plan de precios, seleccione Básico B1.
7. Haga clic en Revisar y crear y, a continuación, haga clic en Crear.

Creación de una aplicación web

1. En Azure Portal, haga clic en Crear un recurso.
2. Busque Aplicación web y selecciónela.

Configure la aplicación web:

1. Elija la suscripción de Azure.
2. Seleccione el grupo de recursos que ha creado.
3. Escriba un nombre para la aplicación web.
4. Establezca Publicar en Código.
5. Seleccione Python 3.13 como entorno de ejecución.
6. Seleccione la misma región de Azure que los demás recursos.
7. Ponga Nombre de Host Predeterminado Seguro Único en Activado.
8. Haga clic en Revisar y crear y, a continuación, haga clic en Crear.

Creación de un bot de Azure

1. En Azure Portal, haga clic en Crear un recurso.
2. Busque Azure Bot y selecciónelo.

Configuración del bot de Azure:

1. Escriba un identificador de bot (nombre).
2. Elija la suscripción de Azure.
3. Seleccione el grupo de recursos que ha creado.
4. Establezca Residencia de datos en Global.
5. Establezca Plan de precios en Gratis.
6. Establezca Tipo de aplicación en Inquilino único.
7. Establezca Tipo de creación en Crear nuevo identificador de aplicación de Microsoft.
8. Deje referencia de gestión de servicios en blanco.
9. Haga clic en Revisar y crear y, a continuación, haga clic en Crear.

Después de crear el bot de Azure, configure sus opciones:

1. Vaya al recurso de Azure Bot.

2. En Configuración, seleccione Configuración.

3. Establezca el punto de conexión de mensajería en https://<your-webapp-name>.azurewebsites.net/api/messages.

   Reemplace por <your-webapp-name> el nombre de la aplicación web. Puede confirmar la dirección URL comprobando el dominio predeterminado en el recurso de aplicación web.

4. Haga clic en Aplicar.

5. Copie y guarde el identificador de aplicación de Microsoft y el identificador de inquilino de la aplicación.

6. Junto a Id. de aplicación de Microsoft, haga clic en Administrar contraseña.

7. Haga clic en Nuevo secreto de cliente para crear un nuevo secreto de cliente.

8. Copie y guarde el valor secreto de cliente. No puede volver a ver este valor después de salir de la página.

Importante

Verá un secreto de cliente existente al navegar a la página, pero debe crear uno nuevo para esta integración.

Configurar el canal de Microsoft Teams

1. En el recurso de Azure Bot, en Canales, seleccione Microsoft Teams.
2. Acepte los Términos de servicio.

Después de completar estos pasos, ha creado y configurado los siguientes recursos:

• Grupo de recursos: un contenedor lógico para los recursos de Azure relacionados
• Plan de App Service: una configuración para los recursos de proceso que define cómo se ejecutan las aplicaciones
• Aplicación web: hospeda el código del bot
• Bot de Azure: un servicio que habilita la activación del canal para interactuar con el bot
• Aplicación de Azure: administra las configuraciones de autenticación, incluidos los secretos de cliente, las claves, los ámbitos y los tokens.

Configuración de la aplicación de Azure para OAuth

Configure la aplicación de Azure para habilitar la autenticación de OAuth 2.0 en nombre del usuario.

1. En Azure Portal, vaya a la aplicación de Azure para el bot.

En la sección Autenticación , agregue una dirección URL de redireccionamiento:

1. Haga clic en Agregar una plataforma>web.

2. Agregue el URI de redirección: https://token.botframework.com/.auth/web/redirect

3. Haga clic en Configurar.

   

En la sección Token Configuration, agregue una reclamación opcional para el token de acceso:

1. Haga clic en Agregar notificación opcional>token de acceso.
2. Busque y seleccione la preferred_username reclamación.

En la sección Exponer una API , cree un ámbito:

1. Establezca el URI del ID de aplicación en api://<app_id> (utilice el ID de cliente o de su aplicación).

2. Haga clic en Guardar>Agregar un ámbito.

3. Configure el ámbito:

   • Nombre de ámbito: access_as_user
   • Quién puede dar su consentimiento: administradores y usuarios
   • Nombre para mostrar del consentimiento del administrador: Acceso a la API como usuario autenticado
   • Descripción del consentimiento del administrador: permitir que la aplicación acceda a la API como usuario
   • Nombre para mostrar del consentimiento del usuario: Acceder a la API como tú
   • Descripción del consentimiento del usuario: permitir que la aplicación acceda a la API a medida que lo haga

En la sección Permisos de API , agregue permisos de Microsoft Graph:

1. Haga clic en Agregar un permiso>Microsoft Graph>permisos delegados.
2. Seleccione email, openidy profile permisos.

En la sección Manifiesto , compruebe la versión del token de acceso:

1. Busque la api clave en el JSON del manifiesto.
2. Asegúrese de que requestedAccessTokenVersion está establecido en 2. Si no es así, cámbielo a 2 y guárdelo.

Configuración de la conexión de OAuth de Azure Bot

Configure la conexión de OAuth en el recurso de Azure Bot:

1. En su bot de Azure, vaya a Configuración>Configuración>Agregar Configuración de conexión OAuth.

2. Configure la conexión:

   • Nombre: elija un nombre descriptivo (lo usará en la configuración de la aplicación web).
   • Proveedor de servicios: Azure Active Directory v2
   • Id. de cliente: la aplicación o el identificador de cliente del bot de Azure
   • Secreto de cliente: el secreto que creó para la aplicación
   • ID de arrendatario: El ID de arrendatario de tu organización
   • Ámbitos: api://<app_id>/access_as_user (use el ID de aplicación/cliente de Azure)

3. Haz clic en Guardar.

   

Configuración de la aplicación web para la integración del agente

Configure las variables de entorno de aplicación web y el comando de inicio para la integración del agente de Databricks:

1. Vaya a Configuración>Variables de entorno en su aplicación web.
2. Agregue las siguientes variables del agente de Databricks:

Nombre de la variable	Importancia	Description
ConnectionName	<oauth_connection_name>	Nombre de la conexión de OAuth creada en Azure Bot
DATABRICKS_HOST	<databricks_workspace_url>	La URL del área de trabajo de Databricks donde se ejecuta el extremo de servicio del agente (por ejemplo, https://adb-1234567890123456.7.azuredatabricks.net).
MicrosoftAppID	<microsoft_app_id>	El identificador de cliente o el identificador de aplicación del bot de Azure (guardado anteriormente)
MicrosoftAppPassword	<client_secret>	Secreto de cliente que creó para la aplicación (guardado anteriormente)
MicrosoftAppType	singletenant	Tipo de aplicación
MicrosoftTenantId	<tenant_id>	Identificador de inquilino de la organización (guardado anteriormente)
SERVING_ENDPOINT_NAME	<endpoint_name>	Nombre del punto de servicio que se ejecuta en el área de trabajo de Databricks
SCM_DO_BUILD_DURING_DEPLOYMENT	True	Instala y compila dependencias durante la implementación.
WEBSITE_HTTPLOGGING_RETENTION_DAYS	3	Conserva los registros durante 3 días.

1. Haz clic en Guardar.
2. Vaya a Configuración>Opciones.
3. Establezca el comando Startup en: python3 app.py
4. Haz clic en Guardar.

Nota:

El comando python3 app.py de inicio está configurado para trabajar con el código del bot del agente de Databricks que implemente en un paso posterior. Esto difiere de otras configuraciones de bot de Azure que pueden usar distintos comandos de inicio.

Paso 3. Creación de una directiva de federación de OAuth en Databricks

Cree una directiva de federación de OAuth para habilitar la autenticación segura "en nombre del usuario" entre Microsoft Teams y Databricks. Esta directiva permite el intercambio de tokens entre microsoft Entra ID y las API REST de Databricks.

Para obtener información detallada sobre las directivas de federación, consulte:

• Configuración de una directiva de federación
• Autenticación con un token de proveedor de identidades

Nota:

Debe ser un administrador de Databricks para crear directivas de federación.

Creación de la directiva de federación mediante la CLI de Databricks

1. Inicie sesión en la consola de la cuenta de Databricks con el identificador de cuenta de Databricks:

   databricks auth login --host https://accounts.azuredatabricks.net/ --account-id <your_databricks_account_id>
   

2. Cree la directiva de federación utilizando las app_id y tenant_id de su aplicación de Azure.

   databricks account federation-policy create --json '{
     "oidc_policy": {
       "issuer": "https://login.microsoftonline.com/<tenant_id>/v2.0",
       "audiences": [
         "<app_id>"
       ],
       "subject_claim": "preferred_username"
     }
   }'
   

Después de crear la directiva de federación, puede intercambiar tokens de Microsoft Entra ID por tokens de Databricks, lo que permite realizar solicitudes autenticadas a las API de Databricks en representación del usuario.

Paso 4. Implementación del código de bot en Azure Web App

Implemente el código de la aplicación de bot en la aplicación web de Azure para completar la integración.

Clonación del repositorio de bots

Clone el repositorio que contiene el código del bot que administra la autenticación del flujo OAuth, el intercambio de tokens de Databricks, y la interacción con el agente.

git clone https://github.com/databricks-solutions/teams-databricks-bot-service.git

Instalación de la CLI de Azure

Instale la CLI de Azure para la plataforma:

• Windows: Instalación de la CLI de Azure en Windows
• macOS: Instalación de la CLI de Azure en macOS
• Linux: Instalación de la CLI de Azure en Linux

Implementación de la aplicación

1. Inicie sesión en una cuenta de Azure:

   az login
   

   Se abre un explorador web para la autenticación. Elija la misma suscripción que usó para crear los recursos de Azure.

2. En un terminal, vaya a la carpeta teams-bot del repositorio clonado: cd databricks-bot-service/teams-bot/

3. Implemente el código del bot en la aplicación web:

   az webapp up --resource-group <resource_group> --name <web_app_name> --runtime "PYTHON:3.13" --sku B1
   

   Reemplace por <resource_group> el nombre del grupo de recursos de Azure y <web_app_name> por el nombre de la aplicación web.

   El proceso de compilación e inicio tarda varios minutos. Cuando se complete el proceso, verá la salida JSON con información sobre la aplicación y el código fuente cargado.

Paso 5. Probar el bot

Pruebe la integración del bot mediante el chat web de Azure Bot Service:

1. Vaya a Configuración>Prueba en el chat web en su recurso Azure Bot.
2. Escriba "Hello" para ver el botón de inicio de sesión.
3. Después de iniciar sesión, verá el mensaje "Ya ha iniciado sesión".
4. Realice preguntas relacionadas con el dominio del bot. El bot devuelve respuestas del agente de Databricks.

Pasos siguientes

• Más información sobre la autenticación para agentes de IA
• Revisión de las herramientas del agente de IA para conectar a servicios externos
• Exploración de conexiones HTTP de UC
• Lea la documentación de Microsoft Bot Framework.