Conectar um agente de IA ao Microsoft Teams

Esta página mostra como integrar agentes de IA com o Microsoft Teams usando a autenticação OAuth "Em nome de". Essa integração permite que seus agentes Databricks interajam com os usuários por meio do Microsoft Teams, mantendo acesso seguro e delegado pelo usuário aos recursos do Databricks.

Visão geral

Conectar um agente Databricks ao Microsoft Teams requer coordenação entre três plataformas: Databricks, Azure e Microsoft Teams. Em um nível alto, você conclui as seguintes etapas:

1. Criar um agente no Databricks: crie e implante um agente de IA num ponto de extremidade de serviço.
2. Configurar recursos do Azure: configure o Serviço de Bot do Azure, o Serviço de Aplicativo do Azure e defina as configurações de autenticação OAuth.
3. Criar uma política de federação OAuth: habilite a troca segura de tokens entre o Microsoft Entra ID e o Databricks.
4. Implantar o código do bot: implante o código do aplicativo que conecta o Teams ao seu agente Databricks.
5. Teste a integração: verifique se os usuários podem autenticar e interagir com seu agente por meio do Teams.

Requerimentos

Antes de começar, verifique se você tem:

• Privilégios de administrador do espaço de trabalho para criar conexões do Unity Catalog e implantar agentes
• Acesso a uma subscrição do Azure onde pode criar recursos
• Permissões de administrador do Databricks para criar políticas de federação OAuth
• Acesso a um espaço de trabalho do Microsoft Teams para teste

Passo 1. Criar um agente de IA no Databricks

Crie um agente de IA no Databricks que processe consultas do Microsoft Teams. Este agente serve como a inteligência central do seu chatbot e lida com as seguintes tarefas:

• Processa consultas de usuários do Teams
• Interage com serviços Databricks para recuperação e computação de dados
• Devolve respostas relevantes para a interface do Teams

Para criar um agente, consulte Criar agentes de IA no código. Depois de criar o seu agente, implante-o em um endereço de serviço.

Observe a URL do ponto de extremidade de serviço porque você precisa dela quando configura as variáveis de ambiente do aplicativo Web do Azure.

Passo 2. Configurar recursos do Azure

A integração requer recursos específicos do Azure para dar suporte à autenticação e implantar os componentes do bot do Teams.

Crie os seguintes recursos do Azure para dar suporte à integração do bot do Teams. Todos os recursos devem estar na mesma região do Azure.

Criar um grupo de recursos

1. Navegue até o portal do Azure.

2. Clique em Criar um recurso.

3. Procure por Grupo de Recursos e selecione-o.

   Importante

   Todos os recursos do Azure que você cria devem estar na mesma região que seu grupo de recursos.

Configure o grupo de recursos:

1. Escolha a sua subscrição do Azure.
2. Introduza um nome para o grupo de recursos.
3. Selecione uma região do Azure (por exemplo, Leste dos EUA).
4. Clique em Rever + Criar e, em seguida, clique em Criar.

Criar um Plano do Serviço de Aplicações

1. No portal do Azure, clique em Criar um recurso.
2. Procure Plano de Serviço de Aplicações e selecione-o.

Configure o Plano do Serviço de Aplicativo:

1. Escolha a sua subscrição do Azure.
2. Selecione o grupo de recursos que você criou.
3. Insira um nome para o Plano de Serviço de Aplicações.
4. Selecione Linux como o sistema operacional.
5. Selecione a mesma região do seu grupo de recursos.
6. Em Plano de preços, selecione B1 básico.
7. Clique em Rever + Criar e, em seguida, clique em Criar.

Criar uma Aplicação Web

1. No portal do Azure, clique em Criar um recurso.
2. Pesquise por Web App e selecione-o.

Configure o aplicativo Web:

1. Escolha a sua subscrição do Azure.
2. Selecione o grupo de recursos que você criou.
3. Insira um nome para o aplicativo Web.
4. Defina Publicar como Código.
5. Selecione Python 3.13 como o stack de runtime.
6. Selecione a mesma região do Azure que seus outros recursos.
7. Ative Secure Unique Default Hostname para Ativado.
8. Clique em Rever + Criar e, em seguida, clique em Criar.

Criar um Bot do Azure

1. No portal do Azure, clique em Criar um recurso.
2. Procure o Bot do Azure e selecione-o.

Configure o Bot do Azure:

1. Insira um identificador de bot (nome).
2. Escolha a sua subscrição do Azure.
3. Selecione o grupo de recursos que você criou.
4. Defina Data residency como Global.
5. Defina o Plano de Preços como Gratuito.
6. Defina Tipo de Aplicação como Locatário Único.
7. Defina Tipo de Criação para Criar uma nova ID de Aplicativo Microsoft.
8. Deixe a referência de gerenciamento de serviços em branco.
9. Clique em Rever + Criar e, em seguida, clique em Criar.

Depois que o Bot do Azure for criado, defina suas configurações:

1. Navegue até o recurso de Bot do Azure.

2. Em Definições, selecione Configuração.

3. Defina o ponto de extremidade de mensagens como https://<your-webapp-name>.azurewebsites.net/api/messages.

   Substitua <your-webapp-name> pelo nome do aplicativo Web. Você pode confirmar a URL verificando o domínio padrão no recurso do aplicativo Web.

4. Clique em Aplicar.

5. Copie e salve a ID do Aplicativo Microsoft e a ID do Locatário do Aplicativo.

6. Ao lado de ID do Aplicativo Microsoft, clique em Gerenciar Senha.

7. Clique em Novo segredo do cliente para criar um novo segredo do cliente.

8. Copie e guarde o valor do segredo do cliente. Não é possível visualizar esse valor novamente depois de sair da página.

Configurar o canal do Microsoft Teams

1. No recurso Bot do Azure, em Canais, selecione Microsoft Teams.
2. Aceite os Termos de Serviço.

Depois de concluir essas etapas, você criou e configurou os seguintes recursos:

• Grupo de recursos: um contêiner lógico para recursos relacionados do Azure
• Plano do serviço de aplicativo: uma configuração para recursos de computação que define como os aplicativos são executados
• Aplicativo Web: hospeda o código do bot
• Bot do Azure: um serviço que permite a ativação de canal para interagir com o bot
• Aplicativo do Azure: gerencia configurações de autenticação, incluindo segredos de cliente, chaves, escopos e tokens

Configurar o aplicativo do Azure para OAuth

Configure seu aplicativo do Azure para habilitar a autenticação OAuth 2.0 em nome do usuário.

1. No portal do Azure, navegue até seu aplicativo do Azure para o bot.

Na seção Autenticação , adicione uma URL de redirecionamento:

1. Clique em Adicionar uma plataforma>Web.

2. Adicionar URI de redirecionamento: https://token.botframework.com/.auth/web/redirect

3. Clique em Configurar.

   

Na seção Configuração de token , adicione uma declaração opcional para o token de acesso:

1. Clique em Adicionar declaração opcional>Token de acesso.
2. Pesquise e selecione a preferred_username reivindicação.

Na seção Expor uma API , crie um escopo:

1. Defina o URI da ID do aplicativo como api://<app_id> (use a ID do aplicativo/cliente).

2. Clique em Salvar>Adicionar um escopo.

3. Configure o escopo:

   • Nome do escopo: access_as_user
   • Quem pode consentir: administradores e utilizadores
   • Nome de exibição do consentimento do administrador: acessar a API como usuário conectado
   • Descrição do consentimento do administrador: permitir que o aplicativo acesse a API como usuário
   • Nome de exibição do consentimento do usuário: Acesse a API como você
   • Descrição do consentimento do usuário: permita que o aplicativo acesse a API como você

Na seção Permissões da API , adicione permissões do Microsoft Graph:

1. Clique em Adicionar uma permissão>Microsoft Graph>Permissões delegadas.
2. Selecione as permissões email, openid e profile.

Na seção Manifesto , verifique a versão do token de acesso:

1. Localize a api chave no manifesto JSON.
2. Certifique-se de que requestedAccessTokenVersion está definido como 2. Se não estiver, altere-o para 2 e guarde.

Configurar a conexão OAuth do Bot do Azure

Configure a conexão OAuth em seu recurso de Bot do Azure:

1. No Bot do Azure, navegue até Configurações>de Configuração>Adicionar Configurações de Conexão OAuth.

2. Configure a conexão:

   • Nome: escolha um nome descritivo (você usa isso na configuração do aplicativo Web)
   • Provedor de serviços: Azure Ative Directory v2
   • ID do cliente: seu aplicativo de bot do Azure/ID do cliente
   • Segredo do cliente: o segredo que você criou para o aplicativo
   • ID do inquilino: o ID do locatário da sua organização
   • Escopos: api://<app_id>/access_as_user (use o ID da aplicação/cliente do Azure)

3. Clique em Salvar.

   

Configurar o aplicativo Web para integração do agente

Configure as variáveis de ambiente do Aplicativo Web e o comando de inicialização para a integração do agente Databricks:

1. Navegue até Configurações>de variáveis de ambiente em seu aplicativo Web.
2. Adicione as seguintes variáveis de agente Databricks:

1. Clique em Salvar.
2. Navegue até Definições>Configuração.
3. Defina o comando Startup para: python3 app.py
4. Clique em Salvar.

Passo 3. Criar política de federação OAuth no Databricks

Crie uma política de federação OAuth para habilitar a autenticação segura "em nome do usuário" entre o Microsoft Teams e o Databricks. Esta política permite a troca de tokens entre o Microsoft Entra ID e as APIs REST do Databricks.

Para obter informações detalhadas sobre políticas de federação, consulte:

• Configurar uma política de federação
• Autenticar com um token de identidade do provedor

Criar a política de federação usando a CLI do Databricks

1. Faça login no console da conta Databricks usando seu ID de conta Databricks:

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

2. Crie a política de federação usando a sua aplicação app_id do Azure e tenant_id:

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

Depois de criar a política de federação, você pode trocar tokens de ID do Microsoft Entra por tokens Databricks, que permitem solicitações autenticadas para APIs do Databricks em nome do usuário.

Passo 4. Implantar código de bot no Aplicativo Web do Azure

Implante o código do aplicativo bot em seu Aplicativo Web do Azure para concluir a integração.

Clone o repositório do bot

Clone o repositório que contém o código do bot que gere a autenticação do fluxo OAuth, a troca de token do Databricks e a interação com o agente.

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

Instalar a CLI do Azure

Instale a CLI do Azure para sua plataforma:

• Windows: Instalar a CLI do Azure no Windows
• macOS:Instalar a CLI do Azure no macOS
• Linux: Instalar a CLI do Azure no Linux

Implementar a aplicação

1. Inicie sessão na sua conta do Azure:

   az login
   

   Um navegador da Web é aberto para autenticação. Escolha a mesma assinatura que você usou para criar os recursos do Azure.

2. Em um terminal, navegue até a pasta teams-bot do repositório clonado: cd databricks-bot-service/teams-bot/

3. Implante o código do bot no aplicativo Web:

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

   Substitua <resource_group> pelo nome do grupo de recursos do Azure e <web_app_name> pelo nome do aplicativo Web.

   O processo de compilação e início leva vários minutos. Quando o processo for concluído, você verá a saída JSON com informações sobre o aplicativo e o código-fonte carregado.

Passo 5. Testar o bot

Teste a integração do bot usando o Chat da Web do Serviço de Bot do Azure:

1. Navegue até Teste de Configurações>no Chat da Web em seu recurso de Bot do Azure.
2. Digite "Olá" para ver o botão de login.
3. Depois de iniciar sessão, vê a mensagem "Agora iniciou sessão".
4. Faça perguntas relacionadas ao domínio do seu bot. O bot retorna respostas do seu agente Databricks.

Próximos passos

• Saiba mais sobre a autenticação para agentes de IA
• Analisar Conectar ferramentas de agente de IA a serviços externos
• Explore UC conexões HTTP
• Leia a documentação do Microsoft Bot Framework