Conecte o Databricks Genie ao Microsoft Agent 365

Use este guia para conectar um espaço de trabalho Databricks ao Microsoft Agent 365. Depois que você se conectar, o Agente 365 sincroniza os agentes Genie do workspace com o registro de agentes do Microsoft 365 e coleta a atividade de conversa deles para observabilidade.

Como funciona a conexão

O Agente 365 faz login no espaço de trabalho como um principal de serviço Databricks usando autenticação OAuth machine-to-machine (M2M). A conexão usa estes valores:

Com essas credenciais, Agent 365:

• Lista os agentes Genie que a entidade de serviço pode acessar e lê seus dados.
• Lê as conversas e mensagens do Genie de cada agente sincronizado quando Coletar dados de observabilidade do agente é selecionado, e mostra a atividade na aba Atividade do agente.

O Agent 365 não faz perguntas para agentes do Genie, não executa consultas SQL nem muda os agentes do Genie. A única exceção é quando um administrador remove um agente sincronizado no Agent 365 e o principal de serviço tem a permissão Can Manage no agente Genie. Nesse caso, o Agente 365 move o agente Genie para o lixo no Databricks.

Antes de começar

• Confirme se o administrador de IA do Agent 365 pode criar conexões no Centro de administração do Microsoft 365.
• Identifique o workspace do Databricks que contém os agentes Genie que você quer sincronizar. Cada conexão cobre um espaço de trabalho.
• Peça a um administrador de workspace do Databricks para completar as etapas do Databricks neste artigo. Administradores de workspace podem criar entidades de serviço, gerar segredos OAuth e compartilhar agentes Genie.
• Confirme que o Genie funciona no workspace.

Obtenha a URL do workspace

1. Faça login no espaço de trabalho do Databricks.

2. Copie a URL da barra de endereços do navegador.

3. Mantenha apenas o esquema e o host. Remova qualquer caminho ou cadeia de consulta, como /genie ou ?o=1234567890123456.

   

O formato da URL do workspace depende da nuvem que hospeda o workspace:

Administradores de conta também podem encontrar a URL do workspace no console de contas Databricks, em Workspaces.

Criar um principal de serviço

Crie um principal de serviço dedicado para o Agente 365 para que você possa auditar e revogar seu acesso independentemente de outras integrações.

1. No espaço de trabalho do Databricks, selecione seu nome de usuário na barra superior e depois selecione Configurações.

2. Selecione Identidade e acesso. Ao lado de Entidades de Serviço, selecione Gerenciar.

3. Selecione Adicionar service principal.

   

4. Crie um novo service principal com um nome descritivo, como agent365-connector. No Azure Databricks, selecione Adicionar novo e depois selecione Gerenciado pelo Databricks.

5. Ative as permissões de acesso ao Databricks SQL e acesso ao Workspace. O Agent 365 não precisa de acesso de Consumidor. Ative o acesso de administrador somente se você optar por tornar o service principal administrador do workspace.

   Você pode definir direitos de acesso ao adicionar o principal de serviço, ou depois na aba Configurações do principal de serviço.

6. Abra o principal de serviço e copie seu ID de Aplicação. Use esse valor como ID do cliente para a conexão.

   

Para obter mais informações, consulte Gerenciar entidades de serviço.

Gerar um segredo OAuth

1. Na página de detalhes do principal de serviço, selecione a aba Segredos e depois selecione Gerar segredo.

   

2. Em Validade (dias), insira quanto tempo o segredo é válido. O máximo é 730 dias.

3. Em Escopo, selecione Outras APIs, selecione Adicionar escopo e então selecione all-apis.

   

4. Selecione Gerar.

5. Copie o segredo e o ID do cliente, e então selecione Concluído.

O diálogo marca all-apis como não recomendado. Os direitos do principal de serviço e as permissões do agente Genie ainda limitam o que o Agente 365 pode ler. Anote a data de validade do segredo para que você possa rotacioná-lo antes que expire.

Dê ao service principal acesso aos agentes Genie

O Agente 365 sincroniza e monitora apenas os agentes Genie que o service principal pode acessar. Escolha uma das opções a seguir.

Compartilhe Genie agents com a entidade de serviço

Essa opção é recomendada porque concede acesso apenas aos agentes Genie que você escolher.

1. No espaço de trabalho Databricks, selecione Agentes Genie na barra lateral e então abra um agente Genie.
2. Selecione Compartilhar.
3. Insira o nome do principal de serviço, selecione Adicionar e então defina o nível de permissão. Para coletar atividade, selecione Tem permissão para gerenciar.
4. Repita esses passos para cada agente Genie que você deseja sincronizar.

O nível de permissão determina o que o Agente 365 pode fazer:

A atividade exige Pode gerenciar. O Databricks retorna as conversas de todos os usuários de um agente Genie apenas para as entidades que têm a permissão Can Manage. Com uma permissão de nível inferior, o agente sincroniza, mas nenhuma atividade aparece.

Depois de compartilhar um agente Genie, pode levar um ou dois minutos até que o service principal possa listá-lo.

Torne o service principal um administrador do workspace

Para cobrir todos os agentes Genie no workspace, incluindo agentes Genie que são criados posteriormente, ative o acesso de Administrador para o principal de serviço em vez de compartilhar os agentes Genie individualmente.

1. Na página de detalhes do principal de serviço, selecione a aba Configurações .
2. Selecione Acesso de administrador e depois selecione Atualizar. O Databricks adiciona o principal de serviço ao grupo do espaço de trabalho admins.
3. Para confirmar, vá em Configurações>de Identidade e acesso. Ao lado de Grupos, selecione Gerenciar. Abra o grupo admins e verifique se o principal do serviço está listado na aba Membros.

Mudanças de permissão podem levar alguns minutos para serem aplicadas.

Criar a conexão

1. Abra o Centro de administração do Microsoft 365.

2. Selecione Agentes>Todos os agentes.

3. Nas plataformas conectadas, selecione Gerenciar.

4. Selecione + Conectar uma plataforma.

5. Insira um nome e uma descrição para a conexão.

6. Na plataforma externa, selecione Databricks Genie. O método de autenticação é OAuth (principal de serviço).

7. Insira a URL do Workspace, ID do Cliente e o Segredo do Cliente.

8. Certifique-se de que Dados de observabilidade do agente esteja selecionado.

9. Selecione Verificar autenticação.

10. Quando Conexão verificada com sucesso aparecer, selecione Salvar.

    

A verificação confirma que o Agente 365 pode entrar no espaço de trabalho e listar os agentes Genie. A operação é bem-sucedida mesmo que o principal do serviço ainda não consiga acessar nenhum agente Genie.

Sincronizar agentes

Quando você salva a conexão, o painel de detalhes se abre e inicia a primeira sincronização. Quando a sincronização termina, o painel mostra **Sync

O Agente 365 sincroniza todos os agentes Genie que o principal de serviço pode acessar. Agentes sincronizados aparecem no registro de agentes do Microsoft 365. Para encontrá-los, vá em Agentes>Todos os agentes e filtre Plataforma pelo Databricks Genie. Eles também aparecem em um cluster Genie de Databricks no mapa do Agente.

Para sincronizar após criar ou compartilhar mais agentes Genie, abra a conexão e selecione Sincronizar agentes.

Verificar atividade

1. No Databricks, abra um agente Genie sincronizado e faça algumas perguntas a ele. Pule essa etapa se o agente já tem conversas recentes.

2. No Centro de administração do Microsoft 365, abra o agente na lista de agentes sincronizados da conexão ou em Agents>All agents.

3. Selecione a aba Atividade. Quando a atividade é coletada, Sessões mostra uma ou mais sessões.

   

A atividade pode levar algum tempo para surgir após uma conversa. O Databricks não fornece identidades de usuário do Microsoft Entra, então usuários ativos mostra N/A. Para definições de métricas, consulte Observabilidade de agente de terceiros (Frontier).

Rotacionar ou revogar acesso

Para rotacionar o segredo do cliente:

1. No Databricks, gere um novo segredo OAuth para a entidade de serviço. Um principal de serviço pode ter até cinco segredos, então você pode criar o novo segredo antes de deletar o antigo.
2. No centro de administração do Microsoft 365, abra a conexão e selecione Editar. Insira o novo segredo do cliente, selecione Verificar autenticação e então salve a conexão.
3. No Databricks, exclua o segredo antigo da aba Segredos do principal do serviço.

Para revogar o acesso:

• Para impedir o acesso a um agente Genie específico, remova o service principal das configurações de compartilhamento do agente Genie.
• Para impedir todo acesso, exclua os segredos OAuth do principal de serviço ou remova o principal de serviço do workspace.

Troubleshoot

Teste as credenciais fora do Agent 365

Se a verificação continuar falhando, um administrador do Databricks pode testar as credenciais diretamente. Defina as variáveis de ambiente DATABRICKS_CLIENT_ID e DATABRICKS_CLIENT_SECRET e depois solicite um token de acesso da área de trabalho. Substitua <workspace-host> pelo host da URL do workspace.

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

Uma resposta bem-sucedida é um objeto JSON que contém um valor access_token e um token_type de Bearer. Para verificar quais agentes Genie o principal de serviço pode acessar, defina a DATABRICKS_TOKEN variável de ambiente para o access_token valor e então liste os agentes Genie:

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

Não salve nem compartilhe o token de acesso.

Para problemas de conexão que não são específicos do Databricks Genie, veja Solucionar problemas em plataformas conectadas.