Kontextsets mit dem Kontext-Engineering-Agent erstellen

In diesem Dokument wird beschrieben, wie Sie Kontextsets erstellen und optimieren, um eine hohe QueryData-Abfragegenauigkeit für Ihre Daten-Agent-Anwendungen zu erzielen. Der Context Engineering-Agent hilft Ihnen, Kontext-Sets zu erstellen, zu bewerten und zu verbessern, indem er deren Erstellung und Optimierung automatisiert.

Weitere Informationen zu Kontextsets und QueryData finden Sie unter Kontextsets – Übersicht und QueryData – Übersicht.

Für die Erstellung von Datenanwendungen auf Unternehmensniveau muss die Genauigkeit des Text-zu-Abfrage-Modells in der Regel eine Qualität von nahezu 100 % erreichen. Falsch generiertes SQL beeinträchtigt die allgemeine Nutzerfreundlichkeit und Nutzererfahrung der Anwendung. 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 erreichen.

Wenn Sie QueryData den auf Ihre Geschäftsanwendung zugeschnittenen Kontext zur Verfügung stellen, liefern Sie die genauen Geschäftsregeln, die das System benötigt, um nuancierte Nutzerabsichten zu erkennen.

Context Engineering Agent

Der Context-Engineering-Agent automatisiert diesen Optimierungs-Workflow. Sie können mit dem KI-Agenten kommunizieren, um Ad-hoc-Aufgaben zu erledigen und Ihren Kontext zu optimieren. Die folgende Liste enthält Beispiele für Prompts in natürlicher Sprache, mit denen Sie den KI-Agenten anweisen können, sowie eine Beschreibung der Antwort des KI-Agenten. Anhand dieser Beispiele können Sie Ihren Kontext erstellen und optimieren:

  • Beispiel-Prompt für die Fehleranalyse: „Aktualisiere den Kontext, damit wir den Flughafen für Abfragen wie ‚Flüge nach Disney World‘ korrekt identifizieren.“ Der Agent analysiert den Fehler, begründet die Lücke und empfiehlt, ein geeignetes Kontextelement hinzuzufügen, z. B. eine Suchanfrage nach Werten.
  • Beispielprompt für kontextbezogene Vorschläge: „Lies meinen App-Code und schlage Kontext vor, den ich hinzufügen kann.“ Der KI-Agent analysiert den Code, zieht Schlussfolgerungen zur Domain Ihrer Anwendung und schlägt relevante Kontextelemente vor.
  • Beispiel-Prompt für die Bulk-Verarbeitung: „Hier sind 10 Beispiele für Fragen und SQL-Abfragen. und sie in Vorlagen umwandeln.“ Der KI-Agent verarbeitet Ihre Eingaben im Bulk und aktualisiert Ihren Kontextsatz.

Bedeutung des Golden Dataset

Zur Optimierung des Kontexts müssen Sie ein Dataset erstellen, das den Eingaben in natürlicher Sprache Ihrer Anwendung entspricht. Der KI-Agent kann Ihnen helfen, diesen Golden Dataset zu erstellen, der aus Nutzerfragen und den erwarteten Datenbankabfragen besteht. Mit einem Golden Dataset können Sie:

  • Legen Sie eine Baseline für die Abfrageleistung fest.
  • Aktualisierungen anhand von Datenbankabfragen mit Grundwahrheiten validieren.
  • Verbesserungen der Accuracy über Iterationen hinweg messen.

Der systematische Hill-Climbing-Prozess

Beim systematischen Hill-Climbing verbessert der Agent iterativ einen Kontextsatz, indem er das Golden Dataset bewertet, eine Lückenanalyse durchführt und Aktualisierungen vornimmt, um die Genauigkeit auf nahezu 100 % zu steigern.

  • Referenzkontext automatisch generieren: Erstellen Sie einen Startkontext, der von Ihrem Datenbankschema und Ihren Anwendungsartefakten abgeleitet ist.
  • Workflow zur Optimierung durch Bergsteigen: Lassen Sie den Agenten die Genauigkeit Ihrer QueryData bewerten, eine Lückenanalyse bei Fehlern durchführen und automatisch Verbesserungen vorschlagen, um die Genauigkeit zu erhöhen.

Das folgende Diagramm zeigt den systematischen Hill-Climbing-Workflow:

Workflow für den iterativen Aufbau von Kontext.

Hinweis

Bevor Sie den Kontext-Engineering-Agenten verwenden, müssen die folgenden Voraussetzungen erfüllt sein.

Erforderliche Dienste aktivieren

Aktivieren Sie die folgenden Dienste für Ihr Projekt:

AlloyDB for PostgreSQL-Cluster, -Instanz und -Datenbank vorbereiten

Prüfen Sie, ob Sie Zugriff auf einen vorhandenen AlloyDB-Cluster und eine vorhandene AlloyDB-Instanz haben, oder erstellen Sie einen neuen Cluster und eine neue Instanz.
Für diese Anleitung benötigen Sie eine Datenbank in Ihrer AlloyDB-Instanz. Weitere Informationen finden Sie unter Datenbank erstellen.

Erforderliche Rollen und Berechtigungen

  • Fügen Sie dem Cluster auf Datenbankebene einen IAM-Nutzer (Identity and Access Management) oder ein Dienstkonto hinzu. Weitere Informationen finden Sie unter Datenbanknutzer verwalten.
  • Weisen Sie dem IAM-Nutzer auf Projektebene die Rollen alloydb.databaseUser, serviceusage.serviceUsageConsumer und geminidataanalytics.queryDataUser zu. Weitere Informationen finden Sie unter IAM-Richtlinienbindung für ein Projekt hinzufügen.
  • Wenn Sie Kontextgruppen erstellen, hochladen und verwalten möchten, weisen Sie dem IAM-Nutzer auf Projektebene die Rolle „Dataplex Catalog Editor“ (roles/dataplex.catalogEditor) oder „Dataplex Catalog Admin“ (roles/dataplex.catalogAdmin) zu. Weitere Informationen finden Sie unter Berechtigungen für Kontextgruppen.

Berechtigung executesql für AlloyDB for PostgreSQL-Instanz gewähren

Verwenden Sie den folgenden curl-Befehl, um der AlloyDB for PostgreSQL-Instanz die Berechtigung executesql zu gewähren und die Instanzeinstellung data_api_access auf den Wert ALLOW_DATA_API festzulegen: 
   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json" \
     https://alloydb.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID/instances/INSTANCE_ID?updateMask=dataApiAccess \
     -d '{
       "dataApiAccess": "ENABLED",
     }'
Ersetzen Sie Folgendes:
  • PROJECT_ID: Die ID Ihres Google Cloud -Projekts.
  • LOCATION: Die Region, in der sich Ihr AlloyDB-Cluster befindet.
  • CLUSTER_ID: Die ID Ihres AlloyDB-Clusters.
  • INSTANCE_ID: Die ID Ihrer AlloyDB-Instanz.
Melden Sie sich zum Ausführen der Schritte in dieser Anleitung bei Google Cloud an und authentifizieren Sie sich dann mit der IAM-Authentifizierung bei der Datenbank.

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 erforderlich ist, um die zugrunde liegenden Python-Pakete zu verwalten.

  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 Agenten-Framework, z. B. der Antigravity CLI, Claude Code oder der Gemini CLI, um Ihre Umgebung vorzubereiten.

Führen Sie je nach ausgewähltem Agenten-Framework die entsprechenden Installationsschritte aus:

Antigravity CLI

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

  1. Installieren Sie die Antigravity CLI. Weitere Informationen finden Sie unter Erste Schritte mit der Antigravity-Befehlszeile.
  2. Installieren Sie das Kontext-Engineering-Agent-Plug-in, das Workflows für die Kontextgenerierung enthält. Ersetzen Sie VERSION durch die erforderliche Release-Version: 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION
  3. Starten Sie die Antigravity CLI: 
    agy

Führen Sie den folgenden Befehl aus, um das Plug-in auf die aktuelle Version zu aktualisieren. Ersetzen Sie VERSION durch die erforderliche Release-Version:

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

Claude Code

So installieren Sie den Context Engineering-Agenten 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. 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. Aktualisieren Sie die Erweiterung: 
    gemini extensions update google-cloud-db-context-engineering

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 KI-Agent mit Ihrer Datenbank interagieren kann, müssen Sie Authentifizierungsdaten konfigurieren und die Konfiguration der 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-Agenten 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 den folgenden Befehl aus, um sich zu authentifizieren:

gcloud auth application-default login

Datenbankverbindungsdatei konfigurieren

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

In der Konfigurationsdatei werden die Datenbankquelle und die Tools angegeben, die zum Abrufen von Schemas oder zum Ausführen von SQL erforderlich sind. Der Context-Engineering-Agent verfügt über vorinstallierte Agent Skills, die Sie beim Erstellen der Konfiguration unterstützen.

  1. Starten Sie die KI-Agentenumgebung.

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

  3. Laden Sie die Verbindung neu, um die neue tools.yaml-Konfiguration anzuwenden:

    • Führen Sie in der Antigravity CLI /mcp aus und wählen Sie toolbox aus, um den Neustart durchzuführen.
    • Führen Sie in der Gemini CLI /mcp reload aus.
    • Führen Sie in Claude Code /mcp aus, wählen Sie toolbox und dann Reconnect 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, mit denen Sie die Context Engineering-Funktionen Ihres Coding-Agenten verbessern können. Sie können diese Tools zusammen verwenden, um eine Baseline zu generieren, die Effektivität zu messen und Verbesserungen iterativ anzuwenden. Sie können jedoch in jeder Phase des Workflows beginnen:

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

Jede Funktion beschreibt die Aktionen, Anwendungsfälle und Aufrufbefehle des KI-Agenten.

Die Beispiel-Prompts zeigen, wie Sie den Agenten in natürlicher Sprache abfragen können. Wenn der Agent zusätzliche Details benötigt, um eine Anfrage abzuschließen, werden Sie um Klärung gebeten.

Bewertungs-Datasets erstellen und erweitern

Wenn Sie die Leistung verbessern möchten, müssen Sie sie zuerst messen. Ohne ein Golden Dataset, das aus Nutzerfragen und den erwarteten SQL-Abfragen besteht, fehlt dem Kontext-Engineering eine systematische Überprüfung. Mit einem Golden Dataset ist jede Änderung eine messbare Verbesserung, die Sie anhand der Grundwahrheit validieren können.

Das manuelle Erstellen eines repräsentativen Golden Dataset ist zeitaufwendig und kleine Datasets können Variationen in den Formulierungen der Nutzer vermissen lassen. Der KI-Agent löst das Problem so:

  • Kandidaten für Frage-SQL-Paare werden basierend auf Ihrem Datenbankschema generiert.
  • Erweitern eines kleinen Seed-Datasets mithilfe von Filtervarianten, Synonymen und Umformulierungen.

Optional können Sie den KI-Agenten die generierte SQL-Abfrage 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:

json [ { "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, wo sie für die Bewertung bereit sind. Sie können eine vorhandene Datei bereitstellen oder einige Bewertungsbeispiele inline schreiben, die der Agent erweitern kann.

Sie können den Agenten mit den folgenden Beispiel-Prompts anweisen:

  • „Erstelle ein Bewertungs-Dataset aus meinem Schema.“
  • "Hier ist eine Ausgangsfrage und SQL. Erweitere es zu einem größeren Dataset und überprüfe, ob die Abfragen ausgeführt werden.“

Basis-Kontextset generieren

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

Sie können den Agenten mit den folgenden Beispiel-Prompts anweisen:

  • „Erstelle ein Kontextset aus meinem Schema.“
  • „Generiere den ersten Kontext mit diesen Schemas und den Geschäftsregeln in requirements.md.“

Der KI-Agent fordert Sie auf, das Experiment zu benennen, um die generierten Artefakte zu organisieren. Wenn Ihr Datenbankschema groß ist, werden Sie möglicherweise aufgefordert, den Umfang einzugrenzen. Wenn Sie den Kontext mit AlloyDB 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 KI-Agenten die Kontextleistung messen lassen, indem Sie die QueryData API Ihres KI-Datenagenten mit jeder Golden Question abfragen. Der Agent vergleicht das generierte SQL und die Ausführungsergebnisse mit der erwarteten Antwort. Dabei wird Evalbench für den Vergleich verwendet.

Eine Bewertung bietet Folgendes:

  • Quantitative Messwerte wie Ergebnisse zu bestandenen und nicht bestandenen Tests sowie aggregierte Punktzahlen, um den Fortschritt über Kontextiterationen hinweg zu verfolgen.
  • Eine Inline-Zusammenfassung der Unterhaltung und detaillierte CSV-Berichte, die im Verzeichnis eval_reports/ in Ihrem Testordner gespeichert werden.

Geben Sie den Pfad zum Golden Dataset und die Kontext-Set-ID an, um eine Bewertung zu starten. Informationen zum Ermitteln der Kontext-ID finden Sie unter Kontext-ID des KI-Agenten ermitteln.

Sie können den Agenten mit den folgenden Beispiel-Prompts anweisen:

  • „Evaluate my context against golden.json.“
  • „Führe die Bewertung noch einmal mit der Konfiguration aus meinem letzten Test aus.“

Wenn Sie eine zuvor generierte Bewertungskonfiguration noch einmal ausführen möchten, ohne sie neu einzurichten, fragen Sie den Agenten oder rufen Sie die Befehlszeile direkt auf:

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

Weitere Informationen zum Schema der Bewertungskonfiguration und zum Anpassen von Bewertungsausführungen finden Sie in der Evalbench-Dokumentation.

Lückenanalyse durchführen und Verbesserungen vorschlagen

Um Abfragefehler zu beheben, müssen Sie die Ursachen ermitteln, z. B. falsche Spalten, fehlende Tabellenverknüpfungen oder nicht aufgelöste unscharfe Begriffe. Die manuelle Identifizierung dieser Probleme erfordert eine umfassende Analyse der Bewertungsberichte.

Der KI-Agent automatisiert diese Analyse- und Korrekturschleife:

  • Lückenanalyse: Der Agent liest die Bewertungsergebnisse und Ihren Kontext, um ähnliche Fehler zu gruppieren und gezielte Kontextergänzungen wie Vorlagen, Facetten oder Wertesuchen zu empfehlen.
  • Vorgeschlagene Korrekturen: Der Agent schlägt konkrete Änderungen vor und testet die SQL-Abfrage optional mit Ihrer Datenbank, um die Lösung zu überprüfen.
  • Baseline-Erhaltung: Der Agent schreibt die Verbesserungen in eine neue JSON-Datei neben Ihrem Baseline-Kontext und behält die Originaldateien bei.

Sie können den Agenten mit den folgenden Beispiel-Prompts anweisen:

  • „Führe eine Lückenanalyse für meine letzte Bewertung durch und schlage Korrekturen vor.“
  • „Optimiere dieses Kontextset für golden.json.“

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

Kontextbezogene Elemente bei Bedarf 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 Fragmentsyntax führen. Der KI-Agent übernimmt die JSON-Formatierung, damit Sie sich auf Ihre Geschäftsabsicht 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 die JSON-Datei zu erhalten, beschreiben Sie dem Agenten den erforderlichen Kontext, ohne eine Bewertung auszuführen oder ein Experiment 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 entdecken bei einer Codeüberprüfung eine fehlende Facette. Sie müssen kein Experiment einrichten oder eine Bewertung ausführen, um das Problem zu beheben. Beschreiben Sie einfach, was Sie möchten, und der KI-Agent erstellt die JSON-Datei.

Sie können den Agenten mit den folgenden Beispiel-Prompts anweisen:

  • „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.“

Über die Auswahl des Kontexttyps nachdenken

Wenn Sie den richtigen Kontexttyp auswählen, unabhängig davon, ob es sich um eine Vorlagen-, Facetten- oder Wertsuche handelt, können Sie Kontextüberlastung und Regressionen bei Datenbankabfragen vermeiden. Wenn Sie beispielsweise eine Vorlage anstelle einer Facette verwenden, kann dies zu doppelten Regeln führen. Wenn Sie Wertesuchen einführen, wo eine Vorlage ausreicht, kann sich die Abfragelatenz erhöhen. Um das richtige Schemaformat zu finden, fordern Sie den KI-Agenten auf, einen Typ basierend auf der Abfragestruktur oder den Datenbankspalten zu empfehlen, bevor Sie Kontextelemente erstellen. Der Agent erklärt seine Schlussfolgerungen, damit Sie die Kontextoptionen besser verstehen.

Sie können den Agenten mit den folgenden Beispiel-Prompts anweisen:

  • „Ich verwende den Filter departure_time BETWEEN '00:00:00' AND '06:00:00' in vielen Abfragen. Wie kann ich das am besten festhalten?
  • „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 was verwenden?“

Bulk-Vorgänge auf ein Kontextset anwenden

Der KI-Agent unterstützt Bulk-Updates, um große Kontextmengen konsistent zu verwalten. Wenn Sie mehrere Kontextelemente gleichzeitig aktualisieren müssen, z. B. wenn eine Datenbankspalte umbenannt wird, sich das Format eines Codewerts ändert oder Vorlagen auf eine verworfene Tabelle verweisen, kann der Agent die Änderung auf alle betroffenen Elemente anwenden, ohne nicht zugehörige Einträge zu ändern.

Sie können den Agenten mit den folgenden Beispiel-Prompts anweisen:

  • „Lies golden.txt und wandle alle Paare in Vorlagen um.“
  • „Ersetzen Sie in context_set.json den Wert airline = 'UA' durch airline = 'United Airlines' für alle Elemente, die sich auf ‚United‘ beziehen. Lassen Sie nicht zusammenhängende Elemente in Ruhe.“

Nächste Schritte