Criar e otimizar conjuntos de contexto com o agente de engenharia de contexto

Para alcançar alta precisão de consulta do QueryData e baixa latência on-line nos aplicativos de agente de dados, use o agente de engenharia de contexto para criar, avaliar e otimizar conjuntos de contexto. Ao automatizar a criação, o upload e a otimização de contexto, o agente ajuda seus aplicativos a retornar respostas rápidas, determinísticas e explicáveis a perguntas em linguagem natural.

Para saber mais sobre conjuntos de contexto e QueryData, consulte Visão geral dos conjuntos de contexto e Visão geral do QueryData.

Ao fornecer ao QueryData um contexto adaptado ao seu aplicativo de negócios, você fornece as regras de negócios precisas que o sistema precisa para resolver a intenção do usuário com nuances e oferecer uma qualidade de consulta de quase 100%. Enquanto você trabalha na CLI ou no ambiente de desenvolvimento integrado, o agente de engenharia de contexto faz o upload automático dos conjuntos de contexto para o Google Cloud , salvando os arquivos locais no espaço de trabalho para controle de versões.

Agente de engenharia de contexto

O agente de engenharia de contexto atua como seu assistente de tempo de design diretamente na CLI ou no ambiente de desenvolvimento integrado. A criação manual de contexto exige a escrita manual de padrões de consulta detalhados, a antecipação de todas as variações de frase e o diagnóstico manual de falhas de consulta em todas as iterações. O agente de engenharia de contexto elimina essa sobrecarga ao inicializar o contexto de referência, selecionar conjuntos de dados de avaliação de informações empíricas, realizar otimizações iterativas para corrigir lacunas de precisão e provar que seu contexto se generaliza em novas perguntas.

Você conversa com o agente usando linguagem natural para conduzir o fluxo de trabalho de otimização. Comece com um comando como "Otimize o conjunto de contexto de acordo com os requisitos do meu aplicativo".

Antes de começar

Antes de usar o agente de engenharia de contexto, conclua os pré-requisitos nas seções a seguir. É possível criar e armazenar conjuntos de contexto nas regiões us-central1, us-east1, europe-west4 e asia-southeast1, mesmo que a instância do banco de dados esteja em uma região diferente.

Ativar serviços obrigatórios

Ative os seguintes serviços para seu projeto:

Preparar o banco de dados

Prepare sua instância do Cloud SQL para PostgreSQL e configure o acesso para o agente:

Papéis e permissões necessárias

Para receber as permissões necessárias para usar o agente de engenharia de contexto e gerenciar conjuntos de contexto, configure os seguintes papéis do Identity and Access Management (IAM) e privilégios de banco de dados:

  • Adicione um usuário do IAM ou uma conta de serviço à instância. Para mais informações, consulte Gerenciar usuários com a autenticação de banco de dados do IAM para o Cloud SQL.
  • Conceda os papéis roles/cloudsql.instanceUser (ou roles/cloudsql.studioUser se você também testar consultas no Cloud SQL Studio), roles/serviceusage.serviceUsageConsumer, roles/geminidataanalytics.queryDataUser e roles/mcp.toolUser ao usuário ou à conta de serviço do IAM no nível do projeto. Para mais informações, consulte Adicionar vinculação de política do IAM para um projeto.
  • Para criar, fazer upload e gerenciar conjuntos de contexto, conceda o papel de Editor do Dataplex Catalog (roles/dataplex.catalogEditor) ou Administrador do Dataplex Catalog (roles/dataplex.catalogAdmin) ao usuário do IAM ou à conta de serviço no nível do projeto. Para mais informações, consulte Permissões de conjuntos de contexto.
  • Se você usar pesquisas de valor semântico (google_ml.embedding), ative a API Vertex AI e conceda o papel roles/aiplatform.user à conta de serviço da instância do Cloud SQL para PostgreSQL.

  • Conceda privilégios de banco de dados somente leitura a um usuário ou conta de serviço do IAM fazendo login como um usuário com privilégios de superusuário, como o usuário postgres:

    GRANT SELECT ON ALL TABLES IN SCHEMA public TO "USER_NAME";

    Substitua USER_NAME pelo endereço de e-mail do usuário (para uma conta de serviço, omita o sufixo .). É preciso usar aspas ao redor do nome de usuário porque ele contém caracteres especiais (@ e .). Se as tabelas estiverem em um esquema personalizado diferente de public, execute também GRANT USAGE ON SCHEMA SCHEMA_NAME TO "USER_NAME"; e GRANT SELECT ON ALL TABLES IN SCHEMA SCHEMA_NAME TO "USER_NAME";. 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.

Preparar o ambiente

É possível criar e otimizar conjuntos de contexto no ambiente de desenvolvimento local ou no ambiente de desenvolvimento integrado.

Instalar o uv

O agente de engenharia de contexto requer uv para gerenciar os pacotes Python subjacentes:

  1. Instale o uv seguindo as instruções em Instalar o uv.

  2. Verifique se o uv está instalado e pode ser acessado na linha de comando:

    uv --version

Instalar o agente de engenharia de contexto

Instale o plug-in do agente de engenharia de contexto no seu ambiente de desenvolvimento preferido:

CLI do Antigravity

  1. Instale a CLI do Antigravity. Consulte Começar a usar a CLI do Antigravity.
  2. Instale o plug-in do agente de engenharia de contexto: 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin
  3. Inicie a CLI do Antigravity: 
    agy

Para atualizar o plug-in mais tarde, execute agy plugin uninstall db-context-engineering seguido por agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin.

Claude Code

  1. Adicione o marketplace de plug-ins: 
    /plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git
  2. Instalar o plug-in: 
    /plugin install db-context-engineering@db-context-enrichment-marketplace
  3. Atualize os plug-ins para ativar as mudanças: 
    /reload-plugins

Para atualizar o plug-in mais tarde, execute /plugin update db-context-engineering@db-context-enrichment-marketplace.

CLI do Gemini (descontinuada)

  1. Instale a CLI do Gemini. Consulte Começar a usar a CLI do Gemini.
  2. Instalar a extensão: 
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

Para atualizar a extensão mais tarde, execute gemini extensions update google-cloud-db-context-engineering.

Autenticar com Google Cloud

  1. Configure o Application Default Credentials (ADC) para autenticar seu ambiente de desenvolvimento:

    gcloud auth application-default login

  2. Defina o projeto de cota para suas credenciais para que as ferramentas do Protocolo de Contexto de Modelo (MCP) possam usar seu projeto do Google Cloud :

    gcloud auth application-default set-quota-project PROJECT_ID

    Substitua PROJECT_ID pelo ID do projeto Google Cloud .

Conectar ao seu banco de dados

  1. Inicie o ambiente do agente e peça para ele estabelecer a conexão com o banco de dados (por exemplo, "Me ajude a configurar a conexão com o banco de dados"). O agente orienta você na criação do arquivo de configuração .context-engineering/tools.yaml para que ele possa ler esquemas e validar o SQL. (Antes de .context-engineering/tools.yaml ser criado, é esperado um aviso inicial de conexão com o servidor MCP de toolbox na inicialização.)

  2. Atualize a conexão do servidor MCP para aplicar a configuração .context-engineering/tools.yaml:

    • CLI do Antigravity: execute /mcp e selecione toolbox (ou db-context-engineering_toolbox) para reiniciar.
    • Claude Code: execute /mcp, selecione toolbox e selecione Reconnect.
    • CLI do Gemini: execute /mcp refresh (ou /mcp reload).

Criar e otimizar o contexto

O agente de engenharia de contexto guia seu conjunto de contexto por um ciclo de vida completo, desde o bootstrapping inicial até a generalização verificada.

Inicializar um conjunto de contexto de referência

Para evitar a criação de contexto em uma página em branco, o agente inspeciona o esquema do banco de dados e todos os artefatos de aplicativo disponíveis, como requisitos de negócios, documentação ou exemplos de consultas SQL. O agente deriva um conjunto de contexto de referência inicial que contém modelos de consulta fundamentais e aspectos de consulta baseados no seu modelo de banco de dados.

Depois de gerar e validar o contexto de referência, o agente o envia diretamente para o Google Cloud e retorna o nome do recurso do conjunto de contexto.

Criar conjuntos de dados de avaliação e de validação com base em artefatos de aplicativos

Para melhorar a acurácia de forma sistemática, você precisa de perguntas de informações empíricas pareadas com consultas SQL verificadas. Se você ainda não tiver um comparativo de mercado de avaliação, o agente poderá gerar um extraindo cenários de negócios do código do aplicativo, das consultas históricas e do esquema do banco de dados.

Durante a geração do conjunto de dados, o agente cria dois conjuntos distintos:

  • Comparativo de mercado de treinamento: uma coleção de pares de pergunta-SQL representativos usados durante a otimização iterativa.
  • Conjunto de dados de validação: um conjunto separado de perguntas semelhantes em domínio ao seu comparativo de mercado de treinamento, reservado para testes de generalização.

Otimizar a precisão com o algoritmo hill climbing

Na otimização de subida de encosta, o agente refina iterativamente seu conjunto de contexto para levar a precisão do QueryData a quase 100%:

  • Avaliar: o agente testa o conjunto de contexto atual em relação ao comparativo de mercado de treinamento usando a API QueryData e pontua a acurácia.
  • Diagnosticar lacunas: o agente analisa as falhas de consulta, identifica as causas raiz (como junções de tabelas ausentes, entidades particulares não vinculadas ou condições de filtro complexas) e formula correções direcionadas.
  • Refinar e fazer upload: o agente adiciona ou melhora modelos de consulta, facetas de consulta e pesquisas de valor para resolver as lacunas e faz o upload automático do conjunto de contexto atualizado para o Google Cloud na CLI.
  • Iteração: o agente repete esse ciclo em várias rodadas até que a precisão atinja a pontuação ideal.

O diagrama a seguir mostra o fluxo de trabalho sistemático de hill climbing:

Fluxo de trabalho para criar contexto de forma iterativa.

Comprovar a generalização com o conjunto de dados reservado

Alcançar alta precisão em um comparativo de mercado de treinamento é necessário, mas o tráfego de produção inclui variações de frases e perguntas compostas complexas que nunca foram vistas durante o desenvolvimento.

Depois que a otimização de subida de encosta converge, o agente testa o conjunto de contexto resultante em relação ao conjunto de dados de validação. Essa etapa verifica se o conjunto de contexto se generaliza de forma limpa para novas entradas do usuário sem overfitting para o comparativo de mercado inicial. O agente produz um relatório de generalização que mostra a acurácia em variações de perguntas não vistas e filtros compostos (como "Encontre casas perto de boas escolas em Del Mar para uma família iniciante com vista para o mar").

Criação e raciocínio sob demanda

Além das execuções de otimização completa, você pode conversar com o agente para atualizações direcionadas conforme os requisitos de negócios evoluem:

  • Criação direcionada: descreva um requisito de negócios específico em linguagem natural, e o agente formata o item de contexto e o envia diretamente da CLI sem edição manual:

    • "Crie um modelo para: 'Encontre casas perto de boas escolas em Del Mar' com SQL: SELECT p.property_id, p.address FROM properties AS p JOIN schools AS s ON p.school_id = s.school_id WHERE p.city = 'Del Mar' AND s.rating >= 7."
    • "Crie uma faceta para o filtro properties.bedrooms BETWEEN 3 AND 4 AND properties.square_feet BETWEEN 1500 AND 2500 com o rótulo 'para uma família iniciante'."
    • "Crie uma pesquisa de valor para properties.city."

  • Atualizações em massa em um conjunto de contexto: se as colunas do banco de dados forem renomeadas ou as estruturas das tabelas mudarem, o agente poderá atualizar todos os itens de contexto afetados simultaneamente sem modificar entradas não relacionadas:

    • "No meu conjunto de contexto, substitua properties.property_type = 'SFR' por properties.property_type = 'Single Family Residential' em qualquer item que faça referência a casas unifamiliares. Deixe os itens não relacionados em paz."

A seguir