Conectar um agente de IA ao Microsoft Teams

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

Visão geral

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

1. Crie um agente no Databricks: Crie e implante um agente de IA em um endpoint de serviço.
2. Configurar recursos do Azure: configurar o Serviço de Bot do Azure, o Serviço de Aplicativo do Azure e definir as configurações de autenticação OAuth.
3. Criar uma política de federação OAuth: habilitar a troca de token seguro entre a ID do Microsoft Entra e o Databricks.
4. Implante o código do bot: implante o código do aplicativo que conecta o Teams ao agente do Databricks.
5. Teste a integração: verifique se os usuários podem autenticar e interagir com seu agente por meio do Teams.

Requirements

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

• Privilégios de administrador do workspace para criar conexões do Catálogo do Unity e implantar agentes
• Acesso a uma assinatura do Azure em que você pode criar recursos
• Permissões de administrador do Databricks para criar políticas de federação OAuth
• Acesso a uma área de trabalho do Microsoft Teams para teste

Etapa 1. Criar um agente de IA no Databricks

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

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

Para criar um agente, consulte Criação de agentes de IA em código. Depois de criar seu agente, implante-o em um endpoint de serviço.

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

Etapa 2. Configurar recursos do Azure

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

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

Criar um grupo de recursos

1. Navegue no portal Azure.

2. Clique em Criar um recurso.

3. Pesquise o Grupo de Recursos e selecione-o.

   Importante

   Todos os recursos do Azure criados devem estar na mesma região do grupo de recursos.

Configure o grupo de recursos:

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

Criar um Plano do Serviço de Aplicativo

1. No portal do Azure, clique em Criar um recurso.
2. Pesquise o Plano do Serviço de Aplicativo e selecione-o.

Configurar o Plano do Serviço de Aplicativo:

1. Escolha a sua assinatura do Azure.
2. Selecione o grupo de recursos que você criou.
3. Digite um nome para o Plano de Serviço de Aplicativo.
4. Selecione Linux como o sistema operacional.
5. Selecione a mesma região que a do grupo de recursos.
6. Para o Plano de Preços, selecione Básico B1.
7. Clique em Examinar + Criar e, em seguida, clique em Criar.

Criar um aplicativo Web

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

Configurar o aplicativo Web:

1. Escolha a sua assinatura do Azure.
2. Selecione o grupo de recursos que você criou.
3. Insira um nome para o Aplicativo Web.
4. Defina Publicar em Código.
5. Selecione Python 3.13 como a pilha de execução.
6. Selecione a mesma região do Azure que seus outros recursos.
7. Ative o nome de host padrão exclusivo seguro.
8. Clique em Examinar + Criar e, em seguida, clique em Criar.

Criar um Bot do Azure

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

Configurar o Bot do Azure:

1. Insira um identificador de bot (nome).
2. Escolha a sua assinatura do Azure.
3. Selecione o grupo de recursos que você criou.
4. Defina a residência de dados como Global.
5. Defina o Plano de Preços como Gratuito.
6. Defina o tipo de aplicativo como Single Tenant.
7. Defina o tipo de criação para criar uma nova ID de aplicativo da Microsoft.
8. Deixe a referência de gerenciamento de serviços em branco.
9. Clique em Examinar + 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 Configurações, escolha Configuração.

3. Defina o endpoint 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 em seu recurso de 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 da 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 salve o valor do segredo do cliente. Não é possível exibir esse valor novamente depois de sair da página.

Configurar o canal do Microsoft Teams

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

Depois de concluir estas 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 habilita a ativação de canal para interagir com o bot
• Aplicativo do Azure: gerencia configurações de autenticação, incluindo segredos do cliente, chaves, escopos e tokens

Configurar o aplicativo do Azure para OAuth

Configure seu aplicativo do Azure para habilitar a autenticação do 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 usuários
   • Nome de exibição de consentimento do administrador: Acessar a API como usuário conectado
   • Descrição de consentimento do administrador: permitir que o aplicativo acesse a API como usuário
   • Nome de exibição de consentimento do usuário: Acessar a API como você
   • Descrição de consentimento do usuário: permitir que o aplicativo acesse a API como você

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

1. Clique em Adicionar uma permissão> nas permissões delegadas do Microsoft Graph>.
2. Selecione email, openide profile permissões.

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

1. Encontre a chave api no JSON do manifest.
2. Verifique se requestedAccessTokenVersion está configurado como 2. Se não estiver, altere-o para 2 e salve-o.

Configurar a conexão OAuth do Bot do Azure

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

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

2. Configure a conexão:

   • Nome: escolha um nome descritivo (use-o na configuração do aplicativo Web)
   • Provedor de Serviços: Azure Active 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 locatário: ID do locatário da sua organização
   • Escopos: api://<app_id>/access_as_user (use o ID do cliente/aplicativo do Azure)

3. Clique em Salvar.

   

Configurar o Aplicativo Web para integração de agente

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

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

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

Etapa 3. Criar política de federação do 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. Essa política permite a troca de tokens entre a ID do Microsoft Entra 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 o token do provedor de identidade

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

1. Faça logon no console da conta do Databricks usando sua ID da conta do Databricks:

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

2. Crie a política de federação usando o app_id e tenant_id do aplicativo 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"
     }
   }'
   

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

Etapa 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.

Clonar o repositório de bot

Clone o repositório que contém o código do bot que gerencia a autenticação de fluxo OAuth, a troca de tokens do Databricks e a interação do 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

Implantar o aplicativo

1. Faça logon 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.

Etapa 5. Testar o bot

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

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

Próximas etapas

• Saiba mais sobre a Autenticação para agentes de IA
• Examinar as ferramentas do agente de IA do Connect para serviços externos
• Explorar conexões HTTP do UC
• Ler a documentação do Microsoft Bot Framework