Inspecionar e chamar um agente de dados

Neste documento, descrevemos como inspecionar um agente e atualizar o arquivo de contexto dele. Você pode inspecionar um agente para testar a capacidade dele de gerar consultas SQL com base em perguntas em linguagem natural. Se uma consulta gerada não estiver correta, 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 para ele. Para mais informações, consulte Gerenciar agentes de dados no Spanner Studio.

Inspecionar um agente de dados

Para inspecionar um agente de dados, siga estas etapas:

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

    Acessar o Spanner

  2. Selecione uma instância na lista e depois um banco de dados.

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

  4. No painel "Explorer", ao lado de Agentes de dados, clique em Ver ações.

  5. Clique em Inspecionar agente.

  6. No editor de consultas, clique em Gerar SQL para abrir o painel Me ajude a programar.

  7. Insira uma pergunta em linguagem natural para gerar uma consulta SQL e clique em Gerar.

  8. Confira se a consulta SQL está correta.

Baixar 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, baixe o arquivo de contexto do agente atual. Em seguida, revise e atualize o modelo de consulta e faça upload do arquivo de contexto atualizado para o agente.

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

  1. No painel "Explorer", ao lado de Agentes de dados, 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 mais pares de consultas.
  4. No painel "Explorer", ao lado do seu agente de dados, clique em Ver ações.
  5. Clique em Editar agente.
  6. Clique em Procurar na seção Fazer upload do arquivo de contexto do agente e selecione o arquivo atualizado.
  7. Clique em Salvar para atualizar o contexto do agente.

Quando estiver satisfeito com a precisão das respostas, use o endpoint QueryData para conectar seu 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 console Google Cloud , acesse a página do Spanner.

    Acessar o Spanner

  2. Selecione uma instância na lista e depois um banco de dados.

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

  4. No painel "Explorer", ao lado de Agentes de dados, clique em Ver ações.

  5. Clique em Editar agente.

  6. Anote o ID do contexto em ID do contexto do agente. O formato do ID de contexto do agente é semelhante a projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates.

Conectar o agente de dados ao aplicativo

Defina o ID do contexto do agente na chamada do 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 sua 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 spanner_reference. O campo agent_context_reference.context_set_id é usado para vincular ao contexto pré-criado armazenado no banco de dados.

{
  "parent": "projects/cloud-db-nl2sql/locations/us-central1",
  "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "spanner_reference" {
          "database_reference" {
            "engine": "GOOGLE_SQL"
            "project_id": "cloud-db-nl2sql"
            "region": "us-central1"
            "instance_id": "evalbench"
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/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.
      • spanner_reference: obrigatório ao consultar o banco de dados. Esse campo muda de acordo com o banco de dados consultado.
        • database_reference: especifica informações relacionadas à sua instância de banco de dados.
          • engine: o dialeto SQL do banco de dados. Defina como GOOGLE_SQL para bancos de dados do Spanner.
          • project_id: o ID do projeto da instância de banco de dados.
          • region: a região da instância do Spanner.
          • instance_id: o ID da instância do Spanner.
          • database_id: o ID do banco de dados.
        • agent_context_reference: links para o contexto criado no banco de dados.
          • context_set_id: o ID completo do contexto do agente armazenado no banco de dados. Por exemplo, projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_gsql_gemini_all_templates.
  • generationOptions: configura o tipo de saída a ser gerada.
    • generate_query_result: defina como "true" para gerar e retornar os resultados da consulta.
    • generate_natural_language_answer: opcional. Se definido como "true", gera uma resposta em linguagem natural.
    • generate_explanation: opcional. Se definido como "true", gera uma explicação da consulta SQL.
    • generate_disambiguation_question: opcional. Se definido como verdadeiro, gera perguntas de disambiguação se a consulta for ambígua.

Exemplo de resposta do 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