Criar contextos usando a CLI do Gemini

Este documento descreve como usar a CLI do Gemini e a caixa de ferramentas do MCP para criar arquivos de contexto do agente. Esses arquivos contêm modelos e aspectos que fornecem contexto para gerar consultas SQL em linguagem natural. Você também vai usar o servidor MCP de enriquecimento de contexto do banco de dados.

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

Para criar o contexto do agente, siga estas etapas gerais:

  • Preparar o ambiente
  • Gerar modelos segmentados
  • Gerar aspectos segmentados
  • Opcional. Gerar modelos em massa

Antes de começar

Conclua os pré-requisitos a seguir antes de criar um agente.

Preparar uma instância do Spanner

  • Verifique se uma instância do Spanner está disponível. Para mais informações, consulte Criar uma instância.
  • Preencha o banco de dados com os dados e o esquema que o usuário final quer acessar.

Papéis e permissões necessárias

Preparar o ambiente

É possível criar arquivos de contexto do agente em qualquer ambiente de desenvolvimento local ou IDE. Para preparar o ambiente, siga estas etapas:

  • Instalar a CLI do Gemini
  • Instalar e configurar a caixa de ferramentas do MCP
  • Instalar e configurar o servidor MCP de enriquecimento de contexto do banco de dados

Instalar a CLI do Gemini

Para instalar a CLI do Gemini, consulte Começar a usar a CLI do Gemini. Instale a CLI do Gemini em um diretório separado, que também é usado para instalar a caixa de ferramentas do MCP e o servidor MCP de enriquecimento de contexto do banco de dados.

Instalar e configurar a caixa de ferramentas do MCP

  1. No mesmo diretório em que você instalou a CLI do Gemini, instale a extensão da CLI do Gemini da MCP Toolbox:

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

  2. Crie um arquivo de configuração tools.yaml no mesmo diretório em que você instalou a caixa de ferramentas do MCP para configurar a conexão do banco de dados:

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

    Substitua:

    • PROJECT_ID: o ID do projeto do Google Cloud .
    • INSTANCE_ID: o ID da sua instância do Spanner.
    • DATABASE_ID: o nome do banco de dados a ser conectado.

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

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

Instalar o servidor MCP de enriquecimento de contexto de banco de dados

O servidor MCP de enriquecimento de contexto do banco de dados oferece um fluxo de trabalho interativo e guiado para gerar modelos NL2SQL estruturados com base nos esquemas do banco de dados. Ele depende da extensão MCP Toolbox para conectividade de banco de dados. Para mais informações sobre como instalar o servidor MCP de enriquecimento de contexto do banco de dados, consulte Servidor MCP de enriquecimento de contexto do banco de dados.

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

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

      pip install --user pipx
  pipx ensurepath
  pipx install uv

  2. Instale o servidor MCP de enriquecimento de contexto de banco de dados.

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

O servidor usa a API Gemini para geração. Exporte a chave de API como uma variável de ambiente. Para saber como encontrar sua chave de API, consulte Como usar chaves de API do Gemini.

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

export GEMINI_API_KEY="YOUR_API_KEY"

Substitua YOUR_API_KEY pela sua chave de API do Gemini.

Gerar modelos segmentados

Se você quiser adicionar um par de consulta específico como um modelo de consulta ao contexto do agente, use o comando /generate_targeted_templates. Para mais informações sobre modelos, consulte Visão geral dos agentes de dados.

Para adicionar um modelo de consulta ao contexto do agente, siga estas etapas:

  1. No mesmo diretório em que você instalou a CLI do Gemini, inicie o Gemini:

    gemini

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

  3. Verifique se a caixa de ferramentas do MCP e a extensão de enriquecimento de banco de dados estão prontas para uso:

    /mcp list

  4. Execute o comando /generate_targeted_templates:

    /generate_targeted_templates

  5. Insira a consulta em linguagem natural que você quer adicionar ao modelo.

  6. Insira a consulta SQL correspondente ao modelo de consulta.

  7. Revise o modelo de consulta gerado. Você pode salvar o modelo de consulta como um arquivo de contexto do agente ou anexá-lo a um arquivo de contexto atual.

O arquivo de contexto do agente semelhante a my-cluster-psc-primary_postgres_templates_20251104111122.json é salvo no diretório em que você executou os comandos.

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

Gerar aspectos segmentados

Se você quiser adicionar um par de consulta específico como uma faceta ao arquivo de contexto do agente, use o comando /generate_targeted_fragments. Para mais informações sobre facetas, consulte Visão geral dos agentes de dados.

Para adicionar uma faceta ao contexto do agente, siga estas etapas:

  1. Execute o comando /generate_targeted_fragments:

    /generate_targeted_fragments

  2. Insira a consulta em linguagem natural que você quer adicionar ao modelo.

  3. Insira a consulta SQL correspondente ao modelo de consulta.

  4. Revise a faceta gerada. É possível salvar o aspecto em um arquivo de contexto do agente ou anexá-lo a um arquivo de contexto existente.

O arquivo de contexto do agente semelhante a my-cluster-psc-primary_postgres_templates_20251104111122.json é salvo no diretório em que você executou os comandos.

Para mais informações sobre o arquivo de contexto e os aspectos, consulte Contexto do agente.

Opcional: gerar modelos em massa

Se quiser gerar automaticamente o arquivo de contexto do agente com base no esquema e nos dados do banco de dados, use o comando /generate_bulk_templates.

Para gerar automaticamente modelos em massa, siga estas etapas:

  1. Execute o comando /generate_bulk_templates:

    /generate_bulk_templates

  2. Com base no esquema do banco de dados, a geração de SQL baseada em modelos faz uma série de perguntas relacionadas à verificação das informações do banco de dados e à concessão de permissões para acessar o esquema.

  3. Revise o modelo de consulta gerado. Você pode aprovar o modelo ou atualizar um par de consultas que quer revisar.

  4. Insira a consulta em linguagem natural que você quer adicionar ao modelo.

  5. Insira a consulta SQL correspondente ao modelo de consulta.

  6. Revise o modelo de consulta gerado. Você pode salvar o modelo de consulta como um arquivo de contexto do agente ou anexá-lo a um arquivo de contexto atual.

  7. Depois de aprovar o modelo de consulta, você pode criar um arquivo de modelo ou anexar os pares de consulta a um arquivo de modelo existente. O modelo de consulta é salvo como um arquivo JSON no seu diretório local.

O arquivo de contexto do agente semelhante a my-cluster-psc-primary_postgres_templates_20251104111122.json é salvo no diretório em que você executou os comandos.

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

A seguir