Receber insights com o agente Data Insights

O agente de insights de dados é um agente criado pelo Google. Ele oferece insights de dados do BigQuery. Com o agente Data Insights, você não precisa ter conhecimento prévio de SQL. Assim, você toma decisões de negócios bem fundamentadas e baseadas em dados, além de liberar os analistas de dados para se concentrarem em tarefas mais complexas.

Nesta página, descrevemos como um administrador de projetos do Google Cloud pode autorizar, criar e implantar o agente do Data Insights usando o consoleGoogle Cloud e a API REST. Esta página também mostra como um usuário final pode usar o agente.

Visão geral

O agente do Data Insights foi projetado para fazer o seguinte:

  • Entender a intenção do usuário: analisa o contexto das fontes de dados conectadas e a consulta em linguagem natural do usuário para entender o objetivo dele.
  • Gerar SQL: com base nesse entendimento, ele converte a pergunta do usuário em uma consulta SQL sintática e semanticamente correta.
  • Recuperar dados: em seguida, ele executa o SQL gerado para buscar os dados relevantes diretamente da fonte de dados conectada, um conjunto de dados do BigQuery.
  • Fornecer insights: apresenta os dados recuperados como visualizações, como gráficos e tabelas, ou como resumos baseados em texto para responder à consulta do usuário.

Exemplos de consultas que você pode fazer ao agente do Data Insights

Confira alguns exemplos de consultas que você pode fazer ao agente de insights de dados:

  • Agregação e visualização de dados:
    • "Como as vendas do segundo trimestre deste ano na região da América Latina se comparam com as do segundo trimestre do ano passado?"
    • "Crie um gráfico de barras mostrando a comparação de cada um dos cinco principais países da região."
  • Análise de tendências:
    • "Como o volume de chamadas feitas variou nos últimos seis meses, dividido por local?"
    • "Analise os padrões de reserva dos hotéis em Lisboa com classificação superior a 3 estrelas"
  • Mineração de dados:
    • "Quais fatores estão correlacionados com o valor total das vendas quando um cliente compra algo? Mostre um mapa de calor com a relação."
  • Análise e relatórios:
    • "Resuma a tabela de oportunidades e contas e crie um relatório curto destacando as principais tendências."

Antes de começar

Para começar a usar o agente Data Insights no Gemini Enterprise, siga estas etapas:

Conceder acesso aos dados do BigQuery

Para permitir que o agente do Data Insights veja e consulte os dados do BigQuery, conceda os papéis do Identity and Access Management (IAM) aos usuários do agente:

Fluxo de trabalho

O fluxo de trabalho geral para configurar e usar o agente do Data Insights é o seguinte:

Receber detalhes da autorização

Siga estas etapas para configurar a autorização. Os detalhes obtidos são necessários para autorizar o agente do Data Insights a se conectar aos dados do BigQuery.

  1. No console Google Cloud , acesse a página Credenciais em APIs e serviços.

    Ir para Credenciais

  2. Selecione o projeto Google Cloud que contém o conjunto de dados do BigQuery que você quer que o agente consulte.

  3. Clique em Criar credenciais e selecione ID do cliente do Oauth.

  4. Em Tipo de aplicativo, selecione Aplicativo da Web.

  5. Na seção URIs de redirecionamento autorizados, adicione os seguintes URIs:

    • https://vertexaisearch.cloud.google.com/oauth-redirect
    • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

  6. Clique em Criar.

  7. No painel Cliente OAuth criado, clique em Fazer o download do JSON. O JSON baixado inclui os seguintes detalhes para o projetoGoogle Cloud selecionado. Você precisa desses detalhes para criar um recurso de autorização:

    • ID do cliente: CLIENT_ID
    • URI de autorização: 
      https://accounts.google.com/o/oauth2/v2/auth?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
    • URI do token: https://oauth2.googleapis.com/token
    • Secret do cliente: CLIENT_SECRET

Configurar o agente usando o console Google Cloud

Nesta seção, mostramos como autorizar, criar e implantar uma instância do agente do Data Insights usando o console Google Cloud . Você também pode adicionar permissões de usuário que determinam quem pode acessar o agente criado.

Autorizar e criar uma instância de agente

Autorize e crie uma instância do agente do Data Insights seguindo estas etapas:

  1. No console Google Cloud , acesse Gemini Enterprise.

    Acessar o Gemini Enterprise

  2. Selecione um app em que você quer criar o agente.

  3. No menu, clique em Agentes.

    A página Agentes mostra os agentes atuais.

  4. Clique em Adicionar agente.

  5. No painel Criar agente, clique em Criar no card Agente de dados.

  6. Em Autorizações, clique em Adicionar autorização e insira os detalhes. Para mais informações, consulte Receber autorização.

  7. Clique em Concluído.

  8. Clique em Próxima.

  9. Configure seu agente da seguinte maneira:

    1. Insira o nome e a descrição do agente.
    2. Em Conjunto de dados do BigQuery, clique em Procurar e faça uma das seguintes ações:
      • Selecione um conjunto de dados disponível e clique em Selecionar.
      • Insira o caminho para o conjunto de dados do BigQuery necessário, clique em Pesquisar, selecione-o e clique em Selecionar.

    3. Opcional: clique em Mostrar mais para ver as opções avançadas.

    4. Selecione as opções corretas de acesso à tabela. Se você quiser impor uma lista de permissões ou uma lista de bloqueio, especifique os caminhos para as tabelas restritas.

    5. Opcional: defina a configuração de consulta em linguagem natural para fornecer personalizações específicas de uma tradução em linguagem natural para código SQL ou Python. Você também pode fornecer um exemplo de SQL usando uma consulta em linguagem natural, a saída de SQL esperada e a resposta esperada. Isso melhora a qualidade das respostas do agente.

      • Descrição do esquema: uma string em linguagem natural que descreve o esquema do conjunto de dados do BigQuery.
      • Consulta em linguagem natural para o comando SQL: uma consulta em linguagem natural transformada em uma instrução SQL.
      • Consulta em linguagem natural para o comando do Python: uma consulta em linguagem natural transformada em uma instrução do Python.

    6. Opcional: adicione exemplos de consultas em linguagem natural transformadas em consultas SQL:

      • Consulta: um exemplo de consulta natural que precisa ser convertida em uma consulta SQL. Por exemplo, "Quais são os nomes e endereços de e-mail dos clientes na Califórnia?"
      • SQL esperado: uma string que ilustra um exemplo de consulta SQL correspondente à consulta em linguagem natural. Por exemplo, suponha que você tenha uma tabela do BigQuery chamada customers. Então, sua consulta SQL esperada pode ser SELECT customer_name, email FROM customers WHERE state = 'California'.
      • Resposta esperada: uma string que fornece a resposta esperada para a consulta executando a consulta SQL esperada. Exemplo:
      Here are the names and email addresses of your customers in California: \
* Customer name: Lara B, Email address: 222larabrown@gmail.com \
* Customer name: Alex A, Email address: baklavainthebalkans@gmail.com \
* Customer name: Bola C, Email address: cloudysanfrancisco@gmail.com \

  10. Clique em Criar.

    A instância do agente do Data Insights aparece na lista Agentes.
    Para começar a trabalhar com o agente, aguarde até que a coluna Estado do agente mostre Ativado para sua instância.

Configurar o agente usando a API REST

Esta seção descreve como autorizar, criar e implantar uma instância do agente do Data Insights usando a API REST.

Autorizar o agente

Como administrador, crie um recurso de autorização no Gemini Enterprise. Isso permite que o agente de insights de dados acesse os dados do BigQuery.

  1. Crie o recurso de autorização.

    REST

    O exemplo a seguir mostra como criar um recurso de autorização usando o método authorizations.create.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 -H "X-Goog-User-Project: PROJECT_NUMBER" \
 "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTHORIZATION_ID" \
 -d '{
   "name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTHORIZATION_ID",
   "serverSideOauth2": {
     "clientId": "CLIENT_ID",
     "clientSecret": "CLIENT_SECRET",
     "authorizationUri": "AUTHORIZATION_URI",
     "tokenUri": "https://oauth2.googleapis.com/token"
}
}'

    Substitua:

    • PROJECT_NUMBER: o número do projeto Google Cloud .
    • LOCATION: o local do projeto Google Cloud .
    • AUTHORIZATION_ID: um ID que você precisa fornecer para identificar o recurso de autorização.
    • CLIENT_ID: o ID do cliente que você recebeu na etapa anterior.
    • CLIENT_SECRET: a chave secreta do cliente que você recebeu na etapa anterior.
    • AUTHORIZATION_URI: o URI de autorização que você conferiu na etapa anterior.

Criar uma instância de agente

Como administrador do projeto Google Cloud , você pode criar uma instância do agente do Data Insights. Isso exige o ID do projeto e do conjunto de dados do BigQuery que você quer consultar usando o agente.

REST

O exemplo a seguir mostra como criar uma instância de agente do Data Insights usando o método agents.create. Para saber mais sobre os campos avançados que podem ser adicionados a essa amostra, consulte Adicionar configurações avançadas para o agente.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
  -d '{
    "displayName": "AGENT_DISPLAY_NAME",
    "description": "AGENT_DESCRIPTION",
    "icon": {
       "uri": "AGENT_ICON_URI"
     },
    "managed_agent_definition": {
      "tool_settings": {
        "tool_description": "AGENT_DESCRIPTION"
      },
      "data_science_agent_config": {
        "bq_project_id": "BIGQUERY_PROJECT_ID",
        "bq_dataset_id": "BIGQUERY_DATASET_ID"
      }
    },
    "authorization_config": {
      "tool_authorizations" : [
        "AUTHORIZATION_RESOURCE_NAME"
      ]
    }
  }'

Substitua:

  • PROJECT_NUMBER: o número do projeto Google Cloud .
  • LOCATION: o local do seu app Gemini Enterprise.
  • APP_ID: o ID do app.
  • AGENT_DISPLAY_NAME: o nome da sua instância do agente do Data Insights.
  • AGENT_ICON_URI: um campo opcional para fornecer um URI para o ícone do agente.
  • AGENT_DESCRIPTION: uma descrição da sua instância do agente do Data Insights que indica a finalidade do agente ou os detalhes da fonte de dados do BigQuery.
  • BIGQUERY_PROJECT_ID: o ID do projeto do Google Cloud projeto que contém o conjunto de dados do BigQuery.
  • BIGQUERY_DATASET_ID: o ID do conjunto de dados do BigQuery que contém os dados a serem consultados.
  • AUTHORIZATION_RESOURCE_NAME: o nome do recurso de autorização que você recebeu na seção anterior.

Adicionar configurações avançadas para o agente

Você também pode definir o campo nlQueryConfig para fornecer personalizações específicas para a tradução de linguagem natural em código SQL ou Python. Você também pode fornecer um exemplo de SQL usando uma consulta em linguagem natural, a saída SQL esperada e a resposta esperada. Isso melhora a qualidade das respostas do agente. O snippet de código a seguir mostra como configurar esses campos avançados:

"dataScienceAgentConfig": {
  "nlQueryConfig": {
    "nl2sqlPrompt": "NL_TO_SQL_INSTRUCTIONS",
    "nl2pyPrompt": "NL_TO_PYTHON_INSTRUCTIONS",
    "nl2sqlExample": {
      "query": "EXAMPLE_NL_QUERY",
      "expectedSql": "EXPECTED_SQL_QUERY",
      "expectedResponse": "EXPECTED_SQL_RESPONSE"
    },
    "schemaDescription": "NL_DESCRIPTION_OF_BQ_DATASET"
  }
}

Substitua:

  • NL_TO_SQL_INSTRUCTIONS: uma consulta em linguagem natural transformada em uma instrução SQL.
  • NL_TO_PYTHON_INSTRUCTIONS: uma consulta em linguagem natural transformada em uma instrução do Python.
  • EXAMPLE_NL_QUERY: um exemplo de consulta em linguagem natural que precisa ser convertida em uma consulta SQL. Por exemplo, "Quais são os nomes e endereços de e-mail dos clientes da Califórnia?"
  • EXPECTED_SQL_QUERY: uma string que ilustra um exemplo de consulta SQL correspondente à consulta natural. Por exemplo, suponha que você tenha uma tabela do BigQuery chamada customers. Então, a consulta SQL esperada pode ser "SELECT customer_name, email FROM customers WHERE state = 'California'".

  • EXPECTED_SQL_RESPONSE: uma string que fornece a resposta esperada para a consulta e a consulta SQL esperada. Exemplo:

    Here are the names and email addresses of your customers in California: \
* Customer name: Lara B, Email address: 222larabrown@gmail.com \
* Customer name: Alex A, Email address: baklavainthebalkans@gmail.com \
* Customer name: Bola C, Email address: cloudysanfrancisco@gmail.com \

  • NL_DESCRIPTION_OF_BQ_DATASET: uma string em linguagem natural que descreve o esquema do conjunto de dados do BigQuery.

Implante a instância

Depois de criar a instância do agente do Data Insights, como administrador, você pode implantá-la para que os usuários finais possam usá-la.

REST

  1. Implante o agente. O exemplo a seguir mostra como implantar o agente criado usando o método agents.deploy. A implantação do agente é uma operação de longa duração (LRO).

    curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 -H "X-Goog-User-Project: PROJECT_NUMBER" \
 "https://discoveryengine.googleapis.com/v1alpha/AGENT_RESOURCE_NAME:deploy" \
 -d '{
   "name":"AGENT_RESOURCE_NAME"
 }'

    Substitua:

    • PROJECT_NUMBER: o número do projeto Google Cloud .
    • AGENT_RESOURCE_NAME: o nome do recurso do agente que você recebeu na seção anterior ao criar o agente.

  2. Confira o status da operação de implantação. A amostra a seguir mostra como receber o status da operação de implantação operations.get método.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://discoveryengine.googleapis.com/v1alpha/DEPLOY_OPERATION_NAME"

    Substitua DEPLOY_OPERATION_NAME pelo nome da LRO obtido na etapa anterior ao implantar o agente.

    Na resposta, se o valor do campo done for true, a implantação será concluída. Se o valor do campo done for false, a implantação estará em andamento.

Adicionar ou modificar usuários e permissões

Adicione ou modifique participantes na sua instância do agente do Data Insights e atribua papéis específicos do Identity and Access Management (IAM) a eles seguindo estas etapas:

Console

  1. No console Google Cloud , acesse Gemini Enterprise.

    Acessar o Gemini Enterprise

  2. Selecione um app que contenha sua instância do agente do Data Insights.

  3. No menu, clique em Agentes.

    A página Agentes mostra os agentes atuais.

  4. Clique no agente para adicionar ou modificar usuários. Por exemplo, clique na instância Agente de insights de dados.

    Por padrão, um agente recém-criado não tem usuários.

    data-insights-agent
    Clique na instância do agente de insights de dados

  5. Clique em Permissões do usuário.

  6. Na tabela Usuários com permissão, clique em Adicionar usuário.

    add-user
    Navegar para adicionar um usuário

  7. Selecione um Tipo de membro na lista disponível:

    • Para um Usuário ou Grupo, insira o endereço de e-mail como a string de membro e selecione uma função.

    • Para um pool de identidades de colaboradores, insira um principal válido como a string de membro e selecione uma função.

    • Em Todos os usuários, selecione uma função.

    member-type
    Selecione um tipo de membro

  8. Clique em Salvar.

    A política do IAM é atualizada, e o usuário é adicionado à lista de usuários com permissão.

  9. Para excluir as permissões atribuídas, clique em na coluna Ações e em Excluir.

    excluir
    Remover uma função

Mudar o estado de funcionamento da instância

Depois de criar a instância do agente Data Insights, ele é ativado por padrão. Você pode mudar o estado de funcionamento para Visualizar, Desativar, Suspender ou Excluir seguindo estas etapas:

Console

  1. No console Google Cloud , acesse Gemini Enterprise.

    Acessar o Gemini Enterprise

  2. Selecione um app que contenha sua instância do agente do Data Insights.

  3. No menu, clique em Agentes.

    A página Agentes mostra os agentes atuais.

  4. Clique em na coluna Ações dos seus agentes e selecione uma das seguintes opções:

    • Prévia: para abrir o agente em uma nova guia.
    • Desativar: para tornar o agente indisponível para todos os usuários, exceto aquele que o criou.
    • Suspender: tornar o agente temporariamente indisponível para uso. No entanto, os usuários com qualquer grau de permissão para o agente de acesso ainda podem vê-lo.
    • Excluir: para excluir a instância do agente.
    actions
    Selecione uma das ações para seu agente.

Usar o agente

Siga estas etapas para receber insights de dados usando seu agente:

App

  1. No menu de navegação do app, clique em Agentes.

  2. Clique em View all agents.

    view-all-agent
    Ver todos os agentes

  3. Selecione um agente na lista exibida ou na lista recente.

    data-insights-agent
    Escolha sua instância de agente

  4. Se o agente precisar de mais autorização, clique em Autorizar e forneça os detalhes da autorização.

  5. Na caixa de pesquisa, faça o seguinte:

    • Clique no ícone para adicionar arquivos como fontes de dados extras para o agente trabalhar.

    • Clique no ícone para gerenciar seus dados.

  6. Digite suas perguntas ou comandos e pressione Enter.