Criar conjuntos de contexto usando o agente de engenharia de contexto

Este documento descreve como criar e otimizar os conjuntos de contexto que ajudam a alcançar alta precisão de consultas QueryData nos seus aplicativos de agente de dados. O agente de engenharia de contexto ajuda a criar, avaliar e melhorar conjuntos de contexto automatizando a criação e a otimização deles.

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

Para criar aplicativos de dados de nível empresarial, a acurácia do modelo de conversão de texto em SQL normalmente precisa atingir quase 100% de qualidade. Resultados de consultas incorretos afetam a usabilidade geral do aplicativo e a experiência do usuário. Para conseguir respostas explicáveis e relevantes para os negócios com alta precisão, é necessário fazer engenharia de contexto, que é o processo de criar e otimizar iterativamente o contexto para alcançar a precisão ideal.

Ao fornecer QueryData com o contexto direcionado ao seu aplicativo comercial, você fornece as regras de negócios precisas de que o sistema precisa para resolver a intenção do usuário sutil.

Agente de engenharia de contexto

O agente de engenharia de contexto automatiza esse fluxo de trabalho de otimização. Você pode conversar com o agente para lidar com tarefas específicas e otimizar seu contexto. A lista a seguir oferece exemplos de comandos em linguagem natural que você pode usar para instruir o agente, além de uma descrição de como ele responde. Use estes exemplos para criar e otimizar seu contexto:

  • Exemplo de comando para análise de falhas: "Atualize o contexto para que possamos identificar corretamente o aeroporto em consultas como 'voos para a disney world'" O agente analisa a falha, explica a lacuna e recomenda adicionar um item de contexto adequado, como uma consulta de pesquisa de valor.
  • Exemplo de comando para sugestão de contexto: "Leia o código do meu app e sugira algum contexto para adicionar." O agente analisa o código, considera o domínio do seu aplicativo e sugere quais itens de contexto seriam relevantes.
  • Exemplo de comando para processamento em massa: "Aqui estão 10 exemplos de perguntas e consultas SQL. Transforme-os em modelos." O agente processa em lote suas entradas e atualiza seu conjunto de contexto.

Importância do conjunto de dados de ouro

Para otimizar seu contexto, primeiro crie um conjunto de dados que corresponda às entradas de linguagem natural do seu aplicativo. O agente pode ajudar você a criar esse conjunto de dados valioso, que consiste em perguntas dos usuários e consultas esperadas do banco de dados. Com um conjunto de dados de referência, é possível:

  • Estabeleça uma linha de base para a performance da consulta.
  • Validar atualizações com base em consultas de banco de dados de informações empíricas.
  • Meça as melhorias na precisão em todas as iterações.

O processo sistemático de subida de encosta

Na escalada de colina sistemática, o agente melhora iterativamente um conjunto de contexto por meio da avaliação do conjunto de dados padrão-ouro, da análise de lacunas e das atualizações para aumentar a precisão em quase 100%.

  • Gerar automaticamente o contexto de valor de referência: crie um conjunto de contexto inicial derivado do esquema do banco de dados e dos artefatos do aplicativo.
  • Fluxo de trabalho de otimização de Hill-Climbing: deixe o agente avaliar a acurácia dos seus dados de consulta, realizar uma análise de lacunas em falhas e propor automaticamente melhorias para aumentar a acurácia.

O diagrama a seguir mostra o fluxo de trabalho sistemático de subida de encosta:

Fluxo de trabalho para criar contexto de forma iterativa.

Antes de começar

Conclua os pré-requisitos a seguir antes de usar o agente de engenharia de contexto.

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 Data do Cloud SQL, 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 projeto do Google Cloud .
  • INSTANCE_ID: o ID da sua instância do Cloud SQL.
Para seguir as etapas deste tutorial, faça login no Google Cloud e autentique o banco de dados usando a autenticação do IAM.

Preparar o banco de dados para pesquisas de valor

Para usar pesquisas semânticas e de valor 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. Para permitir que a instância do Cloud SQL para MySQL faça pesquisas de valor semântico, 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 se integre à Vertex AI.

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

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

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

    4. Gerar e armazenar 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 permitir que a instância do Cloud SQL para MySQL faça pesquisas de valores 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 ambiente de desenvolvimento integrado. Para preparar o ambiente, conclua as seguintes etapas:

  • Instalar o agente de engenharia de contexto
  • Configurar a conexão de banco de dados

Instalar o agente de engenharia de contexto

O agente de engenharia de contexto executa o servidor do Protocolo de Contexto de Modelo (MCP) que exige uv para gerenciar pacotes Python subjacentes.

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

  2. Verifique se uv está instalado e acessível na linha de comando:

    uv --version

Para preparar seu ambiente, instale o agente de engenharia de contexto na estrutura de agentes selecionada, como a CLI do Antigravity, o Claude Code ou a CLI do Gemini.

Dependendo do arnês do agente selecionado, siga as etapas de instalação correspondentes:

CLI do Antigravity

Para instalar o agente de engenharia de contexto na CLI do Antigravity, siga estas etapas:

  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, que inclui fluxos de trabalho para geração de contexto. Substitua VERSION pela versão lançada necessária: 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION
  3. Inicie a CLI do Antigravity: 
    agy
  4. Opcional. Atualize o plug-in: 
    agy plugin uninstall google-cloud-db-context-engineering
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/NEW_VERSION

Claude Code

Para instalar o agente de engenharia de contexto no Claude Code, siga estas etapas:

  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
  4. Opcional. Atualize o plug-in: 
    /plugin update db-context-engineering@db-context-enrichment-marketplace

CLI do Gemini (descontinuada)

Para instalar o agente de engenharia de contexto na CLI do Gemini, siga estas etapas:

  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
  3. Opcional. Atualize a extensão: 
    gemini extensions update mcp-db-context-enrichment

Configurar a conexão de banco de dados

O agente precisa de uma conexão de banco de dados para buscar esquemas e validar a sintaxe do contexto SQL gerado. Para permitir que o agente interaja com seu banco de dados, configure as credenciais de autenticação e defina a configuração de conexão do banco de dados.

Configurar o Application Default Credentials

Configure as Application Default Credentials (ADC) para fornecer credenciais de usuário e acessar recursos do Google Cloud agente de engenharia de contexto:

  • Servidor MCP da caixa de ferramentas: usa credenciais para se conectar ao banco de dados, buscar esquemas e executar SQL para validação.
  • Evalbench: usa credenciais para invocar QueryData para avaliação.

Execute os seguintes comandos no terminal para autenticar:

gcloud auth application-default login

Configurar o arquivo de conexão do banco de dados

O agente precisa de uma conexão de banco de dados para gerar contexto, que o MCP Toolbox aceita e define em um arquivo de configuração.

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

  1. Inicie o ambiente do agente.

  2. Peça ajuda ao agente para configurar a conexão do banco de dados. Por exemplo, diga "me ajude a configurar a conexão do banco de dados". Siga as instruções do agente para criar o arquivo de configuração no diretório de trabalho atual como autoctx/tools.yaml.

  3. Para aplicar a nova configuração de tools.yaml, recarregue sua conexão:

    • Na CLI do Antigravity, execute /mcp e selecione toolbox para reiniciar.
    • Na CLI do Gemini, execute /mcp reload.
    • No Claude Code, execute /reload-plugins.

Para mais informações sobre como configurar manualmente o arquivo de configuração do banco de dados, consulte Configuração da MCP Toolbox.

Gerar e otimizar contexto

O agente de engenharia de contexto oferece um conjunto de habilidades do agente e ferramentas do MCP para melhorar a capacidade de engenharia de contexto do seu agente de programação. Use essas ferramentas juntas para gerar um valor de referência, medir a eficácia e aplicar melhorias de forma iterativa. No entanto, você pode começar em qualquer etapa do fluxo de trabalho:

  • Se você já tiver um contexto definido, poderá prosseguir diretamente para a avaliação.
  • Se você tiver consultas com falha que quer corrigir, vá direto para a análise de lacunas.

Cada funcionalidade descreve as ações, os casos de uso e os comandos de invocação do agente.

Os exemplos de comandos mostram como consultar o agente em linguagem natural. Se o agente precisar de mais detalhes para concluir uma solicitação, ele vai pedir esclarecimentos.

Criar e expandir conjuntos de dados de avaliação

Para melhorar o desempenho, primeiro é preciso medi-lo. A engenharia de contexto sem um conjunto de dados de ouro, que consiste em perguntas do usuário combinadas com o SQL esperado, não tem verificação sistemática. Com um conjunto de dados de referência, cada mudança é uma melhoria mensurável que pode ser validada em relação à verdade fundamental.

Criar um conjunto de dados de ouro representativo manualmente é demorado, e conjuntos de dados pequenos podem não ter variações na forma de falar dos usuários. O agente resolve isso:

  • Gerando pares de pergunta e SQL candidatos com base no esquema do banco de dados.
  • Expansão de um pequeno conjunto de dados de sementes usando variações de filtro, sinônimos e reformulações.

Como opção, você pode deixar o agente executar o SQL gerado no seu banco de dados. Essa verificação confirma que as consultas são executadas corretamente antes de serem adicionadas ao conjunto de dados.

O conjunto de dados é um arquivo JSON que contém pares de pergunta-SQL:

[
  {
    "id": "example_001",
    "nlq": "What is the total revenue for the top 5 products?",
    "golden_sql": "SELECT product_id, sum(net_revenue) FROM sales GROUP BY product_id ORDER BY sum(net_revenue) DESC LIMIT 5;"
  }
]

Os pares aprovados preenchem o arquivo autoctx/golden.json no seu espaço de trabalho, onde estão prontos para avaliação. Você pode fornecer um arquivo existente ou escrever alguns exemplos de avaliação inline para o agente expandir.

Você pode usar os seguintes exemplos de comandos para instruir o agente:

  • "Gere um conjunto de dados de avaliação com base no meu esquema."
  • "Aqui está uma pergunta inicial e SQL. Expanda para um conjunto de dados mais amplo e verifique as consultas executadas."

Gerar um conjunto de contexto de referência

Para evitar a criação de contexto do zero, deixe o agente derivar um conjunto de contexto inicial do esquema do banco de dados e dos artefatos do aplicativo, como regras de negócios, consultas de amostra ou arquivos README. Embora esse contexto de base não seja final, ele oferece um ponto de partida validado com base no modelo de banco de dados.

Você pode usar os seguintes exemplos de comandos para instruir o agente:

  • "Gere um conjunto de contexto do meu esquema."
  • "Gere o contexto inicial usando estes esquemas e as regras de negócios em requirements.md."

O agente pede que você nomeie o experimento, que organiza os artefatos gerados, e pode pedir que você reduza o escopo se o esquema do banco de dados for grande. Para fazer upload do contexto usando o Cloud SQL Studio, siga as instruções depois que o agente gerar o arquivo JSON.

Avaliar a eficácia do contexto

Depois de estabelecer um conjunto de contexto e um conjunto de dados de ouro, deixe o agente medir a performance do contexto consultando a API QueryData do agente de dados com cada pergunta de ouro. O agente compara o SQL gerado e os resultados da execução com a resposta esperada usando o Evalbench para processar a comparação.

Executar uma avaliação oferece o seguinte:

  • Métricas quantitativas, como resultados de aprovação e reprovação e pontuações agregadas, para acompanhar o progresso nas iterações de contexto.
  • Um resumo da conversa inline e relatórios CSV detalhados gravados no diretório eval_reports/ da pasta do experimento.

Para iniciar uma avaliação, forneça o caminho do conjunto de dados de referência e o ID do conjunto de contexto. Para saber como encontrar o ID do conjunto de contexto, consulte Encontrar o ID do contexto do agente.

Você pode usar os seguintes exemplos de comandos para instruir o agente:

  • "Avalie meu contexto em relação a golden.json."
  • "Execute a avaliação de novo usando a configuração do meu último experimento."

Para executar novamente uma configuração de avaliação gerada anteriormente sem configurá-la de novo, pergunte ao agente ou invoque a CLI diretamente:

uvx google-evalbench --run_config=autoctx/experiments/my-experiment/eval_configs/run_config.json

Para detalhes sobre o esquema de configuração de avaliação e como personalizar execuções de avaliação, consulte a documentação do Evalbench.

Realizar análise de lacunas e propor melhorias

Para resolver falhas de consulta, é necessário identificar as causas raiz, como colunas incorretas, junções de tabelas ausentes ou termos aproximados não resolvidos. Identificar esses problemas manualmente exige uma análise extensa dos relatórios de avaliação.

O agente automatiza esse ciclo de análise e correção:

  • Análise de lacunas: o agente lê os resultados da avaliação e o contexto definido para agrupar falhas semelhantes e recomendar adições de contexto segmentadas, como modelos, aspectos ou pesquisas de valor.
  • Correções propostas: o agente propõe edições concretas e, opcionalmente, testa o SQL no seu banco de dados para verificar a resolução.
  • Preservação da linha de base: o agente grava as melhorias em um novo arquivo JSON ao lado do contexto de linha de base, preservando os arquivos originais.

Você pode usar os seguintes exemplos de comandos para instruir o agente:

  • "Faça uma análise de lacunas na minha última avaliação e proponha correções."
  • "Otimize este conjunto de contexto em relação a golden.json."

Para se preparar para a próxima iteração, faça upload do contexto aprimorado para o conjunto de contexto de destino usando o Data Agents Studio. Siga as instruções.

Criar itens de contexto específicos do autor sob demanda

Se você já conhece o contexto necessário, como um modelo para uma pergunta específica, uma faceta para um filtro repetido ou uma pesquisa de valor para uma coluna específica, escrever o JSON de contexto manualmente pode introduzir erros de serialização em nomes de parâmetros, metadados de tipo ou sintaxe de fragmento. O agente processa a formatação JSON para que você possa se concentrar na sua intenção comercial.

Você também pode usar esse recurso para atualizações ad hoc, como quando precisar oferecer suporte a um novo padrão de consulta ou resolver um detalhe de esquema ausente. Para receber o JSON, descreva o contexto necessário ao agente sem executar uma avaliação ou configurar um experimento.

Esse também é o recurso certo para usar quando você recebe uma tarefa única: um stakeholder dá a você um novo par pergunta-SQL que ele quer que seja compatível, ou você identifica uma faceta ausente durante uma revisão de código. Não é necessário configurar um experimento ou executar uma avaliação para corrigir isso. Basta descrever o que você quer, e o agente vai produzir o JSON.

Você pode usar os seguintes exemplos de comandos para instruir o agente:

  • "Crie um modelo para: 'Quais aeroportos estão na Califórnia?' com SQL: SELECT name FROM airports WHERE country = 'United States' AND state = 'CA'."
  • "Crie uma faceta para o filtro departure_time BETWEEN '00:00:00' AND '06:00:00' com o rótulo 'olho vermelho'."
  • "Crie uma pesquisa de valor para airports.iata."

Motivo para a seleção do tipo de contexto

Selecionar o tipo de contexto correto, seja uma pesquisa de modelo, atributo ou valor, ajuda a evitar o aumento do contexto e regressões de consultas de banco de dados. Por exemplo, usar um modelo em vez de uma faceta pode causar regras duplicadas, enquanto pesquisas de valor introduzidas quando um modelo é suficiente podem aumentar a latência da consulta. Para encontrar o formato de esquema correto, peça ao agente para recomendar um tipo com base na estrutura da consulta ou nas colunas do banco de dados antes de criar itens de contexto. O agente explica o raciocínio para ajudar você a entender as opções de contexto.

Você pode usar os seguintes exemplos de comandos para instruir o agente:

  • "Continuo escrevendo o filtro departure_time BETWEEN '00:00:00' AND '06:00:00' em várias consultas. Qual é a melhor maneira de capturar isso?"
  • "Os usuários descrevem o status do voo em texto livre, e eu quero associar essas informações a flights.status. Que tipo de pesquisa de valor devo configurar?"
  • "Qual é a diferença entre um modelo e uma faceta, e quando devo usar cada um?"

Aplicar operações em massa a um conjunto de contexto

O agente é compatível com atualizações em massa para gerenciar grandes conjuntos de contexto de maneira consistente. Se você precisar atualizar vários itens de contexto simultaneamente, como quando uma coluna de banco de dados é renomeada, um valor de código muda de formato ou os modelos fazem referência a uma tabela descontinuada, o agente poderá aplicar a mudança em todos os itens afetados sem alterar entradas não relacionadas.

Você pode usar os seguintes exemplos de comandos para instruir o agente:

  • "Leia golden.txt e transforme todos os pares em modelos."
  • Em context_set.json, substitua airline = 'UA' por airline = 'United Airlines' em qualquer item que faça referência a "United". Não mexa em itens não relacionados."

A seguir