Build context sets using the context engineering agent

This document describes how to create and optimize the context sets that help achieve high QueryData accuracy for your Spanner Graph data agent applications. The context engineering agent helps you build, evaluate, and improve Graph Query Language (GQL) context sets by automating their creation and optimization.

To learn about context sets and QueryData for Spanner Graph, see Context sets overview and QueryData overview.

To build enterprise graph data applications, natural language-to-GQL translation accuracy typically needs to achieve near-100% quality. Incorrect graph traversal patterns or missing edge filters affect application usability and user experience. Achieving explainable, business-relevant answers with high accuracy requires context engineering, which is the process of creating and iteratively optimizing the context set.

By providing QueryData with context targeted to your Spanner Graph schema and business application, you supply the precise graph traversal rules and domain definitions the system needs to resolve nuanced user intent.

The examples in this document use the FinGraph property graph schema and sample dataset (Person and Account nodes connected by Owns and Transfers edges). To create the FinGraph schema and insert the sample data, see Set up and query Spanner Graph.

Context engineering agent

The context engineering agent automates the context engineering workflow: it generates evaluation datasets, bootstraps a context set, and iteratively improves it.

The following list provides examples of natural language prompts to instruct the agent, along with a description of how the agent responds:

  • Example prompt for context suggestion: "Read my application document for the FinGraph property graph in my Spanner database and suggest GQL context items to add." The agent parses the dataset application documents you provide, maps business rules to FinGraph node and edge labels, and suggests GQL templates and facets.
  • Example prompt for gap analysis when user questions don't return expected results: "When users ask 'transfers from rainy day account', QueryData filters on nick_name = 'rainy day account' and returns nothing. Update the context for the FinGraph property graph in my Spanner database so that this question is answered correctly." The agent inspects the schema, identifies that the nickname is stored as Rainy Day Fund, and recommends a value search on Account.nick_name (or a template or facet if the pattern is the problem).
  • Example prompt for bulk processing: "Here are natural language questions and GQL queries for the FinGraph property graph in my Spanner database. Turn them into templates:

    • Find everyone that Dana transferred money to, with the amounts: GRAPH FinGraph MATCH (:Person {name: 'Dana'})-[:Owns]->(:Account)-[transfer:Transfers]->(:Account)<-[:Owns]-(to_person:Person) RETURN to_person.name AS recipient, transfer.amount AS amount
    • Which high-risk transfers did Alex make? GRAPH FinGraph MATCH (:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount"

    The agent bulk-processes your inputs, replaces literal values with ? placeholders, and updates your context set file.

Importance of the golden dataset

To optimize your context, you must first create a golden dataset that matches the natural language inputs of your application. The agent can help you build this golden dataset, which consists of user questions paired with their expected GQL queries. A golden dataset lets you do the following:

  • Establish a baseline for natural language-to-GQL query performance.
  • Validate context updates against ground-truth GQL queries.
  • Measure accuracy improvements across optimization iterations.

The systematic hill-climbing process

In systematic hill-climbing, the agent iteratively improves a context set through evaluation of the golden dataset, gap analysis, and targeted GQL context update to drive accuracy toward near-100%:

  • Auto-generate baseline context: Create a starting GQL context set derived from your Spanner Graph property graph schema and application artifacts.
  • Hill-climbing optimization workflow: Let the agent evaluate your QueryData accuracy with graph_ids configured, perform gap analysis on failing GQL queries, and automatically propose improvements to drive accuracy higher.

The following diagram shows the systematic hill-climbing workflow:

Workflow for iteratively building context.

Before you begin

Complete the following prerequisites before using the context engineering agent:

Enable required services

Enable the following services for your project:

Prepare a Spanner instance

Required roles and permissions

  • Add an IAM user or service account to the instance. For more information, see Apply IAM roles.
  • Grant the roles/spanner.databaseReader, roles/serviceusage.serviceUsageConsumer, and roles/geminidataanalytics.queryDataUser roles to the IAM user at the project level. For more information, see Add IAM policy binding for a project.
  • To create, upload, and manage context sets, grant the Dataplex Catalog Editor (roles/dataplex.catalogEditor) or Dataplex Catalog Admin (roles/dataplex.catalogAdmin) role to the IAM user at the project level. For more information, see Context sets permissions.
  • Grant roles and permissions to the IAM user at the project-level for the required databases.

To set up the FinGraph property graph schema and insert the sample graph data used in this guide, follow the steps in Set up and query Spanner Graph.

Prepare your environment

You can build context set files from any local development environment or IDE. To prepare your environment, complete the following steps:

  • Install the context engineering agent.
  • Set up the database connection to Spanner Graph.

Install the context engineering agent

The context engineering agent runs a Model Context Protocol (MCP) server that requires uv to manage underlying Python packages.

  1. Install uv by following the instructions in Install uv.
  2. Verify that uv is installed and accessible from your command line:

    uv --version

To prepare your environment, install the context engineering agent in your selected agent harness, such as the Antigravity CLI, Claude Code, or the Gemini CLI.

Depending on your selected agent harness, follow the corresponding installation steps:

Antigravity CLI

To install the context engineering agent in the Antigravity CLI, follow these steps:

  1. Install the Antigravity CLI. See Get Started with Antigravity CLI.
  2. Install the context engineering agent plugin, which includes workflows for context generation:
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin
  3. Start the Antigravity CLI:
    agy
  4. Update the plugin:
    agy plugin uninstall google-cloud-db-context-engineering
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin

Claude Code

To install the context engineering agent in Claude Code, follow these steps:

  1. Add the plugin marketplace:
    /plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git
  2. Install the plugin:
    /plugin install db-context-engineering@db-context-enrichment-marketplace
  3. Reload plugins to activate the changes:
    /reload-plugins
  4. Update the plugin:
    /plugin update db-context-engineering@db-context-enrichment-marketplace

Gemini CLI (Deprecated)

To install the context engineering agent in the Gemini CLI, follow these steps:

  1. Install the Gemini CLI. See Get Started with Gemini CLI.
  2. Install the extension:
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment
  3. Update the extension:
    gemini extensions update mcp-db-context-enrichment

Set up the database connection

The agent requires a database connection to fetch property graph schemas (spanner-list-graphs), inspect underlying tables (spanner-list-tables), and validate the syntax of generated GQL and SQL queries (spanner-execute-sql). To let the agent interact with the property graph in your Spanner database, configure authentication credentials and define your database connection configuration.

Configure Application Default Credentials

Configure Application Default Credentials (ADC) to provide user credentials for accessing Google Cloud resources from the context engineering agent:

  • Toolbox MCP server: Uses credentials to connect to your Spanner database, fetch property graph schemas, and run GQL queries for validation.
  • Evalbench: Uses credentials to call the QueryData REST API with graph_ids and to run the LLM rater on Vertex AI during evaluation.

Run the following command in your terminal to authenticate:

gcloud auth application-default login

Configure the database connection file

The agent requires a database connection for context generation, which the MCP Toolbox supports and defines within a configuration file (autoctx/tools.yaml), along with a state tracker (autoctx/state.md) that records the active property graph names (such as FinGraph).

  1. Start your agent environment.
  2. Ask the agent to set up the database connection for your Spanner database and specify the property graph name. For example, enter the following prompt:

    Help me set up the database connection for my Spanner database with the FinGraph property graph.
    

    Follow the agent's instructions to provide your project ID, Spanner instance ID, database ID, and property graph name (FinGraph). The agent creates autoctx/tools.yaml (with spanner-list-graphs, spanner-list-tables, and spanner-execute-sql tools) and autoctx/state.md.

  3. Open autoctx/state.md and verify that the ## Active Database section lists your property graph in the following format:

    - **Graph Ids**: ["FinGraph"]
    

    The evaluation workflow reads the property graph IDs only from this line. If the line is missing, empty ([]), or not in this format, the evaluation calls QueryData without graph_ids, and QueryData generates relational SQL instead of GQL.

  4. To apply the new tools.yaml configuration, reload your connection:

    • In the Antigravity CLI, run /mcp and select toolbox to restart.
    • In the Gemini CLI, run /mcp reload.
    • In Claude Code, run /mcp, select toolbox, and select Reconnect.

For more information about manually configuring the database configuration file, see MCP Toolbox Configuration.

Generate and optimize context

The context engineering agent provides a set of Agent Skills and MCP tools to generate a baseline GQL context set, measure effectiveness against a golden GQL dataset, and iteratively apply improvements. You can begin at any stage of the workflow:

  • If you already have a context set, you can proceed directly to evaluation.
  • If you have failing GQL queries that you want to fix, you can proceed directly to gap analysis.

At any stage, remind the agent that the target is a property graph in your Spanner database and name the graph (such as FinGraph), so that it stays in the GQL-specific workflow.

Build and expand evaluation datasets

To improve performance, you must first measure it. A golden dataset is a set of user questions paired with their expected GQL queries. Without one, context engineering lacks systematic verification; with one, every context change is a measurable improvement that you can validate against ground truth.

Creating a representative golden dataset manually is time-consuming, and small datasets might miss variations in user phrasing. The agent resolves this by:

  • Generating candidate natural language questions and GQL query pairs based on your property graph schema.
  • Expanding a seed dataset using filter variations, synonyms, and multi-hop path rephrasings.
  • Executing the generated GQL queries against your Spanner database to confirm that every query runs cleanly and returns valid results.

Based on the FinGraph queries in Spanner Graph queries overview, the golden dataset (autoctx/golden.json) is a JSON file containing natural language question and GQL pairs such as the following:

[
  {
    "id": "fingraph_001",
    "database": "example-db",
    "nlq": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.",
    "golden_sql": "GRAPH FinGraph MATCH (from_person:Person {name: 'Dana'})-[:Owns]->(from_account:Account)-[transfer:Transfers]->(to_account:Account)<-[:Owns]-(to_person:Person) RETURN to_person.name AS to_account_owner, to_account.id AS to_account_id, transfer.amount AS amount;"
  },
  {
    "id": "fingraph_002",
    "database": "example-db",
    "nlq": "Find all money transfers involving a blocked account.",
    "golden_sql": "GRAPH FinGraph MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true}) RETURN transfer.order_number, transfer.amount;"
  },
  {
    "id": "fingraph_003",
    "database": "example-db",
    "nlq": "Find destination accounts that are 1 to 3 transfers away from account 7, and show the path length.",
    "golden_sql": "GRAPH FinGraph MATCH (src:Account {id: 7})-[e:Transfers]->{1, 3}(dst:Account) WHERE src != dst RETURN dst.id AS dst_account_id, ARRAY_LENGTH(e) AS path_length;"
  },
  {
    "id": "fingraph_004",
    "database": "example-db",
    "nlq": "Find all high-risk transfers initiated by Alex.",
    "golden_sql": "GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;"
  }
]

Approved pairs populate the autoctx/golden.json file in your workspace, where they are ready for evaluation. In each entry, database must match your Spanner database ID (such as example-db).

You can use the following example prompts to instruct the agent, specifying that FinGraph is a property graph in your Spanner database:

  • "Generate a GQL evaluation dataset from the FinGraph property graph in my Spanner database."
  • "Here's a seed question and GQL query for the FinGraph property graph in my Spanner database. Expand it into a broader GQL evaluation dataset and verify that the queries run."

Generate a baseline context set

To avoid creating context from scratch, you can let the agent derive an initial GQL context set (bootstrap_context.json) from your property graph schema and application artifacts, such as business rules, sample GQL queries, or design documents. Because your dataset is a property graph in your Spanner database, the agent prefers GQL patterns (GRAPH FinGraph MATCH ...) over relational SQL joins when generating templates and facets.

You can use the following example prompts to instruct the agent:

  • "Generate a baseline GQL context set from the FinGraph property graph in my Spanner database."
  • "Generate initial GQL context for the FinGraph property graph in my Spanner database using the property graph schema and the business rules in requirements.md."

The agent prompts you to name the experiment (for example, fingraph_tuning), which organizes generated artifacts under autoctx/experiments/fingraph_tuning/. After the agent generates bootstrap_context.json, follow the instructions in Manage context sets in Spanner Studio to upload the context set file.

Evaluate context effectiveness

After you establish a context set and a golden dataset, you can let the agent measure context performance by querying the QueryData API with each golden question. The agent compares the generated GQL and execution results against the expected golden answers using Evalbench.

For Spanner Graph, the evaluation calls the QueryData REST API directly so that each request can include graph_ids.

When autoctx/state.md contains - **Graph Ids**: ["FinGraph"], the agent generates an Evalbench model configuration file (autoctx/experiments/fingraph_tuning/eval_configs/model_config.yaml) that uses the REST API and includes graph_ids in spanner_reference.database_reference, similar to the following:

generator: query_data_api
project_id: PROJECT_ID
location: global
use_rest_api: true
context:
  datasource_references:
    spanner_reference:
      database_reference:
        engine: GOOGLE_SQL
        project_id: PROJECT_ID
        instance_id: INSTANCE_ID
        database_id: DATABASE_ID
        graph_ids:
        - FinGraph
      agent_context_reference:
        context_set_id: projects/PROJECT_ID/locations/REGION/contextSets/CONTEXT_SET_ID

Before you run an evaluation, open model_config.yaml and verify that use_rest_api is true and that graph_ids lists your property graph.

Running an evaluation provides the following:

  • Quantitative metrics, such as pass and fail results and aggregate scores, to track progress across GQL context iterations.
  • An inline conversation summary and detailed CSV reports written to the eval_reports/ directory in your experiment folder.

To start an evaluation, provide the golden dataset path (autoctx/golden.json) and the context set ID. To learn how to find the context set ID, see Find the context set ID.

You can use the following example prompts to instruct the agent:

  • "Evaluate my context for the FinGraph property graph in my Spanner database against autoctx/golden.json. Call the QueryData REST API with graph_ids set to FinGraph."
  • "Re-run the evaluation for the FinGraph property graph in my Spanner database using the configuration from my last experiment."

To re-run a previously generated evaluation configuration directly from your workspace root, run the following command:

uvx google-evalbench --experiment_config=autoctx/experiments/fingraph_tuning/eval_configs/run_config.yaml

For details on the evaluation configuration schema and how to customize evaluation runs, see the Evalbench documentation.

Perform gap analysis and propose improvements

To resolve GQL query failures, identify their root causes, such as the following:

  • Reversed edge directions (-[:Owns]-> versus <-[:Owns]-)
  • Missing quantified path bounds (->{1, 3})
  • Unmapped business definitions (such as high-risk transfers)
  • Unresolved property values

For query syntax, see Spanner Graph queries overview and the GQL reference.

The agent automates this analysis and correction loop for the property graph in your Spanner database:

  • Gap analysis: The agent reads evaluation results and your context set to group similar GQL failures and recommend targeted additions, such as GQL templates, facets, or GRAPH_TABLE value searches on node and edge properties.
  • Proposed fixes: The agent proposes concrete GQL context edits and tests the generated GQL against your Spanner database using spanner-execute-sql to verify the resolution.
  • Baseline preservation: The agent writes the improvements to a new JSON file (improved_context_v1.json) alongside your baseline context, preserving the original files.

You can use the following example prompts to instruct the agent, specifying that the dataset is a property graph in your Spanner database to trigger the GQL-specific context engineering workflow:

  • "Run gap analysis on my last evaluation for the FinGraph property graph in my Spanner database and propose GQL context fixes."
  • "Optimize this context set for the FinGraph property graph in my Spanner database against autoctx/golden.json."

To prepare for the next iteration, upload the improved context set file (improved_context_v1.json) to your target context set in Spanner Studio by following the instructions in Edit a context set.

Author specific context items on demand

If you already know the context item that you need (such as a GQL template for a specific graph traversal, a facet for a repeated edge filter, or a GRAPH_TABLE value search on a node or edge property), the agent can generate the properly parameterized JSON object on demand without running a full evaluation.

You can use the following example prompts to instruct the agent for the property graph in your Spanner database:

  • "For the FinGraph property graph in my Spanner database, create a template for: 'Find all high-risk transfers initiated by Alex' with the GQL query: GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;."
  • "For the FinGraph property graph in my Spanner database, create a facet for the GQL clause MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true}) labeled 'transfers involving a blocked account'."
  • "For the FinGraph property graph in my Spanner database, create a GRAPH_TABLE value search on the nick_name property of Account nodes with concept type 'Account nickname' that matches nicknames case-insensitively."

Reason about context type selection

Selecting the appropriate context type (a GQL template, a facet, or a value search) helps prevent context bloat and query regressions. You can prompt the agent to recommend the right context type based on your query patterns:

  • "In the FinGraph property graph in my Spanner database, I keep filtering for transfers involving blocked accounts with MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true}) across many GQL queries. What's the best way to capture this?"
  • "Users refer to accounts in the FinGraph property graph in my Spanner database by nicknames such as 'Vacation Fund' or 'Rainy Day Fund'. What kind of GRAPH_TABLE value search should I set up on Account.nick_name?"
  • "What's the difference between a GQL template and a facet in a context set for Spanner Graph, and when should I use each?"

Apply bulk operations across a context set

The agent supports bulk updates to manage large GQL context sets consistently, such as when a property graph label is updated or a business threshold changes across multiple templates and facets:

  • "Read golden.json for the FinGraph property graph in my Spanner database and turn all the question-GQL pairs into templates."
  • "In context_set.json for the FinGraph property graph in my Spanner database, replace t.amount >= 200 with t.amount >= 300 for any GQL item referencing 'high-risk transfers'. Leave unrelated items alone."

What's next