Crie contextos com a Gemini CLI

Este documento descreve como usar a CLI do Gemini e o conjunto de ferramentas do MCP para criar ficheiros de contexto do agente. Estes ficheiros contêm modelos e facetas que fornecem contexto para gerar consultas SQL a partir de linguagem natural. Também vai usar o servidor MCP de enriquecimento do contexto da base de dados.

Para saber mais sobre os agentes de dados, consulte o artigo Vista geral dos agentes de dados.

Para criar o contexto do agente, siga estes passos gerais:

  • Prepare o seu ambiente
  • Gere modelos segmentados
  • Gere facetas segmentadas
  • Opcional. Gere modelos em massa

Antes de começar

Cumpra os seguintes pré-requisitos antes de criar um agente.

Prepare uma instância do Spanner

  • Certifique-se de que existe uma instância do Spanner disponível. Para mais informações, consulte Crie uma instância.
  • Preencha a base de dados com os dados e o esquema aos quais o utilizador final quer aceder.

Funções e autorizações necessárias

Prepare o seu ambiente

Pode criar ficheiros de contexto do agente a partir de qualquer ambiente de programação local ou IDE. Para preparar o ambiente, siga estes passos:

  • Instale a Gemini CLI
  • Instale e configure a caixa de ferramentas do MCP
  • Instale e configure o servidor MCP de enriquecimento do contexto da base de dados

Instale a Gemini CLI

Para instalar o Gemini CLI, consulte o artigo Comece a usar o Gemini CLI. Certifique-se de que instala a CLI do Gemini num diretório separado, que também é usado para instalar o conjunto de ferramentas do MCP e o servidor do MCP de enriquecimento do contexto da BD.

Instale e configure a caixa de ferramentas do MCP

  1. No mesmo diretório onde instalou a Gemini CLI, instale a extensão da Gemini CLI da MCP Toolbox:

    gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

  2. Crie um ficheiro de configuração tools.yaml no mesmo diretório onde instalou o conjunto de ferramentas do MCP para configurar a ligação à base de dados:

      sources:
    my-spanner-source:
      kind: spanner
      project: PROJECT_ID
      instance: INSTANCE_ID
      database: DATABASE_ID

    Substitua o seguinte:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • INSTANCE_ID: o ID da sua instância do Spanner.
    • DATABASE_ID: o nome da base de dados à qual estabelecer ligação.

  3. Verifique se o ficheiro tools.yaml está configurado corretamente:

    ./toolbox --tools-file "tools.yaml"

Instale o servidor MCP de enriquecimento do contexto da base de dados

O servidor MCP de enriquecimento do contexto da base de dados oferece um fluxo de trabalho interativo e orientado para gerar modelos NL2SQL estruturados a partir dos esquemas da sua base de dados. Baseia-se na extensão da caixa de ferramentas do MCP para a conetividade da base de dados. Para mais informações sobre a instalação do servidor MCP de enriquecimento do contexto da BD, consulte o artigo Servidor MCP de enriquecimento do contexto da BD.

Para instalar o servidor MCP de enriquecimento do contexto da base de dados, faça o seguinte:

  1. No mesmo diretório onde instalou a CLI do Gemini, instale o instalador de pacotes uv Python.

      pip install --user pipx
  pipx ensurepath
  pipx install uv

  2. Instale o servidor MCP de enriquecimento do contexto da base de dados.

    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

O servidor usa a API Gemini para a geração. Certifique-se de que exporta a chave da API como uma variável de ambiente. Para mais informações sobre como encontrar a chave da API, consulte o artigo Usar chaves da API Gemini.

Para exportar a chave da API Gemini, execute o seguinte comando:

export GEMINI_API_KEY="YOUR_API_KEY"

Substitua YOUR_API_KEY pela sua chave da API Gemini.

Gere modelos segmentados

Se quiser adicionar um par de consultas específico como um modelo de consulta ao contexto do agente, pode usar o comando /generate_targeted_templates. Para mais informações sobre os modelos, consulte o artigo Vista geral dos agentes de dados.

Para adicionar um modelo de consulta ao contexto do agente, siga estes passos:

  1. No mesmo diretório onde instalou o Gemini CLI, inicie o Gemini:

    gemini

  2. Conclua a configuração da autenticação da Gemini CLI.

  3. Verifique se a caixa de ferramentas do MCP e a extensão de enriquecimento da base de dados estão prontas a usar:

    /mcp list

  4. Execute o comando /generate_targeted_templates:

    /generate_targeted_templates

  5. Introduza a consulta de linguagem natural que quer adicionar ao modelo de consulta.

  6. Introduza a consulta SQL correspondente no modelo de consulta.

  7. Reveja o modelo de consulta gerado. Pode guardar o modelo de consulta como um ficheiro de contexto do agente ou anexá-lo a um ficheiro de contexto existente.

O ficheiro de contexto do agente semelhante a my-cluster-psc-primary_postgres_templates_20251104111122.json é guardado no diretório onde executou os comandos.

Para mais informações sobre o ficheiro de contexto e o modelo de consulta, consulte o artigo Contexto do agente.

Gere facetas segmentadas

Se quiser adicionar um par de consultas específico como uma faceta ao ficheiro de contexto do agente, pode usar o comando /generate_targeted_fragments. Para mais informações sobre as facetas, consulte o artigo Vista geral dos agentes de dados.

Para adicionar uma faceta ao contexto do agente, siga estes passos:

  1. Execute o comando /generate_targeted_fragments:

    /generate_targeted_fragments

  2. Introduza a consulta de linguagem natural que quer adicionar ao modelo de consulta.

  3. Introduza a consulta SQL correspondente no modelo de consulta.

  4. Reveja o aspeto gerado. Pode guardar a faceta num ficheiro de contexto do agente ou anexá-la a um ficheiro de contexto existente.

O ficheiro de contexto do agente semelhante a my-cluster-psc-primary_postgres_templates_20251104111122.json é guardado no diretório onde executou os comandos.

Para mais informações sobre o ficheiro de contexto e as facetas, consulte o artigo Contexto do agente.

Opcional: gere modelos em massa

Se quiser gerar automaticamente o ficheiro de contexto do agente com base no esquema e nos dados da sua base de dados, pode usar o comando /generate_bulk_templates.

Para gerar automaticamente modelos em massa, siga estes passos:

  1. Execute o comando /generate_bulk_templates:

    /generate_bulk_templates

  2. Com base no esquema da base de dados, a geração de SQL baseada em modelos apresenta-lhe uma série de perguntas relacionadas com a validação das informações da base de dados e a concessão de autorizações para aceder ao esquema da base de dados.

  3. Reveja o modelo de consulta gerado. Pode aprovar o modelo ou atualizar um par de consultas que quer rever.

  4. Introduza a consulta de linguagem natural que quer adicionar ao modelo de consulta.

  5. Introduza a consulta SQL correspondente no modelo de consulta.

  6. Reveja o modelo de consulta gerado. Pode guardar o modelo de consulta como um ficheiro de contexto do agente ou anexá-lo a um ficheiro de contexto existente.

  7. Depois de aprovar o modelo de consulta, pode criar um novo ficheiro de modelo ou anexar os pares de consultas a um ficheiro de modelo existente. O modelo de consulta é guardado como um ficheiro JSON no seu diretório local.

O ficheiro de contexto do agente semelhante a my-cluster-psc-primary_postgres_templates_20251104111122.json é guardado no diretório onde executou os comandos.

Para mais informações sobre o ficheiro de contexto do agente, consulte o artigo Contexto do agente.

O que se segue?