Criar conjuntos de contexto usando o agente de engenharia de contexto

Neste documento, descrevemos como criar e otimizar os conjuntos de contexto que ajudam a alcançar alta precisão de consulta do QueryData nos 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 precisão do modelo de texto para consulta normalmente precisa atingir quase 100% de qualidade. O SQL gerado incorretamente afeta 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 usar a engenharia de contexto, que é o processo de criar e otimizar iterativamente o contexto para alcançar a precisão ideal.

Ao fornecer ao QueryData o contexto direcionado 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.

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 ad hoc e otimizar seu contexto. A lista a seguir mostra exemplos de comandos de linguagem natural que você pode usar para instruir o agente, além de uma descrição de como o agente 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, raciocina sobre o domínio do 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 massa suas entradas e atualiza o conjunto de contexto.

Importância do conjunto de dados de referência

Para otimizar o contexto, você precisa criar 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 de ouro, que consiste em perguntas dos usuários e consultas de banco de dados esperadas. Com um conjunto de dados de referência, é possível:

  • Estabeleça uma referência para o desempenho da consulta.
  • Validar as atualizações em relação às consultas de banco de dados de informações empíricas.
  • Medir as melhorias de precisão em todas as iterações.

O processo sistemático de subida de encosta

Na escalada sistemática, o agente melhora iterativamente um conjunto de contexto avaliando o conjunto de dados de referência, analisando lacunas e fazendo atualizações para aumentar a precisão para quase 100%.

  • Gerar automaticamente o contexto 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 subida de encosta: permita que o agente avalie a precisão do QueryData, realize análises de lacunas em falhas e proponha automaticamente melhorias para aumentar a precisão.

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

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 realizar as etapas deste tutorial, faça login no Google Cloud e autentique-se no 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 realize pesquisas de valor de trigrama, 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, conclua as seguintes etapas:

  • Instalar o agente de engenharia de contexto
  • Configurar a conexão do 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, na sigla em inglês) que requer uv para gerenciar os pacotes Python subjacentes.

  1. Instale a uv seguindo as instruções em Instalar a 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 no arnês de agente selecionado, como a CLI Antigravity, o Claude Code ou a CLI do Gemini.

Dependendo da estrutura de agentes selecionada, 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: 
    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 para a versão mais recente:

agy plugin uninstall google-cloud-db-context-engineering
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin

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

Configurar a conexão do banco de dados

O agente precisa de uma conexão de banco de dados para buscar esquemas e da capacidade de 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 as Application Default Credentials

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

  • Servidor MCP do Toolbox: 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 fazer a autenticação:

gcloud auth application-default login

Configurar o arquivo de conexão do banco de dados

O agente requer uma conexão de banco de dados para a geração de contexto, que é compatível com o MCP Toolbox e definida 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 pré-instaladas para ajudar você a gerar a configuração.

  1. Inicie o ambiente do agente.

  2. Peça ao agente para ajudar a configurar a conexão do banco de dados. Por exemplo, use o comando "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 a conexão:

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

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

Gerar e otimizar o 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. É possível usar essas ferramentas juntas para gerar um valor de referência, medir a eficácia e aplicar melhorias de forma iterativa. No entanto, é possível começar em qualquer estágio do fluxo de trabalho:

  • Se você já tiver um conjunto de contexto, poderá prosseguir diretamente para a avaliação.
  • Se você tiver consultas com falha que quer corrigir, prossiga diretamente 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 a performance, primeiro é preciso medi-la. A engenharia de contexto sem um conjunto de dados de ouro, que consiste em perguntas de usuários pareadas 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 às informações empíricas.

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

  • Gerar pares de perguntas e SQL candidatos com base no esquema do banco de dados.
  • Expandir um pequeno conjunto de dados inicial usando variações de filtro, sinônimos e reformulações.

Se quiser, você pode permitir que o agente execute o SQL gerado no seu banco de dados. Essa verificação confirma que as consultas são executadas com sucesso 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.

Use 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 contextos de referência

Para evitar a criação de contexto do zero, deixe o agente derivar um conjunto inicial de contexto 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 referência não seja definitivo, ele fornece um ponto de partida validado com base no seu modelo de banco de dados.

Use os seguintes exemplos de comandos para instruir o agente:

  • "Gere um conjunto de contexto com base no meu esquema."
  • "Gere o contexto inicial usando esses 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 referência, você pode permitir que o agente meça o desempenho do contexto consultando a API QueryData do agente de dados com cada pergunta de referência. O agente compara o SQL gerado e os resultados da execução com a resposta esperada usando o Evalbench para processar a comparação.

A execução de uma avaliação fornece 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/ na 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 .

Use os exemplos de comandos a seguir para instruir o agente:

  • "Avalie meu contexto em relação a golden.json."
  • "Refazer a avaliação 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 as 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, mesclagens de tabelas ausentes ou termos imprecisos 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 direcionadas, como modelos, facetas ou pesquisas de valor.
  • Correções propostas: o agente propõe edições concretas e, opcionalmente, testa o SQL no banco de dados para verificar a resolução.
  • Preservação do valor de referência: o agente grava as melhorias em um novo arquivo JSON com o contexto de referência, preservando os arquivos originais.

Use os exemplos de comandos a seguir 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 lida com a formatação JSON para que você possa se concentrar na sua intenção de negócios.

Também é possível usar esse recurso para atualizações ad hoc, como quando você precisa oferecer suporte a um novo padrão de consulta ou corrigir um detalhe de esquema ausente. Para receber o JSON, descreva o contexto necessário para o agente sem executar uma avaliação ou configurar um experimento.

Essa também é a capacidade certa 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 gerar o JSON.

Use os exemplos de comandos a seguir para instruir o agente:

  • "Crie um modelo para: 'Quais aeroportos estão na Califórnia?' com o 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 da seleção do tipo de contexto

Selecionar o tipo de contexto correto, seja uma pesquisa de modelo, atributo ou valor, ajuda a evitar o excesso de contexto e as regressões de consulta do banco de dados. Por exemplo, usar um modelo em vez de uma faceta pode causar regras duplicadas, enquanto as pesquisas de valor introduzidas em que 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.

Use os seguintes exemplos de comandos para instruir o agente:

  • "Eu 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 quero que eles correspondam 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 em um conjunto de contexto

O agente oferece suporte a atualizações em massa para gerenciar grandes conjuntos de contexto de forma 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 pode aplicar a mudança em todos os itens afetados sem alterar as entradas não relacionadas.

Use 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