Adicione um recurso de Genie Agent a um aplicativo Databricks

Adicione Genie Agents como recursos do Databricks Apps para habilitar a consulta em linguagem natural em seus aplicativos. Os Genie Agents fornecem uma interface conversacional para exploração de dados, permitindo que os usuários façam perguntas de negócios em inglês simples e recebam percepções baseadas em SQL de seus datasets selecionados.

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

• Converta consultas de linguagem natural dos usuários em SQL
• Acesse o contexto comercial e os metadados pré-configurados
• Use exemplos de consultas e definições de dados selecionadas
• Gerar respostas com base no conjunto de dados de sua organização

Adicionar um recurso do Genie Agent

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

1. Na seção **Recursos do aplicativo** ao criar ou editar um aplicativo, clique em **+ Adicionar recurso** > **Genie Agent**.

2. Escolha um Genie Agent na lista de espaços disponíveis no seu workspace.

3. Selecione o nível de permissão para seu aplicativo:

   • Pode visualizar: Concede à aplicação permissão para ler a configuração e os metadados do Genie Agent.
   • Pode executar: Concede à aplicação permissão para enviar queries ao Genie Agent e receber respostas.
   • Pode editar: Concede ao aplicativo permissão para modificar a configuração do Genie Agent.
   • Pode gerenciar: Concede ao aplicativo acesso administrativo total ao Genie Agent.

4. (Opcional) Especifique uma key de recurso personalizada, que é como você referencia o Genie Agent na configuração do seu aplicativo. A chave default é genie-space.

Ao adicionar um recurso de Genie Agent:

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

nota

A entidade de serviço do aplicativo também precisa de permissões apropriadas nas fontes de dados subjacentes que o Genie Agent consulta. Isso geralmente inclui permissões USE CATALOG, USE SCHEMA e SELECT nas tabelas e views relevantes do Unity Catalog.

variável de ambiente

Quando um aplicativo é implantado com um recurso do Genie Agent, o Databricks expõe o ID do espaço por meio de variáveis de ambiente que é possível referenciar usando o campo valueFrom em sua configuração de app.yaml.

Configuração de exemplo:

YAML

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

Usando o ID de espaço em seu aplicativo:

Python

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 Access variável de ambiente from recurso.

Remover um recurso do Genie Agent

Ao remover um recurso de Genie Agent de um aplicativo, a entidade de serviço do aplicativo perde o acesso ao agente. O próprio Genie Agent permanece inalterado e continua disponível para outros usuários e aplicativos que possuem as permissões apropriadas.

Combine Genie Agents com outros recursos de aplicativo

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

Painel de análise de linguagem natural

Use o recurso a seguir em conjunto com a execução analítica interativa:

• Genie Agent: Converte perguntas do usuário em consultas SQL
• SQL warehouseExecução das consultas e retorno dos resultados para visualização
• Segredos: Armazena a chave API para ferramentas de visualização externas

Configuração de exemplo:

YAML

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

AI-Business Intelligence aprimorado

Use o recurso a seguir para integrar-se aos modelos do site AI:

• **Genie Agent:** Gera a query inicial e o contexto de dados
• servindo modelo endpoint : Devoluções AI-generated summaries and recommendations
• SQL warehouseExecução de consultas analíticas complexas

Permissões da entidade de serviço

Conceda à entidade de serviço do seu aplicativo as seguintes permissões ao integrar-se a outro recurso de aplicativo:

• CAN RUN no Genie Agent
• CAN USE no SQL warehouse (se estiver usando um separado do Genie Agent)
• CAN QUERY no endpoint servindo modelo
• USE CATALOG e USE SCHEMA nos objetos relevantes do Unity Catalog
• SELECT nas tabelas, o aplicativo consulta diretamente

Melhores práticas

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

• Conceda permissões mínimas. Forneça acesso apenas aos Genie Agents específicos de que seu aplicativo precisa para funcionar.
• Garanta que o Genie Agent contenha datasets e metadados bem selecionados para melhorar a qualidade das respostas da consulta em linguagem natural.
• Teste as queries do seu aplicativo com o Genie Agent para validar que ele pode gerar resultados precisos para perguntas esperadas dos usuários.
• Monitore o desempenho da query e ajuste os padrões de interação do seu aplicativo com o Genie Agent para otimizar os tempos de resposta.
• Implemente o tratamento de erros para casos em que o Genie Agent não conseguir interpretar ou responder às queries do usuário de forma eficaz.