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 a instância do Cloud SQL para MySQL 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 Adicionar um usuário individual do IAM ou uma conta de serviço a uma instância do 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.

  • Peça para um usuário privilegiado conceder privilégios de banco de dados somente leitura (e privilégios de execução em mysql.ml_embedding se você usar pesquisas de valor semântico) ao usuário ou à conta de serviço do IAM:

    GRANT SELECT ON *.* TO "IAM_USERNAME";
GRANT EXECUTE ON FUNCTION mysql.ml_embedding TO "IAM_USERNAME";

    Substitua IAM_USERNAME pelo nome de usuário do banco de dados do usuário ou da conta de serviço do IAM (o endereço de e-mail sem o @ e o nome de domínio). 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 banco de dados para pesquisas de valor

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

  1. Ative a API Vertex AI e a API Compute Engine e conceda o papel roles/aiplatform.user à conta de serviço da instância do Cloud SQL para MySQL. Para mais informações, consulte Ativar a integração com a Vertex AI.

  2. Ative as flags de banco de dados cloudsql_vector e ngram_token_size e a integração da Vertex AI na instância do Cloud SQL para MySQL:

    gcloud sql instances patch INSTANCE_NAME \
    --enable-google-ml-integration \
    --database-flags=cloudsql_iam_authentication=on,cloudsql_vector=on,ngram_token_size=3

    Substitua INSTANCE_NAME pelo nome da instância do Cloud SQL para MySQL.

  3. Para permitir que a instância do Cloud SQL para MySQL realize pesquisas de valor semântico:

    1. Crie uma coluna de vetor para armazenar embeddings (por exemplo, embeddings city na tabela properties):

      ALTER TABLE `properties`
ADD COLUMN `city_embedding` VECTOR(768) USING VARBINARY;

    2. Gere e armazene embeddings de vetor para os valores da coluna:

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

  4. Para permitir que a instância do Cloud SQL para MySQL realize pesquisas de valor de trigrama, crie um índice FULLTEXT com o analisador ngram na coluna de texto de destino (por exemplo, address na tabela properties):

    CREATE FULLTEXT INDEX `idx_ngram_properties_address`
ON `properties`(`address`)
WITH PARSER ngram;

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