Inspecionar e chamar um agente de dados

Este documento descreve como inspecionar um agente e atualizar o arquivo de contexto dele. É possível inspecionar um agente para testar a capacidade dele de gerar consultas SQL a partir de perguntas em linguagem natural. Se uma consulta gerada não for precisa, atualize o contexto do agente.

Para saber mais sobre agentes de dados, consulte Visão geral dos agentes de dados.

Antes de começar

Verifique se um agente de dados já foi criado e se o contexto do agente foi enviado a ele. Para mais informações, consulte Gerenciar agentes de dados no AlloyDB Studio.

Inspecionar um agente de dados

Para inspecionar um agente de dados, siga estas etapas:

  1. No Google Cloud console, acesse a página do AlloyDB.

    Acessar o AlloyDB

  2. Selecione um cluster na lista.

  3. No menu de navegação, clique em AlloyDB Studio.

  4. Faça login no Studio usando a autenticação do Identity and Access Management (IAM).

  5. No painel Explorer, clique em Ver ações ao lado do agente de dados que você está usando.

  6. Clique em Inspecionar agente.

  7. No editor de consultas, clique em Gerar SQL para abrir o painel Me ajude com o código.

  8. Insira uma pergunta em linguagem natural no editor para gerar uma consulta SQL e clique em Gerar.

  9. Analise a consulta SQL para verificar a precisão.

Fazer o download e atualizar o contexto de um agente de dados

Se você não estiver satisfeito com a consulta SQL gerada para uma pergunta em linguagem natural, faça o download do arquivo de contexto do agente. Em seguida, revise e atualize o modelo de consulta e faça o upload do arquivo de contexto atualizado para o agente.

Para fazer o download e atualizar o contexto de um agente de dados, siga estas etapas:

  1. No painel Explorer, clique em Ver ações.
  2. Clique em Baixar arquivo de contexto do agente.
  3. Siga as etapas em Criar contextos usando a CLI do Gemini para atualizar o contexto com outros pares de consultas.
  4. No painel Explorer, clique em Ver ações ao lado do agente de dados que você está usando.
  5. Clique em Editar agente.
  6. Clique em Procurar na seção Fazer upload do arquivo de contexto do agente e selecione o arquivo de contexto do agente atualizado.
  7. Clique em Salvar para atualizar o contexto do agente.

Depois de verificar a precisão das respostas, use o endpoint QueryData para conectar o aplicativo ao agente de dados.

Encontrar o ID do contexto do agente

Para conectar um aplicativo de dados ao agente de dados, você precisa do ID de contexto do agente.

  1. No Google Cloud console, acesse a página do AlloyDB.

    Acessar o AlloyDB

  2. Selecione um cluster na lista.

  3. No menu de navegação, clique em AlloyDB Studio.

  4. Faça login no Studio usando a autenticação do Identity and Access Management (IAM).

  5. No painel Explorer, clique em Ver ações ao lado do agente de dados que você está usando.

  6. Clique em Editar agente.

  7. Anote o ID do contexto em ID do contexto do agente. O formato do ID do contexto do agente é semelhante a projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates.

Conectar o agente de dados ao aplicativo

Defina o ID de contexto do agente na chamada de método QueryData para fornecer contexto criado para fontes de dados de banco de dados, como AlloyDB, Spanner, Cloud SQL e Cloud SQL para PostgreSQL. Para mais informações, consulte Definir o contexto do agente de dados para fontes de dados de banco de dados.

Depois de inspecionar o agente de dados, você pode referenciar a fonte de dados do banco de dados na chamada QueryData.

Exemplo de solicitação QueryData com contexto criado

O exemplo a seguir mostra uma solicitação QueryData usando a fonte de dados do banco de dados alloydb. O campo agent_context_reference.context_set_id é usado para vincular ao contexto pré-criado armazenado no banco de dados.

{
  "parent": "projects/data-agents-project/locations/us-central1",
  "prompt": "How many accounts in the Prague region are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "alloydb": {
          "database_reference": {
            "project_id": "data-agents-project",
            "region": "us-central1",
            "cluster_id": "sqlgen-magic",
            "instance_id": "data-agents-primary",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates"
          }
        }
      }
    ]
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

O corpo da solicitação contém os seguintes campos:

  • prompt: a pergunta em linguagem natural do usuário final.
  • context: contém informações sobre as fontes de dados.
    • datasource_references: especifica o tipo de fonte de dados.
      • alloydb: obrigatório ao consultar o banco de dados. Esse campo muda com base no banco de dados que você está consultando.
        • database_reference: especifica informações relacionadas à instância do banco de dados.
          • cluster_id: o ID do cluster da instância do banco de dados.
          • project_id: o ID do projeto da instância do banco de dados.
          • region: a região da instância do AlloyDB.
          • instance_id: o ID da instância do AlloyDB.
          • database_id: o ID do banco de dados.
        • agent_context_reference: vincula ao contexto criado no banco de dados.
          • context_set_id: o ID de contexto completo do agente do contexto armazenado no banco de dados. Por exemplo, projects/data-agents-project/locations/us-east1/contextSets/bdf_gsql_gemini_all_templates.
  • generationOptions: configura o tipo de saída a ser gerada.
    • generate_query_result: definido como verdadeiro para gerar e retornar os resultados da consulta.
    • generate_natural_language_answer: opcional. Se definido como verdadeiro, gera uma resposta em linguagem natural.
    • generate_explanation: opcional. Se definido como verdadeiro, gera uma explicação da consulta SQL.
    • generate_disambiguation_question: opcional. Se definido como verdadeiro, gera perguntas de desambiguação se a consulta for ambígua.

Exemplo de resposta QueryData

Confira um exemplo de resposta bem-sucedida de uma chamada QueryData:

{
  "generated_query": "-- Count the number of accounts in Prague that are eligible for loans\nSELECT\n  COUNT(DISTINCT \"loans\".\"account_id\")\nFROM \"loans\"\nJOIN \"district\" -- Join based on district ID\n  ON \"loans\".\"district_id\" = \"district\".\"district_id\"\nWHERE\n  \"district\".\"A3\" = 'Prague'; -- Filter for the Prague region",
  "intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to join the `district` table with the `loans` table to filter by region and count the distinct accounts. The `A3` column in the `district` table contains the region information, and I'll filter for 'Prague'. The `loans` table contains information about loans, including the `account_id` and `district_id`. I will join these two tables on their respective district IDs.",
  "query_result": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "total_row_count": 1
  },
  "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}

A seguir