Criar e gerenciar um agente do Genie

Crie, compartilhe e gerencie um Agente do Genie, a interface de chat em linguagem natural que os usuários empresariais usam para fazer perguntas sobre seus dados em Azure Databricks. Os analistas de dados configuram cada agente com o Unity Catalog, exemplos de consultas SQL, instruções e ativos confiáveis; os usuários de negócio fazem consultas a ele pela interface de chat.

Requisitos técnicos e limites

Os seguintes requisitos e limites se aplicam ao usar o Genie Agents:

• Catálogo do Unity: Os dados do Agente do Genie devem ser registrados no Catálogo do Unity. Você pode adicionar até 30 tabelas ou views a um Genie Agent.
• Calcular: Os Agentes do Genie exigem um sql warehouse profissional ou sem servidor. Ao criar ou configurar um Agente do Genie, você deve ter pelo menos a permissão CAN USE no armazém selecionado. Suas credenciais de computação estão incorporadas ao Agente Genie para fornecer acesso ao warehouse a todos os usuários. O acesso a dados é sempre avaliado usando as próprias permissões do Catálogo Unity de cada usuário final. Veja como funciona o acesso a dados.
• Capacidade: Cada Agente do Genie pode dar suporte a até 10.000 conversas e cada conversa pode incluir até 10.000 mensagens.

Permissões necessárias

Para criar ou editar um Agente do Genie, você deve ter as seguintes permissões e direitos:

• Permissões: Você deve ter a permissão de acesso ao workspace do Databricks SQL. Consulte Gerenciar direitos.
• Computação: PODE USAR o acesso a pelo menos um SQL Warehouse profissional ou sem servidor.
• Acesso a dados:SELECT privilégios nos dados usados no agente.
• ACLs do Agente do Genie: pelo menos permissões CAN EDIT no Agente do Genie. Os criadores do Genie Agent têm automaticamente permissões CAN MANAGE em agentes criados por eles. Consulte ACLs do Genie Agent.

Gerenciar o acesso do Genie

O Genie utiliza funcionalidades de IA impulsionadas por parceiros, que devem ser ativadas nos níveis de conta e espaço de trabalho. Para saber como gerenciar esses recursos para sua conta, consulte os recursos de IA habilitados para parceiros.

Criar um agente Genie

Para criar um Agente Genie:

1. Clique em Agentes do Genie na barra lateral.
2. Clique em Novo no canto superior direito da tela.
3. Escolha as fontes de dados que você deseja incluir no agente do Genie. Em seguida, clique em Criar.

Configurar um agente com o Genie Code

Quando você cria um agente, o Genie Code é iniciado automaticamente. Ele lê seus dados e sugere um contexto que ajuda o Genie a responder perguntas com precisão, como descrições de suas tabelas e consultas de exemplo. Examine as sugestões e aceite as que você deseja manter. Para preencher uma lacuna específica, descreva o contexto que você deseja adicionar ao Genie Code.

Create a Genie agent for our sales team that answers questions about weekly revenue, units sold, and returns by store and region. Use the sales and store tables in the retail catalog.

Você também pode pedir ao Genie Code para criar um agente para você quando ainda não souber quais tabelas usar. Descreva seu domínio de negócios, as perguntas que você deseja que o agente responda e os dados que ele deve usar. O Genie Code identifica dados relevantes, confirma as fontes com você e cria o agente com o mesmo contexto inicial.

Antes de compartilhar o agente com os usuários, o Databricks recomenda adicionar exemplos de consultas SQL, instruções e configurações do repositório de conhecimento para melhorar a precisão da resposta. Veja a qualidade do Agente do Tune Genie.

Examinar sugestões de consulta

Para entender melhor os dados do seu agente, o Genie acessa informações no seu espaço de trabalho para compreender melhor os relacionamentos entre as tabelas e a semântica do seu negócio. Quando você adiciona ativos de dados a um agente, o Genie pesquisa automaticamente consultas populares relevantes do espaço de trabalho associadas a esses ativos. Suas credenciais de usuário são usadas para localizar consultas relevantes para as quais você tem pelo menos permissões CAN VIEW. Se a pesquisa retornar consultas, uma notificação será exibida na guia Dados do painel Instruções . Clique em Examinar para ver as consultas sugeridas.

Para obter mais informações sobre permissões de acesso à consulta, consulte ACLs de consulta.

Use a caixa de diálogo Revisar Consultas Sugeridas para examinar, editar, aceitar ou rejeitar as consultas sugeridas. Outros usuários com pelo menos acesso CAN EDIT no Agente do Genie podem revisar as consultas, desde que tenham pelo menos acesso CAN VIEW na própria consulta.

1. O texto título é pré-preenchido com uma pergunta. Revise ou edite a pergunta digitando no campo Título .
2. O campo Código contém o texto completo da consulta SQL sugerida. Este campo não é editável. Para exibir a consulta completa, clique em ... mais linhas.
3. Se você tiver permissões suficientes na consulta, pode clicar em consulta SQL para abrir a consulta na UI de histórico de consultas. Veja Visualizar histórico de consultas.
4. Depois de determinar se a consulta é relevante para seu agente, clique em Aceitar ou Rejeitar para adicioná-la ao seu agente ou ignorar a sugestão adequadamente.
5. Clique nas outras sugestões para expandir e revisar.

As consultas aceitas aparecem no contexto de Consultas SQL para o agente. Depois que eles são adicionados ao agente, as consultas sugeridas e as perguntas associadas são totalmente editáveis. Consulte Adicionar consultas e funções SQL de exemplo.

Se nenhuma consulta sugerida for retornada:

• Talvez você não tenha acesso suficiente a consultas relevantes.
• Pode não haver dados relevantes. Se as consultas não tiverem sido executadas em suas tabelas incluídas, a pesquisa poderá não retornar resultados.
• Consultas irrelevantes para o Agente Genie não são consideradas. Por exemplo, consultas que executam apenas operações básicas de gravação nos ativos incluídos não são consideradas exemplos relevantes para o Genie.
• O Genie não sugere consultas em tabelas que não foram adicionadas ao agente. Se você criou tabelas ou exibições unidas especificamente para o Genie Agent, mas consultas SQL relevantes do Databricks normalmente são executadas em uma tabela de origem diferente, o Genie não retorna essas consultas nos resultados.

Gerenciar objetos de dados

Para gerenciar quais objetos de dados estão incluídos em um Agente do Genie, clique em Configurar>Dados. Clique no botão Adicionar para adicionar mais tabelas. Clique no à direita do nome da tabela para remover uma tabela do agente.

Para exibir detalhes sobre um objeto de dados, clique no nome do objeto. A exibição do objeto de dados mostra duas guias:

• Visão geral: mostra as colunas no objeto de dados, incluindo nomes de coluna, tipos de dados e descrições.
• Dados de exemplo: mostra dados de exemplo da tabela para ajudá-lo a entender o contexto e o conteúdo dos dados.

Definir configurações

Personalize o agente do Genie definindo configurações adicionais. Clique em Definir>Configurações para acessar as seguintes configurações:

• Título: O título aparece no navegador da área de trabalho com outros objetos da área de trabalho. Escolha um título que ajudará os usuários finais a descobrir o agente do Genie.
• Warehouse padrão: esse recurso de computação alimenta as instruções SQL geradas no Genie Agent. Quando você salva uma seleção de warehouse, suas credenciais de computação são integradas ao Agente Genie para fornecer acesso ao warehouse a todos os usuários. Essas credenciais incorporadas concedem acesso apenas ao depósito. O acesso a dados é sempre avaliado usando as próprias permissões do Catálogo Unity de cada usuário final. Você precisa ter pelo menos permissões CAN EDIT no agente para alterar o warehouse. Se um autor diferente alterar o warehouse mais tarde, suas credenciais de computação serão incorporadas. Um Agente do Genie pode usar um SQL Warehouse profissional ou sem servidor. Para um desempenho ideal, o Databricks recomenda usar um warehouse SQL sem servidor.
• Tags: Use tags para organizar e categorizar os Genie Agents para facilitar seu gerenciamento. Veja Adicionar tags.
• Miniatura: Adicione uma imagem em miniatura ao agente Genie. As miniaturas aparecem na página de chat inicial do Agente do Genie e no Genie One.
• Descrição: os usuários veem a descrição quando abrem o Agente do Genie. Use essa área de texto para descrever a finalidade do agente. O campo de descrição dá suporte à formatação markdown para que você possa definir o estilo do texto e fornecer links para referências e contexto úteis. Para obter mais informações sobre a sintaxe Markdown, consulte o guia rápido do Guia de Markdown.
• Perguntas comuns: perguntas comuns são exemplos opcionais dos tipos de perguntas que os usuários podem fazer. Eles aparecem na página inicial do chat do agente e podem ser adicionados durante a criação ou posteriormente em Configurações do agente. As perguntas comuns definidas pelo autor têm prioridade e aparecem primeiro. Quando você adiciona perguntas frequentes suficientes para preencher a página inicial do chat, apenas as suas perguntas são exibidas. Quando você fornece menos, o Genie preenche os slots restantes com perguntas geradas automaticamente.

É de se esperar que você faça iterações no seu Agente Genie com base em testes e no uso. Para obter orientações sobre as práticas recomendadas para criar e iterar em um agente, consulte Selecionar um Agente do Genie eficaz.

Adicionar etiquetas

Você deve ter pelo menos a permissão CAN EDIT em um Genie Agent para adicionar uma tag. Para adicionar uma etiqueta governada, você também deve possuir a permissão ASSIGN para a etiqueta governada. Para obter mais informações sobre marcas, consulte Aplicar marcas a objetos protegíveis do Catálogo do Unity.

1. Clique em Definir>Configurações.

2. Clique em Geral.

3. Em Marcas, adicione ou atualize uma marca:

   • Se não houver marcas, clique no botão Adicionar marcas.
   • Se houver marcas, clique no ícone Adicionar/Editar marcas.

4. Selecione uma tag existente de Key e Value ou insira o nome de uma nova tag.

   • As marcações que são controladas estão no cabeçalho da seção Controladas e têm um ícone de cabeçalho.
   • As chaves de etiquetas são obrigatórias. A necessidade de um valor de etiqueta depende da chave da etiqueta.

Compartilhar um Agente do Genie

Para restringir os dados que cada usuário pode ver no mesmo Agente do Genie, aplique a segurança em nível de linha às tabelas subjacentes no Catálogo do Unity. Filtros de linha e máscaras de coluna definidos no Unity Catalog são aplicados automaticamente para cada usuário, independentemente de como o Agente Genie é compartilhado. Veja Filtros de linha e máscaras de coluna.

Quando você compartilha um Agente do Genie, os usuários devem ter as seguintes permissões para interagir com o agente:

• Direitos: o acesso do consumidor ou o direito ao workspace do Databricks SQL. Consulte Gerenciar direitos.
• Calcular: As consultas são executadas usando as credenciais de computação inseridas pelo autor que configurou o warehouse. Os usuários finais não precisam de permissões diretas do warehouse.
• Acesso a dados: pelo menos os privilégios SELECT em todos os objetos de dados do Unity Catalog usados no agente. Os usuários só veem dados que têm permissão para acessar.
• ACLs do Agente do Genie: Pelo menos PODE EXIBIR/PODE EXECUTAR permissões no Agente do Genie. Consulte ACLs do Genie Agent.

Novos Agentes do Genie são salvos na pasta do usuário por padrão. Assim como outros objetos do espaço de trabalho, eles herdam permissões de sua pasta envolvente. Você pode usar a estrutura de pastas do workspace para compartilhá-las com outros usuários. Consulte o navegador do espaço de trabalho.

Você também pode especificar determinados usuários ou grupos (incluindo todos os usuários da conta) para compartilhar em um determinado nível de permissão: PODE GERENCIAR, PODE EDITAR, PODE EXECUTAR e PODE EXIBIR.

Para compartilhar com usuários ou grupos específicos:

1. Clique em Compartilhar.
2. Insira os usuários ou grupos com os quais você deseja compartilhar o agente. Em seguida, clique em Adicionar e definir os níveis de permissão apropriados. Usuários individuais e membros de grupos pequenos recebem uma notificação por email confirmando que o agente foi compartilhado.
3. Use o botão Copiar link na parte inferior da caixa de diálogo Compartilhar para obter um link compartilhável para o Agente do Genie. Usuários privilegiados podem clicar no link para abrir o Agente do Genie em uma nova guia e fazer perguntas.

Para compartilhar com todos os usuários da conta:

1. Clique em Compartilhar.
2. Selecione Todos os usuários da conta.
3. Defina o nível de permissão apropriado.

Os usuários do agente também podem compartilhar conversas individuais. Consulte Compartilhar uma conversa.

Para compartilhar um agente do Genie com usuários de fora da sua organização usando o OpenSharing, consulte Compartilhar um agente do Genie usando o OpenSharing.

Mais ações do agente

O menu de três pontos no canto superior direito de um agente oferece as ações a seguir.

Clonar um Agente do Genie

A clonagem de um agente do Genie cria uma cópia que inclui todo o contexto de instalação e instruções. A clonagem é útil quando você deseja testar alterações em um agente separado ou reutilizar o contexto original em um novo. Depois que um agente é clonado, o novo agente é independente do original. Você pode fazer edições e ajustes sem afetar o original.

Os seguintes elementos são copiados para um Agente Genie clonado:

• Tabelas e configurações
• Instruções gerais
• Exemplo de consultas SQL
• Funções do SQL

Os threads de chat e os dados existentes da guia Monitor não são copiados para o novo agente.

Para clonar um Agente do Genie, faça o seguinte:

1. Abra o Agente do Genie que você deseja clonar.
2. Clique no menu de três pontos no canto superior direito do agente.
3. Clique em Clonar.
4. (Opcional) Na caixa de diálogo Clonar , especifique um novo nome e um local de pasta de workspace para o Agente Genie clonado.
5. Clique em Clonar para criar o novo agente.

Exportar um Agente do Genie como uma exibição de métrica

Você pode exportar o contexto de um agente Genie como uma visualização de métricas. Isso cria uma exibição de métrica com base nos dados e no contexto semântico configurado no agente.

Para exportar um agente do Genie como uma visualização de métrica, faça o seguinte:

1. Abra o Agente do Genie que você deseja exportar.
2. Clique no menu de três pontos no canto superior direito do agente.
3. Selecione Exportar para exibição de métrica.
4. Selecione o caminho para a nova exibição de métrica.
5. (Opcional) Clique no no canto superior direito da página para abrir o Genie Code e refinar a definição da visualização da métrica.
6. Clique em Criar.

Atribuir certificação a um Agente Gênio

Você pode marcar um Agente Genie como certificado ou obsoleto para indicar seu status de confiança ou ciclo de vida. A certificação utiliza a tag regida pelo Unity Catalog system.certification_status . Para aplicar isso, você deve ter a permissão ASSIGN nessa marcação.

Para atribuir certificação a um Agente Gênio, faça o seguinte:

1. Abra o Agente Gênio que você quer certificar.
2. Clique no menu kebab no canto superior direito do agente e selecione Atribuir certificação.
3. Selecione Certificado, Preterido ou Nenhum.
4. Clique em Salvar.

Para mais informações sobre certificação, incluindo como buscar por status de certificação, veja Dados de bandeira como certificados ou obsoletos.

Recursos adicionais

• Para obter orientações sobre práticas recomendadas e ajuda para solucionar problemas, consulte Como criar um Agente Genie eficaz.
• Para saber como adicionar exemplos de SQL, instruções e definir configurações, consulte a qualidade do Tune Genie Agent.
• Para saber como testar, examinar respostas e monitorar o agente, consulte Testar e monitorar um agente do Genie.
• Para saber como usar logs de auditoria para acompanhar a atividade e o uso em um agente do Genie, consulte os eventos do Genie Agent.
• Consulte Usar a API Genie Agents para saber como importar e exportar agentes do Genie programaticamente e usar a API de conversa do Genie. Consulte também a referência da API do Genie.
• Para saber como criar um sistema de vários agentes usando Agentes Personalizados, consulte Usar o Genie em sistemas multiagente (Model Serving).