Criar conjuntos de contexto 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, facetas e pesquisas de valor que fornecem contexto para gerar consultas SQL em linguagem natural. Você também vai usar a extensão de aprimoramento de contexto do banco de dados.

Para saber mais sobre conjuntos de contexto, consulte a Visão geral dos conjuntos de contexto.

Para criar um arquivo de contexto do agente, siga estas etapas gerais:

  • Preparar o ambiente
  • Gerar modelos segmentados
  • Gerar facetas segmentadas
  • Gerar pesquisas de valor segmentadas
  • Opcional. Gerar modelos em massa

Antes de começar

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

Ativar serviços obrigatórios

Ative os seguintes serviços para seu projeto:

Preparar uma instância do Cloud SQL

Papéis e permissões necessárias

Conceder permissão executesql à instância do Cloud SQL

Para conceder a permissão executesql à instância do Cloud SQL e ativar a API Cloud SQL Data, execute o seguinte comando: 
gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
Substitua o seguinte:
  • PROJECT_ID: o ID do seu Cloud de Confiance by S3NS projeto.
  • INSTANCE_ID: o ID da sua instância do Cloud SQL.
Para executar as etapas deste tutorial, faça login no Cloud de Confiance by S3NS e autentique o banco de dados usando a autenticação do IAM.

Preparar o banco de dados para pesquisas de valor

Para usar pesquisas de valor semânticas e de trigramas, configure sua instância do Cloud SQL para MySQL para oferecer suporte a embeddings de vetor e indexação de n-gramas.

  1. Para que a instância do Cloud SQL para MySQL realize pesquisas de valor semânticas, ative as seguintes flags.

    1. Ative a flag cloudsql_vector.

      gcloud sql instances patch INSTANCE_NAME --database-flags=cloudsql_vector=on

    2. Ative a flag enable-google-ml-integration para permitir que a instância do Cloud SQL para MySQL seja integrada à Vertex AI.

      gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration

    3. Crie uma coluna de vetor para armazenar embeddings de cidades

      ALTER TABLE `airports` 
ADD COLUMN `city_embedding` VECTOR(768);

    4. Gere e armazene embeddings de vetor para nomes de cidades

      UPDATE `airports` 
SET `city_embedding` = mysql.ml_embedding('text-embedding-005', `city`) 
WHERE `city` IS NOT NULL;

  2. Para que a instância do Cloud SQL para MySQL realize pesquisas de valor de trigramas, siga estas etapas.

    1. Ative a flag ngram_token_size.

      gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3

    2. Crie um índice FULLTEXT para correspondência de trigramas no nome do aeroporto

      CREATE FULLTEXT INDEX `idx_ngram_airports_name` 
ON `airports`(`name`) 
WITH PARSER ngram;

Preparar o ambiente

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

  • Instalar a CLI do Gemini
  • Instalar a extensão de aprimoramento de contexto do banco de dados
  • Configurar a conexão do banco de dados

Instalar a CLI do Gemini

Para instalar a CLI do Gemini, consulte Começar a usar a CLI do Gemini.

Instalar a extensão do MCP de aprimoramento de contexto do banco de dados

A extensão de aprimoramento de contexto do banco de dados oferece um fluxo de trabalho guiado e interativo para gerar contexto NL2SQL estruturado com base nos esquemas do banco de dados.

Para mais informações sobre como instalar a extensão de aprimoramento de contexto do banco de dados, consulte Extensão de aprimoramento de contexto do banco de dados.

Para instalar a extensão de aprimoramento de contexto do banco de dados, siga estas etapas:

  1. Instale a extensão da CLI do Gemini da caixa de ferramentas do MCP:

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

  2. (Opcional) Atualize a extensão de aprimoramento de contexto do banco de dados.

    Para verificar a versão instalada da extensão, execute o seguinte comando:

    gemini extensions list

    Verifique se a versão é 0.4.2 ou mais recente. Para atualizar a extensão de aprimoramento de contexto do banco de dados, execute o seguinte comando:

      gemini extensions update mcp-db-context-enrichment

    Para atualizar a extensão de aprimoramento de contexto do banco de dados ou substituir a GEMINI_API_KEY, execute o seguinte comando:

    gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY

    Substitua GEMINI_API_KEY pela sua chave da API Gemini.

Configurar a conexão do banco de dados

A extensão exige a conexão do banco de dados para a geração de contexto para buscar esquemas e executar instruções SQL. Para permitir que a extensão interaja com o banco de dados, configure as credenciais de autenticação e defina as fontes e ferramentas do banco de dados.

Configurar as credenciais padrão do aplicativo

É necessário configurar as Application Default Credentials (ADC) para fornecer credenciais de usuário para dois componentes principais:

  • Servidor MCP da caixa de ferramentas: usa credenciais para se conectar ao banco de dados, buscar esquemas e executar SQL para validação.
  • Extensão de aprimoramento de contexto do banco de dados: usa credenciais para autenticar e chamar a API Gemini.

Execute os seguintes comandos no terminal para autenticar:

gcloud auth application-default login

Configurar o arquivo tools.yaml

A extensão exige uma conexão de banco de dados para a geração de contexto, que é compatível com a caixa de ferramentas do MCP e definida no arquivo de configuração tools.yaml.

O arquivo tools.yaml especifica a fonte e as ferramentas do banco de dados necessárias para buscar esquemas ou executar SQL. A extensão vem com habilidades de agente pré-instaladas para ajudar você a gerar a configuração.

  1. Inicie a CLI do Gemini:

    gemini

  2. Verifique se as habilidades estão ativas digitando na CLI do Gemini: 

    /skills

  3. Digite um comando como help me setup the database connection. A habilidade orienta você na criação do arquivo tools.yaml no diretório de trabalho atual.

  4. Execute o seguinte comando na CLI do Gemini para aplicar a configuração tools.yaml ao servidor MCP da caixa de ferramentas.

    /mcp reload

Para mais informações sobre como configurar manualmente o arquivo tools.yaml, consulte Configuração da caixa de ferramentas do MCP.

Gerar contexto

As extensões instaladas anteriormente permitem que a CLI do Gemini ajude você a criar contexto na forma de um arquivo JSON.

Gerar modelos segmentados

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

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

  1. No mesmo diretório, inicie a CLI do 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 aprimoramento do banco de dados estão prontas para uso:

    /mcp reload

  4. Execute o comando /generate_targeted_templates:

    /generate_targeted_templates

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

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

  7. Analise o modelo de consulta gerado. É possível salvar o modelo de consulta como um arquivo de conjunto de contexto ou anexá-lo a um arquivo de conjunto de contexto atual.

O arquivo de conjunto de contexto 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 conjunto de contexto e o modelo de consulta, consulte Visão geral dos conjuntos de contexto.

Gerar facetas segmentadas

Se você quiser adicionar um par de consultas específico como uma faceta ao arquivo de conjunto de contexto, use o comando /generate_targeted_facets.

Para adicionar uma faceta ao arquivo de conjunto de contexto, siga estas etapas:

  1. Execute o comando /generate_targeted_facets:

    /generate_targeted_facets

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

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

  4. Analise a faceta gerada. É possível salvar o atributo em um arquivo de conjunto de contexto ou anexá-lo a um arquivo de conjunto de contexto atual.

O arquivo de conjunto de contexto 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 conjunto de contexto e as facetas, consulte Visão geral dos conjuntos de contexto

Gerar consultas de pesquisa de valor

Se você quiser gerar pesquisas de valor que especifiquem como o sistema deve pesquisar e corresponder valores específicos em um tipo de conceito, use o comando /generate_targeted_value_searches.

Conclua as etapas em Preparar o banco de dados para pesquisas de valor.

Para gerar um índice de valor, siga estas etapas:

  1. Execute o comando /generate_targeted_value_searches:

    /generate_targeted_value_searches
  1. Insira mysql para selecionar o MySQL como o mecanismo de banco de dados. Selecione "default" para selecionar o MySQL 8.0.

  1. Insira a configuração de pesquisa de valor da seguinte maneira:

    Table name: TABLE_NAME
Column name: COLUMN_NAME
Concept type: CONCEPT_TYPE
Match function: MATCH_FUNCTION
Description: DESCRIPTION

    Substitua o seguinte:

    • TABLE_NAME: a tabela em que a coluna associada ao tipo de conceito existe.
    • COLUMN_NAME: o nome da coluna associada ao tipo de conceito.
    • CONCEPT_TYPE: o tipo de conceito que você quer definir, por exemplo, City name.

    • MATCH_FUNCTION: a função de correspondência a ser usada para a pesquisa de valor. É possível usar uma das seguintes funções:

      • EXACT_STRING_MATCH: para correspondência exata de dois valores de string. Ideal para IDs, códigos e chaves primárias exclusivos.
      • TRIGRAM_STRING_MATCH: para correspondência aproximada que calcula a distância normalizada do trigrama. Ideal para pesquisas de usuários e correção de nomes. Para usar TRIGRAM_STRING_MATCH, você deve preparar seu banco de dados para oferecer suporte à indexação de n-gramas.
      • SEMANTIC_SIMILARITY_MATCH: para pesquisa semântica em valores de string. Ideal para pesquisas multilíngues e de sinônimos. Para uma lista de modelos compatíveis, consulte Modelos do Google com suporte. Para usar SEMANTIC_SIMILARITY_MATCH, você deve preparar seu banco de dados para oferecer suporte a embeddings de vetor.

    • DESCRIPTION: (opcional) a descrição da consulta de pesquisa de valor.

  2. Adicione outras pesquisas de valor conforme necessário. Se você pular a adição de outros índices de valor, a geração de SQL baseada em modelo vai passar para a próxima etapa.

  3. Analise as pesquisas de valor geradas. É possível salvar o conjunto de contexto como um arquivo de conjunto de contexto ou adicioná-lo ao final de um arquivo de conjunto de contexto atual.

O arquivo de conjunto de contexto 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 índice de valor, consulte Visão geral dos conjuntos de contexto

Opcional: gerar modelos em massa

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

Para gerar modelos em massa automaticamente, 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 modelo orienta você em 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 do banco de dados.

  3. Analise o modelo de consulta gerado. É possível aprovar o modelo ou atualizar um par de consultas que você quer revisar.

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

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

  6. Analise o modelo de consulta gerado. É possível salvar o modelo de consulta como um arquivo de conjunto de contexto ou anexá-lo a um arquivo de contexto atual.

  7. Depois de aprovar o modelo de consulta, é possível criar um novo arquivo de modelo ou anexar os pares de consultas a um arquivo de modelo atual. O modelo de consulta é salvo como um arquivo JSON no diretório local.

O arquivo de conjunto de contexto 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 conjunto de contexto, consulte Visão geral dos conjuntos de contexto.

A seguir