# Context Engineering Agent
The **Context Engineering Agent** is an AI coding agent plugin designed to run in developer agent harnesses (such as Claude Code, Antigravity, or Gemini CLI). It generates, evaluates, and iteratively tunes tailored context artifacts (`ContextSets` comprising `Templates`, `Facets`, and `Value Searches`) to enrich database schemas for **Gemini Data Analytics's data agent developer platform tools**, supporting both **relational SQL** and **Graph Query Language (GQL)** across [AlloyDB](https://docs.cloud.google.com/gemini/data-agents/querydata/alloydb/data-agent-overview), Cloud SQL ([PostgreSQL](https://docs.cloud.google.com/gemini/data-agents/querydata/sql-postgres/data-agent-overview) / [MySQL](https://docs.cloud.google.com/gemini/data-agents/querydata/sql-mysql/data-agent-overview)), and [Cloud Spanner (GoogleSQL, Spanner Graph, and PostgreSQL)](https://docs.cloud.google.com/gemini/data-agents/querydata/spanner/data-agent-overview).
---
## Why Context Engineering?
When building data agents and natural language analytics interfaces, accurately translating user intent into database queries—whether relational SQL (PostgreSQL, GoogleSQL, MySQL), pure GQL, or hybrid graph queries—is critical.
As outlined in **Build Context with Context Engineering Agent** ([AlloyDB](https://docs.cloud.google.com/gemini/data-agents/querydata/alloydb/build-context-gemini-cli) | Cloud SQL: [PostgreSQL](https://docs.cloud.google.com/gemini/data-agents/querydata/sql-postgres/build-context-gemini-cli) / [MySQL](https://docs.cloud.google.com/gemini/data-agents/querydata/sql-mysql/build-context-gemini-cli) | [Spanner](https://docs.cloud.google.com/gemini/data-agents/querydata/spanner/build-context-gemini-cli)), by optimizing a `ContextSet` to match your application's expected query stream, the **QueryData API** acts as a data agent tool capable of achieving **~100% NL-to-SQL/GQL translation accuracy with low latency**.
---
## Core Concepts
A `ContextSet` is the central artifact generated and managed by the agent, containing structured knowledge across SQL and GQL query domains in three primary forms:
* **Templates**: Link natural language query patterns to complete query statements (supporting relational SQL, pure GQL with `GRAPH ... MATCH`, and hybrid `GRAPH_TABLE` queries for Spanner Graph).
* **Facets**: Reusable, modular query fragments (e.g., parameterized `WHERE` clauses, specialized join filters, or graph `MATCH` traversal patterns) linked to domain vocabulary.
* **Value Searches**: Specialized mapping queries that dynamically resolve user-supplied values (e.g., *"Lndn"*) to database records (*"London"*) via the capabilities of the underlying database, such as embedding search, AI operators, or trigram search on relational and graph property tables.
For full schema details, structure specifications, and dialect-specific JSON representations of `ContextSets`, see the official **Context Sets Overview** ([AlloyDB](https://docs.cloud.google.com/gemini/data-agents/querydata/alloydb/context-sets-overview) | Cloud SQL: [PostgreSQL](https://docs.cloud.google.com/gemini/data-agents/querydata/sql-postgres/context-sets-overview) / [MySQL](https://docs.cloud.google.com/gemini/data-agents/querydata/sql-mysql/context-sets-overview) | [Spanner](https://docs.cloud.google.com/gemini/data-agents/querydata/spanner/context-sets-overview)).
---
## Prerequisites & Environment Setup
Before getting started, prepare your GCP environment, required APIs (Data Analytics API, Gemini for Google Cloud API, Dataplex Universal Catalog API), IAM permissions, and database Data API settings.
Follow the step-by-step setup guide in the official documentation:
👉 **Prepare Your Environment**: ([AlloyDB](https://docs.cloud.google.com/gemini/data-agents/querydata/alloydb/build-context-gemini-cli#prepare-your-environment) | Cloud SQL: [PostgreSQL](https://docs.cloud.google.com/gemini/data-agents/querydata/sql-postgres/build-context-gemini-cli#prepare-your-environment) / [MySQL](https://docs.cloud.google.com/gemini/data-agents/querydata/sql-mysql/build-context-gemini-cli#prepare-your-environment) | [Spanner](https://docs.cloud.google.com/gemini/data-agents/querydata/spanner/build-context-gemini-cli#prepare-your-environment))
### Context Set server access
The plugin talks to the **Context Set server** (upload / read / delete context sets) through a remote Google-hosted MCP server, authenticated with your Application Default Credentials. Before launching your agent, run:
```bash
gcloud auth application-default login
gcloud auth application-default set-quota-project <your-project>
```
Antigravity and Gemini CLI attach the credentials automatically; Claude Code does so through a small helper script bundled with the plugin (needs `gcloud` on your `PATH`). Details in [docs/development.md](docs/development.md#context-set-server-ctxset).
---
## Primary Workflow Phases
The agent enables you to craft an optimized context for QueryData API through three primary phases. Depending on your needs, you may also toggle the agent to skip phases. For example, if you have a dataset already, you can skip directly to context optimization "optimize context using dataset in \<file\>."
### Phase 1: Artifact Ingestion
*Why it matters: Without broader context on the application's goals and scope, AI models generate sterile queries based solely on database column names, missing how your users actually ask for information.*
1. **Connect & Discover**: Inspect any resources shared with the agent that may be relevant to your application and its domain.
2. **Domain Concept Extraction**: Extract key terminology, domain rules, jargon, and common query patterns.
3. **Schema Mapping**: Map extracted concepts directly to their corresponding underlying database tables and columns.
### Phase 2: Dataset Creation
*Why it matters: A realistic golden dataset establishes your benchmark for accuracy, ensuring your data agent is evaluated against messy human language rather than artificially simple database queries.*
1. **Dataset Planning**: Set goals for your dataset, deciding on question difficulty, business topics to cover, and total dataset size.
2. **Initial Question Generation**: Create a core set of natural language questions grounded in your business documents, verifying that each question's corresponding query runs accurately on your database.
3. **Dataset Expansion**: Scale up the question set by adding real-world variations, such as different human phrasing, complex combinations of joins and measures, and realistic values—to cover the ambiguity of natural language.
4. **Dataset Validation**: Audit the full dataset against your original plan and ask for your approval before proceeding.
### Phase 3: Context Optimization via Recursive Hill-Climbing
*Why it matters: Iterative evaluation and gap analysis systematically fix query translation failures, driving accuracy toward ~100% while ensuring fixes don't break previously working queries.*
The optimization loop creates an initial `ContextSet` and then iteratively refines it using evaluation feedback:
1. **Bootstrap**: Generate an initial baseline context.
2. **Evaluate**: Measure context effectiveness against a golden dataset.
3. **Hill-Climbing**: Perform gap analysis on failures and generate automated fixes.
4. **Iterate**: Apply the improved context and re-run evaluation to continuously improve quality until we reach an optimal point.
*Note: While there is a typical ordering for these CUJs, the agent is flexible in how you want to execute. You can run the full pipeline end-to-end, trigger any individual phase, or ask for targeted changes to the `ContextSet`.*
---
## Bring Artifacts via Filesystem or MCP
To prevent the AI from generating trivial schema-only questions (e.g., *"What is the count of users?"*), the agent bridges the semantic gap by grounding context generation in real-world business documents—such as **product glossaries**, **business wikis**, **SOPs**, **ORM data models**, **emails**, or **application or database logs**.
You can provide business artifacts directly to the agent from local filesystems or via **Model Context Protocol (MCP) Servers**.
---
## Installing via a compatible Agent Plugins client
This repository ships a valid [Agent Plugins](https://github.com/agentplugins/agent-plugins-spec) (v1) plugin under [`plugin/`](plugin/), bundling both agent skills and its MCP servers. Any [Agent Plugins–compatible client](https://agent-plugins.org/compatible-clients) (VS Code, Cursor, GitHub Copilot, Kiro, and others) can install it directly using its own built-in plugin command — no extra tooling required — by pointing at this repository:
```
https://github.com/GoogleCloudPlatform/db-context-enrichment
```
See your agent's documentation for its exact install command.
---
## How to Use
Launch your agent harness (Gemini CLI, Claude Code, or Antigravity) in your workspace directory and interact in natural language:
### Example Natural Language Prompts
* **End-to-End**: (From the app directory) *"Optimize context for my app."*
* **Dataset Curation**: *"Expand my dataset with app changes in `<PULL_REQUEST_LINK>`."*
* **Ad-hoc Evaluation**: *"Evaluate accuracy of QueryData with `ContextSet` `<context_set_id>` on dataset.json."*
* **Targeted Authoring**: *"Add a facet for active premium subscriptions."*
---
> 🛠️ **Developer Note**: For developer setup instructions, local CLI linking, unit testing (`pytest`), linting (`ruff`), and fork release testing, see [docs/development.md](docs/development.md).