Adicionar um recurso do Genie Agent a um aplicativo do Databricks

Adicione Genie Agents como recursos de Databricks Apps para permitir consultas em linguagem natural em seus aplicativos. Os Agentes do Genie fornecem uma interface de conversa para exploração de dados, permitindo que os usuários façam perguntas comerciais em inglês sem formatação e recebam insights baseados em SQL de seus conjuntos de dados coletados.

Quando você adiciona um Agente do Genie como um recurso, seu aplicativo pode:

• Converter consultas de linguagem natural de usuários em SQL
• Acessar o contexto de negócios pré-configurado e os metadados
• Utilize consultas de exemplo e definições de dados curadas
• Gerar respostas com base nos conjuntos de dados da sua organização

Adicionar um recurso do Agente do Genie

Antes de adicionar um Genie Agent como um recurso, examine os pré-requisitos do recurso de aplicativo.

1. Na seção Recursos do aplicativo, ao criar ou editar um aplicativo, clique em + Adicionar recurso>Genie Agent.
2. Escolha um Agente Genie na lista de espaços disponíveis em seu workspace.
3. Selecione o nível de permissão do aplicativo:
   • Pode exibir: Concede permissão ao aplicativo para ler a configuração e os metadados do Genie Agent.
   • Pode executar: Concede ao aplicativo permissão para enviar consultas ao Agente Genie e receber respostas.
   • Pode editar: Concede a permissão do aplicativo para modificar a configuração do Genie Agent.
   • Pode gerenciar: Concede ao aplicativo acesso administrativo completo ao Agente do Genie.
4. (Opcional) Especifique uma chave de recurso personalizada, que é como você faz referência ao Agente do Genie na configuração do aplicativo. A chave padrão é genie-space.

Quando você adiciona um recurso do Genie Agent:

• O Azure Databricks concede ao principal de serviço do seu aplicativo as permissões especificadas no Agente Genie selecionado.
• O aplicativo pode enviar consultas de linguagem natural para o agente e receber respostas estruturadas com consultas e resultados do SQL.
• O aplicativo acessa o contexto de negócios curado do agente, incluindo metadados, consultas de exemplo e definições de dados.
• O acesso é limitado apenas ao agente selecionado. Seu aplicativo não pode acessar outros Agentes do Genie, a menos que você os adicione como recursos separados.

Variáveis de ambiente

Quando você implanta um aplicativo com um recurso Genie Agent, o Azure Databricks expõe o ID do espaço por meio de variáveis de ambiente que você pode referenciar usando o campo valueFrom na sua configuração app.yaml.

Configuração de exemplo:

env:
  - name: GENIE_SPACE_ID
    valueFrom: genie-space # Use your custom resource key if different

Usando a ID de espaço em seu aplicativo:

import os
from databricks.sdk import WorkspaceClient

# Access the Genie Agent using the injected environment variable
space_id = os.getenv("GENIE_SPACE_ID")

# Initialize the workspace client
w = WorkspaceClient()

# Start a conversation with a natural language query
response = w.genie.start_conversation_and_wait(
    space_id=space_id,
    content="What were our top-selling products last quarter?"
)

# Process the response (responses contain attachments with text, queries, and so on)
for attachment in response.attachments:
    print(f"Genie response: {attachment.text.content}")

# Continue the conversation with additional questions
follow_up = w.genie.create_message_and_wait(
    space_id=space_id,
    conversation_id=response.conversation_id,
    content="Can you break that down by product category?"
)

Para obter mais informações, consulte Como acessar variáveis de ambiente dos recursos.

Remover um recurso do Genie Agent

Quando você remove um recurso do Genie Agent de um aplicativo, a entidade de serviço do aplicativo perde o acesso ao agente. O próprio Agente do Genie permanece inalterado e continua disponível para outros usuários e aplicativos que têm permissões apropriadas.

Combinar agentes do Genie com outros recursos de aplicativo

Combine o Genie Agents com outros recursos do Databricks Apps para criar aplicativos de dados mais sofisticados. Os padrões comuns de integração incluem:

Painel de análise de linguagem natural

Use os seguintes recursos juntos para executar análises interativas:

• Agente do Genie: Converte perguntas do usuário em consultas SQL
• SQL Warehouse: Executa as consultas e retorna resultados para visualização
• Segredos: Armazena chaves de API para ferramentas de visualização externas

Configuração de exemplo:

env:
  - name: GENIE_SPACE_ID
    valueFrom: genie-space
  - name: SQL_WAREHOUSE_ID
    valueFrom: sql-warehouse
  - name: EXTERNAL_API_KEY
    valueFrom: viz-secret

Business Intelligence aprimorado por IA

Use os seguintes recursos para se integrar aos modelos de IA:

• Agente do Genie: Gera a consulta inicial e o contexto de dados
• Ponto de extremidade de serviço de modelo: Retorna resumos e recomendações gerados por IA
• SQL Warehouse: Executa consultas analíticas complexas

Permissões do principal de serviço

Conceda ao principal de serviço do aplicativo as seguintes permissões ao integrar-se a outros recursos do aplicativo:

• CAN RUN no Agente Genie
• CAN USE no armazém SQL (se estiver usando um separado daquele do Genie Agent)
• CAN QUERY em endpoints de serviço de modelagem
• USE CATALOG e USE SCHEMA em objetos relevantes do Catálogo Unity
• SELECT em tabelas que o aplicativo consulta diretamente

Práticas recomendadas

Siga estas práticas recomendadas ao trabalhar com recursos do Genie Agent:

• Conceda permissões mínimas. Forneça apenas acesso aos Agentes do Genie específicos que seu aplicativo precisa para funcionar.
• Verifique se o Agente Genie contém conjuntos de dados bem coletados e metadados para melhorar a qualidade das respostas de consulta de linguagem natural.
• Teste as consultas do aplicativo no Genie Agent para validar se ele pode gerar resultados precisos para perguntas esperadas do usuário.
• Monitore o desempenho da consulta e ajuste os padrões de interação do aplicativo com o Agente Genie para otimizar os tempos de resposta.
• Implemente o tratamento de erros para casos em que o Agente Genie não possa interpretar ou responder a consultas de usuário efetivamente.