Receber insights com o agente Data Insights

O agente de insights de dados é um agente do 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 sintaticamente 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 foram as vendas do segundo trimestre deste ano na América Latina em comparação com o 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 efetuadas 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: TOKEN_URI
    • 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 Obter 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ão 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, a 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": "TOKEN_URI"
}
}'

    Substitua:

    • PROJECT_NUMBER: o número do seu 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ê recebeu na etapa anterior.
    • TOKEN_URI: o URI do token que você recebeu 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 o ID 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 este exemplo, 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 seu 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 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 seu 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. O exemplo a seguir mostra como receber o status da operação de implantação operations.get method.

    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 padrão, um agente recém-criado não tem usuários.

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

  6. Selecione um Tipo de membro na lista disponível.

  7. Insira a identidade do participante dependendo do tipo e atribua uma ou mais funções.

    • Para um usuário, grupo ou conta de serviço, a string de membro é um e-mail.
    • Para um domínio, a string de membro é um nome de domínio válido.
    • Para um principal, a string de membro é um principal válido. Por exemplo, principal://iam.googleapis.com/locations/global/workforcePools/pool-1/subject/subject-1.
    • Para um conjunto de principais, a string de membro é um conjunto de principais válido. Por exemplo, principalSet://iam.googleapis.com/locations/global/workforcePools/pool-1/group/group-1.
    • Para domínios e conjuntos de principais, todas as identidades e grupos de usuários dentro desses domínios e conjuntos de principais recebem as mesmas funções. Para um acesso seguro ao agente, selecione grupos individuais e domínios controlados ou conjuntos principais e atribua a eles funções de menor privilégio.

  8. Clique em Salvar.

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

  9. Para modificar as permissões atribuídas, clique em Ações, selecione Modificar e faça uma das seguintes ações:

    • Modifique as funções atribuídas.
    • Adicione um papel diferente.
    • Clique em Excluir para remover uma função. É necessário atribuir pelo menos uma função a um usuário.

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 Desativado, Suspenso, Ativado ou Excluído 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 Ações para seus agentes e selecione uma das seguintes opções:

    • Suspenso: para deixar 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.
    • Desativado: para tornar o agente indisponível para todos os usuários, exceto aquele que o criou.
    • Ativado: para disponibilizar o agente a todos os usuários com qualquer grau de permissão para o agente de acesso.
    • Excluir: para excluir a instância do 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.

  3. Selecione sua instância do agente do Data Insights.

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

  5. Clique em Adicionar arquivos para incluir arquivos como fontes de dados adicionais para o agente trabalhar.

  6. Clique em Fontes para selecionar as fontes que o agente precisa incluir para fornecer os insights de dados mais relevantes.

  7. Digite suas perguntas ou comandos e pressione Enter ou clique em Enviar.