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 criar um arquivo de 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.

Ativar serviços obrigatórios

• API Gemini Data Analytics
• API Gemini para o Google Cloud

Preparar uma instância do Cloud SQL

• Verifique se você tem acesso a uma instância do Cloud SQL ou crie uma. Para mais informações, consulte Criar instâncias para o Cloud SQL.
• Crie um banco de dados na instância em que você vai criar as tabelas. Para mais informações, consulte Criar um banco de dados na instância do Cloud SQL.

Papéis e permissões necessárias

• Adicione um usuário do IAM ou uma conta de serviço no nível da instância. Para mais informações, consulte Adicionar uma vinculação de política do IAM a um usuário, uma conta de serviço ou um grupo.
• Conceda os papéis cloudsql.studioUser e cloudsql.instanceUser ao usuário do IAM no nível do projeto. Para mais informações, consulte Adicionar uma vinculação de política do IAM a um projeto.
• Você também precisa conceder privilégios de banco de dados a um usuário do IAM ou uma conta de serviço fazendo login como o usuário baseado em senha do banco de dados.
  
  GRANT ALL PRIVILEGES ON * TO "IAM_USERNAME";.
  
  Para mais informações, consulte Conceder privilégios de banco de dados a um usuário individual do IAM ou a uma conta de serviço.

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

gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API

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 MCP Toolbox

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-cloud-sql-mysql-source:
         kind: cloud-sql-mysql
         project: PROJECT_ID
         region: REGION_ID
         instance: INSTANCE_ID
         database: DATABASE_ID
         user: USER_NAME
         password: PASSWORD
   

   Substitua:

   • PROJECT_ID: o ID do projeto do Cloud de Confiance .
   • REGION_ID: a região da instância do Cloud SQL, por exemplo, us-central1.
   • INSTANCE_ID: o ID da sua instância do Cloud SQL.
   • DATABASE_ID: o nome do banco de dados a ser conectado.
   • USER_NAME: o usuário do banco de dados. Para mais informações sobre como definir esse valor, consulte Fontes na caixa de ferramentas da MCP.
   • PASSWORD: a senha do usuário do banco de dados. Para mais informações sobre como definir esse valor, consulte Fontes na caixa de ferramentas da MCP.

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 guiado e interativo 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.

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Instale o servidor MCP de enriquecimento de contexto do 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 mais informações sobre como encontrar sua chave de API, consulte Como usar chaves de API do Gemini.

Exporte a chave da API Gemini:

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 a faceta em um arquivo de contexto do agente ou anexá-la 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 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 modelos orienta você por 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

• Saiba mais sobre os agentes de dados.
• Saiba como criar ou excluir um agente de dados no Cloud SQL Studio.
• Saiba como inspecionar e chamar um agente de dados.