Kontextsets mit dem Kontext-Engineering-Agent erstellen

In diesem Dokument wird beschrieben, wie Sie die Kontextsets erstellen und optimieren, mit denen Sie eine hohe Genauigkeit bei QueryData-Abfragen in Ihren Daten-Agent-Anwendungen erzielen können. Der Context Engineering-Agent unterstützt Sie beim Erstellen, Bewerten und Verbessern von Kontextsets, indem er die Erstellung und Optimierung automatisiert.

Weitere Informationen zu Kontextsets und QueryData finden Sie unter Kontextsets und QueryData.

Um Datenanwendungen für Unternehmen zu erstellen, muss die Genauigkeit des Text-zu-SQL-Modells in der Regel nahezu 100% erreichen. Falsche Abfrageergebnisse beeinträchtigen die allgemeine Nutzerfreundlichkeit der Anwendung und die Nutzererfahrung. Um nachvollziehbare, geschäftsrelevante Antworten mit hoher Genauigkeit zu erhalten, ist Context Engineering erforderlich. Dabei wird der Kontext erstellt und iterativ optimiert, um eine optimale Genauigkeit zu erzielen.

Wenn Sie QueryData mit dem Kontext für Ihre Geschäftsanwendung bereitstellen, geben Sie die genauen Geschäftsregeln an, die das System benötigt, um differenzierte Nutzerabsichten zu erkennen.

KI-Agent für Context Engineering

Der Context Engineering-Agent automatisiert diesen Optimierungsworkflow. Sie können sich mit dem Agent unterhalten, um Ad-hoc-Aufgaben zur Optimierung Ihres Kontexts zu erledigen. In der folgenden Liste finden Sie Beispiele für Prompts in natürlicher Sprache, mit denen Sie den Agenten anweisen können, sowie eine Beschreibung der Reaktion des Agenten. Diese Beispiele können Ihnen helfen, Ihren Kontext zu erstellen und zu optimieren:

  • Beispiel-Prompt für die Fehleranalyse: „Aktualisiere den Kontext, damit wir den Flughafen für Anfragen wie ‚Flüge nach Disney World‘ richtig identifizieren.“ Der Agent analysiert den Fehler, begründet die Lücke und empfiehlt, ein geeignetes Kontext-Element hinzuzufügen, z. B. eine Wertesuchanfrage.
  • Beispielprompt für Kontextvorschläge: „Lies meinen App-Code und schlage Kontext vor, der hinzugefügt werden kann.“ Der KI-Agent analysiert den Code, zieht Rückschlüsse auf die Domain Ihrer Anwendung und schlägt vor, welche Kontext-Elemente relevant wären.
  • Beispiel-Prompt für die Bulk-Verarbeitung: „Hier sind 10 Beispiele für Fragen und SQL-Abfragen. Sie in Vorlagen umzuwandeln.“ Der KI-Agent verarbeitet Ihre Eingaben im Bulk und aktualisiert Ihren Kontextsatz.

Bedeutung des Goldstandard-Datasets

Um Ihren Kontext zu optimieren, müssen Sie zuerst ein Dataset erstellen, das den Eingaben in natürlicher Sprache Ihrer Anwendung entspricht. Der Agent kann Ihnen helfen, dieses Gold-Dataset zu erstellen, das aus Nutzerfragen und den zugehörigen erwarteten Datenbankabfragen besteht. Mit einem goldenen Dataset haben Sie folgende Möglichkeiten:

  • Eine Baseline für die Abfrageleistung festlegen.
  • Aktualisierungen anhand von Ground-Truth-Datenbankabfragen validieren.
  • Genauigkeitsverbesserungen über Iterationen hinweg messen

Der systematische Hillclimbing-Prozess

Beim systematischen Hill Climbing verbessert der Agent eine Reihe von Kontexten iterativ, indem er das Golden Dataset auswertet, eine Lückenanalyse durchführt und Updates vornimmt, um die Genauigkeit auf nahezu 100 % zu steigern.

  • Baseline-Kontext automatisch generieren: Erstellen Sie einen Startkontextsatz, der aus Ihrem Datenbankschema und Ihren Anwendungsartefakten abgeleitet wird.
  • Workflow zur Hill-Climbing-Optimierung: Der Agent kann die Genauigkeit Ihrer QueryData bewerten, eine Lückenanalyse für Fehler durchführen und automatisch Verbesserungen vorschlagen, um die Genauigkeit zu erhöhen.

Das folgende Diagramm zeigt den systematischen Hill Climbing-Workflow:

Workflow für die iterative Erstellung von Kontext.

Hinweis

Erfüllen Sie die folgenden Voraussetzungen, bevor Sie den Kontext-Engineering-Agent verwenden.

Erforderliche Dienste aktivieren

Aktivieren Sie die folgenden Dienste für Ihr Projekt:

Cloud SQL-Instanz vorbereiten

Erforderliche Rollen und Berechtigungen

executesql-Berechtigung für Cloud SQL-Instanz gewähren

Führen Sie den folgenden Befehl aus, um der Cloud SQL-Instanz die Berechtigung executesql zu erteilen und die Cloud SQL Data API zu aktivieren: 
gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
Ersetzen Sie Folgendes:
  • PROJECT_ID: Die ID Ihres Google Cloud -Projekts.
  • INSTANCE_ID: Die ID Ihrer Cloud SQL-Instanz.
Melden Sie sich an, um die Schritte in dieser Anleitung auszuführen Google Cloud und authentifizieren Sie sich dann mit der IAM-Authentifizierung bei der Datenbank.

Datenbank für die Wertsuche vorbereiten

Wenn Sie semantische und Trigramm-Wertsuchen verwenden möchten, müssen Sie Ihre Cloud SQL for MySQL-Instanz so konfigurieren, dass sie Vektoreinbettungen und N-Gramm-Indexierung unterstützt.

  1. Damit die Cloud SQL for MySQL-Instanz semantische Wertesuchen durchführen kann, müssen Sie die folgenden Flags aktivieren.

    1. Aktivieren Sie das Flag cloudsql_vector.

      gcloud sql instances patch INSTANCE_NAME --database-flags=cloudsql_vector=on

    2. Aktivieren Sie das Flag enable-google-ml-integration, damit die Cloud SQL for MySQL-Instanz in Vertex AI eingebunden werden kann.

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

    3. Vektorspalte zum Speichern von Stadteinbettungen erstellen

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

    4. Vektoreinbettungen für Städtenamen generieren und speichern

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

  2. So lassen Sie die Cloud SQL for MySQL-Instanz Trigrammwert-Suchvorgänge ausführen:

    1. Aktivieren Sie das Flag ngram_token_size.

      gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3

    2. Erstellen Sie einen FULLTEXT-Index für den Abgleich von Trigrammen für den Flughafennamen:

      CREATE FULLTEXT INDEX `idx_ngram_airports_name`
ON `airports`(`name`) 
WITH PARSER ngram;

Umgebung vorbereiten

Sie können Kontextset-Dateien in jeder lokalen Entwicklungsumgebung oder IDE erstellen. Führen Sie die folgenden Schritte aus, um die Umgebung vorzubereiten:

  • Context Engineering-Agent installieren
  • Datenbankverbindung einrichten

Context Engineering-Agent installieren

Der Context Engineering-Agent führt einen MCP-Server (Model Context Protocol) aus, für den uv zur Verwaltung der zugrunde liegenden Python-Pakete erforderlich ist.

  1. Installieren Sie uv gemäß der Anleitung unter uv installieren.

  2. Prüfen Sie, ob uv installiert und über die Befehlszeile zugänglich ist:

    uv --version

Installieren Sie den Context Engineering-Agenten in Ihrem ausgewählten Agent-Harness, z. B. der Antigravity CLI, Claude Code oder der Gemini CLI, um Ihre Umgebung vorzubereiten.

Führen Sie je nach ausgewähltem Agent-Harness die entsprechenden Installationsschritte aus:

Antigravity CLI

So installieren Sie den Context Engineering-Agenten in der Antigravity CLI:

  1. Installieren Sie die Antigravity CLI. Weitere Informationen finden Sie unter Erste Schritte mit der Antigravity-Befehlszeile.
  2. Installieren Sie das Agent-Plug-in für Context Engineering, das Workflows für die Kontexterstellung enthält. Ersetzen Sie VERSION durch die erforderliche veröffentlichte Version: 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION
  3. Starten Sie die Antigravity CLI: 
    agy
  4. Optional. Aktualisieren Sie das 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

So installieren Sie den Context Engineering-Agent in Claude Code:

  1. Fügen Sie den Plug-in-Marktplatz hinzu: 
    /plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git
  2. Installieren Sie das Plug-in: 
    /plugin install db-context-engineering@db-context-enrichment-marketplace
  3. Laden Sie die Plug-ins neu, um die Änderungen zu aktivieren: 
    /reload-plugins
  4. Optional. Aktualisieren Sie das Plug-in: 
    /plugin update db-context-engineering@db-context-enrichment-marketplace

Gemini CLI (eingestellt)

So installieren Sie den Context Engineering-Agenten in der Gemini CLI:

  1. Installieren Sie die Gemini CLI. Weitere Informationen finden Sie unter Erste Schritte mit der Gemini CLI.
  2. Installieren Sie die Erweiterung: 
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment
  3. Optional. So aktualisieren Sie die Erweiterung: 
    gemini extensions update mcp-db-context-enrichment

Datenbankverbindung einrichten

Der Agent benötigt eine Datenbankverbindung, um Schemas abzurufen, und die Möglichkeit, die Syntax des generierten SQL-Kontexts zu validieren. Damit der Agent mit Ihrer Datenbank interagieren kann, müssen Sie Authentifizierungsanmeldedaten konfigurieren und die Konfiguration Ihrer Datenbankverbindung definieren.

Standardanmeldedaten für Anwendungen konfigurieren

Konfigurieren Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC), um Nutzeranmeldedaten für den Zugriff auf Google Cloud -Ressourcen über den Kontext-Engineering-Agent bereitzustellen:

  • Toolbox-MCP-Server: Verwendet Anmeldedaten, um eine Verbindung zu Ihrer Datenbank herzustellen, Schemas abzurufen und SQL zur Validierung auszuführen.
  • Evalbench: Verwendet Anmeldedaten, um QueryData für die Bewertung aufzurufen.

Führen Sie im Terminal die folgenden Befehle aus, um sich zu authentifizieren:

gcloud auth application-default login

Datei für die Datenbankverbindung konfigurieren

Für die Kontexterstellung benötigt der KI-Agent eine Datenbankverbindung, die von der MCP Toolbox unterstützt und in einer Konfigurationsdatei definiert wird.

In der Konfigurationsdatei werden Ihre Datenbankquelle und die Tools angegeben, die zum Abrufen von Schemas oder zum Ausführen von SQL erforderlich sind. Der Agent für Kontext-Engineering enthält vorinstallierte Agent-Skills, die Ihnen beim Generieren der Konfiguration helfen.

  1. Starten Sie die Agent-Umgebung.

  2. Bitten Sie den Agenten, Ihnen beim Einrichten der Datenbankverbindung zu helfen, z. B. mit dem Prompt „Hilf mir beim Einrichten der Datenbankverbindung“. Folgen Sie der Anleitung des Kundenservicemitarbeiters, um die Konfigurationsdatei in Ihrem aktuellen Arbeitsverzeichnis als autoctx/tools.yaml zu erstellen.

  3. So wenden Sie die neue tools.yaml-Konfiguration an:

    • Führen Sie in der Antigravity-Befehlszeile /mcp aus und wählen Sie toolbox aus, um das Gerät neu zu starten.
    • Führen Sie in der Gemini CLI /mcp reload aus.
    • Führen Sie in Claude Code /reload-plugins aus.

Weitere Informationen zum manuellen Konfigurieren der Datenbankkonfigurationsdatei finden Sie unter MCP Toolbox-Konfiguration.

Kontext generieren und optimieren

Der Context Engineering-Agent bietet eine Reihe von Agent Skills und MCP-Tools, um die Context Engineering-Funktionen Ihres Coding-Agenten zu verbessern. Sie können diese Tools zusammen verwenden, um eine Baseline zu erstellen, die Effektivität zu messen und iterativ Verbesserungen vorzunehmen. Sie können jedoch in jeder Phase des Workflows beginnen:

  • Wenn Sie bereits einen Kontext festgelegt haben, können Sie direkt mit der Evaluierung fortfahren.
  • Wenn Sie fehlerhafte Anfragen haben, die Sie korrigieren möchten, können Sie direkt mit der Lückenanalyse fortfahren.

Jede Funktion beschreibt die Aktionen, Anwendungsfälle und Aufruf-Befehle des Agenten.

Die Beispielprompts zeigen, wie Sie den Agent in natürlicher Sprache abfragen können. Wenn der Agent zusätzliche Details benötigt, um eine Anfrage zu bearbeiten, werden Sie aufgefordert, die Anfrage zu präzisieren.

Bewertungs-Datasets erstellen und erweitern

Um die Leistung zu verbessern, müssen Sie sie zuerst messen. Beim Context Engineering ohne einen Golden Dataset, der aus Nutzerfragen in Kombination mit dem erwarteten SQL besteht, fehlt die systematische Überprüfung. Mit einem Golden Dataset ist jede Änderung eine messbare Verbesserung, die Sie anhand der Ground Truth validieren können.

Das manuelle Erstellen eines repräsentativen Golden-Datasets ist zeitaufwendig und bei kleinen Datasets werden möglicherweise Variationen in der Formulierung der Nutzer nicht berücksichtigt. Der Agent löst das Problem so:

  • Es werden mögliche Frage-SQL-Paare auf Grundlage Ihres Datenbankschemas generiert.
  • Ein kleines Seed-Dataset wird mithilfe von Filtervariationen, Synonymen und Umformulierungen erweitert.

Optional können Sie den KI-Agenten die generierte SQL-Anweisung für Ihre Datenbank ausführen lassen. Durch diese Überprüfung wird bestätigt, dass Abfragen erfolgreich ausgeführt werden, bevor Sie sie dem Dataset hinzufügen.

Das Dataset ist eine JSON-Datei mit Frage-SQL-Paaren:

[
  {
    "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;"
  }
]

Genehmigte Paare werden in die Datei autoctx/golden.json in Ihrem Arbeitsbereich eingefügt und können dort ausgewertet werden. Sie können eine vorhandene Datei bereitstellen oder einige Bewertungsbeispiele inline für den Agenten schreiben, damit er sie erweitert.

Sie können die folgenden Beispiel-Prompts verwenden, um den Agenten anzuweisen:

  • „Erstelle ein Bewertungs-Dataset aus meinem Schema.“
  • „Hier ist eine Ausgangsfrage und SQL – erweitere sie zu einem umfassenderen Dataset und prüfe, ob die Abfragen ausgeführt werden.“

Baseline-Kontextset generieren

Damit Sie den Kontext nicht von Grund auf neu erstellen müssen, kann der KI-Agent einen ersten Kontextsatz aus Ihrem Datenbankschema und Ihren Anwendungsartefakten wie Geschäftsregeln, Beispielabfragen oder README-Dateien ableiten. Dieser Baseline-Kontext ist zwar nicht endgültig, bietet aber einen validierten Ausgangspunkt, der auf Ihrem Datenbankmodell basiert.

Sie können die folgenden Beispiel-Prompts verwenden, um den Agenten anzuweisen:

  • Erstelle einen Kontextsatz aus meinem Schema.
  • „Generiere den anfänglichen Kontext mit diesen Schemas und den Geschäftsregeln in requirements.md.“

Der Agent fordert Sie auf, dem Test einen Namen zu geben, um die generierten Artefakte zu organisieren. Wenn Ihr Datenbankschema groß ist, werden Sie möglicherweise aufgefordert, den Umfang einzugrenzen. Wenn Sie den Kontext mit Cloud SQL Studio hochladen möchten, folgen Sie der Anleitung, nachdem der Agent die JSON-Datei generiert hat.

Kontexteffektivität bewerten

Nachdem Sie einen Kontextsatz und ein Golden Dataset erstellt haben, können Sie den Agenten die Kontextleistung messen lassen, indem Sie die QueryData API Ihres Daten-KI-Agenten mit jeder Golden Question abfragen. Der Agent vergleicht das generierte SQL und die Ausführungsergebnisse mit der erwarteten Antwort. Der Vergleich wird mit Evalbench durchgeführt.

Wenn Sie eine Bewertung durchführen, erhalten Sie Folgendes:

  • Quantitative Messwerte wie Ergebnisse für bestanden und nicht bestanden sowie Gesamtergebnisse, um den Fortschritt bei Kontextiterationen zu verfolgen.
  • Eine Inline-Zusammenfassung der Unterhaltung und detaillierte CSV-Berichte, die in das Verzeichnis eval_reports/ in Ihrem Testordner geschrieben werden.

Geben Sie zum Starten einer Bewertung den Pfad zum Golden-Dataset und die ID des Kontextsets an. Informationen zum Suchen der Kontext-Set-ID finden Sie unter Kontext-ID des Agenten finden.

Sie können die folgenden Beispiel-Prompts verwenden, um den Agenten anzuweisen:

  • „Bewerte meinen Kontext im Vergleich zu golden.json.“
  • „Führe die Auswertung mit der Konfiguration aus meinem letzten Test noch einmal durch.“

Wenn Sie eine zuvor generierte Evaluierungskonfiguration noch einmal ausführen möchten, ohne sie noch einmal einzurichten, fragen Sie den Agent oder rufen Sie die CLI direkt auf:

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

Details zum Schema für die Evaluierungskonfiguration und zum Anpassen von Evaluierungsläufen finden Sie in der Evalbench-Dokumentation.

Lückenanalyse durchführen und Verbesserungen vorschlagen

Um Fehler bei Abfragen zu beheben, müssen Sie die Ursachen ermitteln, z. B. falsche Spalten, fehlende Tabellenverknüpfungen oder nicht aufgelöste ungenaue Begriffe. Die manuelle Ermittlung dieser Probleme erfordert eine umfassende Analyse von Bewertungsberichten.

Der Agent automatisiert diese Analyse- und Korrekturschleife:

  • Lückenanalyse: Der Agent liest die Auswertungsergebnisse und Ihren Kontext, um ähnliche Fehler zu gruppieren und gezielte Kontextanpassungen zu empfehlen, z. B. Vorlagen, Facetten oder Wertesuchen.
  • Vorgeschlagene Korrekturen: Der Agent schlägt konkrete Änderungen vor und testet die SQL-Anweisungen optional anhand Ihrer Datenbank, um die Lösung zu überprüfen.
  • Beibehaltung der Baseline: Der KI-Agent schreibt die Verbesserungen in eine neue JSON-Datei neben Ihrem Baseline-Kontext, sodass die Originaldateien erhalten bleiben.

Sie können die folgenden Beispiel-Prompts verwenden, um den Agenten anzuweisen:

  • „Führe eine Lückenanalyse meiner letzten Bewertung durch und schlage Korrekturen vor.“
  • „Optimiere diesen Kontextsatz für golden.json.“

Um sich auf die nächste Iteration vorzubereiten, laden Sie den verbesserten Kontext mit Data Agents Studio in die Zielkontextgruppe hoch. Folgen Sie dazu der Anleitung.

Kontextbezogene Elemente auf Anfrage erstellen

Wenn Sie den erforderlichen Kontext bereits kennen, z. B. eine Vorlage für eine bestimmte Frage, eine Facette für einen wiederholten Filter oder eine Wertsuche für eine bestimmte Spalte, kann das manuelle Schreiben des Kontext-JSON zu Serialisierungsfehlern in Parameternamen, Typmetadaten oder der Fragmentsyntax führen. Der Agent übernimmt die JSON-Formatierung, damit Sie sich auf Ihre geschäftliche Absicht konzentrieren können.

Sie können diese Funktion auch für Ad-hoc-Updates verwenden, z. B. wenn Sie ein neues Abfragemuster unterstützen oder ein fehlendes Schemadetail beheben müssen. Um den JSON-Code zu erhalten, beschreiben Sie den erforderlichen Kontext für den Agent, ohne eine Bewertung auszuführen oder einen Test einzurichten.

Diese Funktion ist auch die richtige Wahl, wenn Sie eine einmalige Aufgabe erhalten: Ein Stakeholder gibt Ihnen ein neues Frage-SQL-Paar, das unterstützt werden soll, oder Sie stellen bei einer Codeüberprüfung eine fehlende Facette fest. Sie müssen kein Experiment einrichten oder eine Bewertung durchführen, um das Problem zu beheben. Beschreiben Sie einfach, was Sie möchten, und der KI-Agent generiert das JSON.

Sie können die folgenden Beispiel-Prompts verwenden, um den Agenten anzuweisen:

  • „Erstelle eine Vorlage für: ‚Welche Flughäfen gibt es in Kalifornien?‘ mit SQL: SELECT name FROM airports WHERE country = 'United States' AND state = 'CA'.“
  • „Erstelle eine Facette für den Filter departure_time BETWEEN '00:00:00' AND '06:00:00' mit dem Label ‚Rote Augen‘.“
  • „Erstelle eine Wertsuche für airports.iata.“

Überlegungen zur Auswahl des Kontexttyps

Wenn Sie den richtigen Kontexttyp auswählen, unabhängig davon, ob es sich um eine Vorlagen-, Facetten- oder Wertsuche handelt, können Sie Kontext-Bloat und Regressionen bei Datenbankabfragen vermeiden. Wenn Sie beispielsweise eine Vorlage anstelle eines Facets verwenden, kann das zu doppelten Regeln führen. Wenn Sie Wertesuchen einführen, wo eine Vorlage ausreicht, kann das die Abfragelatenz erhöhen. Um das richtige Schemaformat zu finden, bitten Sie den Agent, einen Typ basierend auf der Abfragestruktur oder den Datenbankspalten zu empfehlen, bevor Sie Kontext-Elemente erstellen. Der Agent erläutert seine Überlegungen, damit Sie die Kontextoptionen besser nachvollziehen können.

Sie können die folgenden Beispiel-Prompts verwenden, um den Agenten anzuweisen:

  • „Ich schreibe den Filter departure_time BETWEEN '00:00:00' AND '06:00:00' immer wieder in viele Abfragen. Wie kann ich das am besten erfassen?
  • „Nutzer beschreiben den Flugstatus in Freitext und ich möchte sie mit flights.status abgleichen. Welche Art von Wertsuche sollte ich einrichten?“
  • Was ist der Unterschied zwischen einer Vorlage und einer Facette und wann sollte ich welche verwenden?

Bulk-Vorgänge auf eine Kontextgruppe anwenden

Der Agent unterstützt Bulk-Updates, um große Kontextmengen konsistent zu verwalten. Wenn Sie mehrere Kontext-Elemente gleichzeitig aktualisieren müssen, z. B. wenn eine Datenbankspalte umbenannt wird, sich das Format eines Code-Werts ändert oder Vorlagen auf eine eingestellte Tabelle verweisen, kann der Agent die Änderung auf alle betroffenen Elemente anwenden, ohne dass sich dies auf nicht verwandte Einträge auswirkt.

Sie können die folgenden Beispiel-Prompts verwenden, um den Agenten anzuweisen:

  • „Lies golden.txt und wandle alle Paare in Vorlagen um.“
  • Ersetzen Sie in context_set.json für alle Elemente, die auf „United“ verweisen, airline = 'UA' durch airline = 'United Airlines'. Lassen Sie nicht verwandte Elemente in Ruhe.“

Nächste Schritte