Kontextsets mit dem Context-Engineering-Agenten erstellen und optimieren

Wenn Sie in Ihren Daten-Agent-Anwendungen eine hohe Genauigkeit der QueryData-Abfragen und eine niedrige Online-Latenz erreichen möchten, können Sie den Context-Engineering-Agenten verwenden, um Kontextsets zu erstellen, zu bewerten und zu optimieren. Durch die Automatisierung der Kontexterstellung, des Uploads und der Optimierung hilft der Agent Ihren Anwendungen, schnelle, deterministische und erklärbare Antworten auf Fragen in natürlicher Sprache zu liefern.

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

Wenn Sie QueryData mit Kontext versorgen, der auf Ihre Geschäftsanwendung zugeschnitten ist, liefern Sie die genauen Geschäftsregeln, die das System benötigt, um nuancierte Nutzerabsichten zu erkennen und eine Abfragequalität von nahezu 100 % zu erreichen. Während Sie in Ihrer Befehlszeile oder IDE arbeiten, lädt der Kontext-Engineering-Agent Ihre Kontext-Sets automatisch in Google Cloud hoch und speichert lokale Dateien in Ihrem Arbeitsbereich für die Versionsverwaltung.

Context Engineering Agent

Der Context Engineering-Agent fungiert als Designzeit-Assistent direkt in Ihrer Befehlszeile oder IDE. Die manuelle Kontexterstellung erfordert das manuelle Schreiben detaillierter Abfragemuster, das Antizipieren jeder Formulierungsvariante und die manuelle Diagnose von Abfragefehlern über Iterationen hinweg. Der Context Engineering-Agent eliminiert diesen Aufwand, indem er einen Baseline-Kontext erstellt, Ground-Truth-Bewertungs-Datasets kuratiert, iterativ die Genauigkeit verbessert und nachweist, dass Ihr Kontext auf neue Fragen verallgemeinert werden kann.

Sie unterhalten sich mit dem KI-Agenten in natürlicher Sprache, um den Optimierungsworkflow zu steuern. Beginnen Sie mit einem Prompt wie „Optimiere das Kontextset für meine Anwendungsanforderungen.“

Hinweis

Bevor Sie den Context Engineering-Agenten verwenden, müssen Sie die Voraussetzungen in den folgenden Abschnitten erfüllen. Sie können Kontextgruppen in den Regionen us-central1, us-east1, europe-west4 und asia-southeast1 erstellen und speichern, auch wenn sich Ihre Datenbankinstanz in einer anderen Region befindet.

Erforderliche Dienste aktivieren

Aktivieren Sie die folgenden Dienste für Ihr Projekt:

Datenbank vorbereiten

Bereiten Sie Ihre AlloyDB for PostgreSQL-Instanz vor und konfigurieren Sie den Zugriff für den Agenten:

  • Erstellen Sie einen AlloyDB-Cluster und eine AlloyDB-Instanz und erstellen Sie eine Datenbank oder verwenden Sie eine vorhandene Instanz und Datenbank.
  • Aktivieren Sie den Data API-Zugriff auf Ihre AlloyDB-Instanz. Wenn Sie eine private IP-Adresse verwenden, setzen Sie das Feld für den Data API-Zugriff (dataApiAccess) auf Ihrer primären Instanz auf ENABLED, damit der Agent Schemas prüfen und Abfragen validieren kann. Informationen zu Instanzen, die ohne aktivierten Data API-Zugriff erstellt wurden, finden Sie unter Data API-Zugriff aktivieren oder konfigurieren Sie ihn in der Google Cloud Console.

Erforderliche Rollen und Berechtigungen

Damit Sie die Berechtigungen erhalten, die Sie für die Verwendung des Context Engineering-Agents und die Verwaltung von Kontextsets benötigen, konfigurieren Sie die folgenden IAM-Rollen (Identity and Access Management) und Datenbankberechtigungen:

  • Fügen Sie dem Cluster einen IAM-Nutzer oder ein Dienstkonto hinzu. Weitere Informationen finden Sie unter IAM-Authentifizierung verwalten.
  • Weisen Sie dem IAM-Nutzer oder -Dienstkonto auf Projektebene die Rollen roles/alloydb.databaseUser, roles/serviceusage.serviceUsageConsumer, roles/geminidataanalytics.queryDataUser und roles/mcp.toolUser zu. Weitere Informationen finden Sie unter IAM-Richtlinienbindung für ein Projekt hinzufügen.
  • Wenn Sie Kontextsets erstellen, hochladen und verwalten möchten, weisen Sie dem IAM-Nutzer oder -Dienstkonto 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.
  • Wenn Sie semantische Wertesuchen (google_ml.embedding) verwenden, aktivieren Sie die Vertex AI API und weisen Sie dem Dienstkonto des AlloyDB-Clusters die Rolle roles/aiplatform.user zu.

  • Gewähren Sie dem IAM-Nutzer oder -Dienstkonto Lesezugriff auf die Datenbankberechtigungen, indem Sie sich als Nutzer mit Superuser-Berechtigungen anmelden, z. B. als postgres-Nutzer:

    GRANT SELECT ON ALL TABLES IN SCHEMA public TO "USER_NAME";

    Ersetzen Sie USER_NAME durch die E-Mail-Adresse des Nutzers. Lassen Sie bei einem Dienstkonto das Suffix . weg. Wenn sich Ihre Tabellen in einem anderen benutzerdefinierten Schema als public befinden, führen Sie auch GRANT USAGE ON SCHEMA SCHEMA_NAME TO "USER_NAME"; und GRANT SELECT ON ALL TABLES IN SCHEMA SCHEMA_NAME TO "USER_NAME"; aus. Weitere Informationen finden Sie unter IAM-Nutzern Datenbankberechtigungen erteilen.

Umgebung vorbereiten

Sie können Kontextgruppen in Ihrer lokalen Entwicklungsumgebung oder IDE erstellen und optimieren.

uv installieren

Der Context-Engineering-Agent benötigt uv, 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

Context Engineering-Agent installieren

Installieren Sie das Context Engineering Agent-Plug-in in Ihrer bevorzugten Entwicklungsumgebung:

Antigravity CLI

  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: 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin
  3. Starten Sie die Antigravity CLI: 
    agy

Wenn Sie das Plug-in später aktualisieren möchten, führen Sie agy plugin uninstall db-context-engineering und dann agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin aus.

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

Wenn Sie das Plug-in später aktualisieren möchten, führen Sie /plugin update db-context-engineering@db-context-enrichment-marketplace aus.

Gemini CLI (eingestellt)

  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

Wenn Sie die Erweiterung später aktualisieren möchten, führen Sie gemini extensions update google-cloud-db-context-engineering aus.

Mit Google Cloudauthentifizieren

  1. Konfigurieren Sie Standardanmeldedaten für Anwendungen (ADC), um Ihre Entwicklungsumgebung zu authentifizieren:

    gcloud auth application-default login

  2. Legen Sie das Kontingentprojekt für Ihre Anmeldedaten fest, damit die MCP-Tools (Model Context Protocol) Ihr Google Cloud -Projekt verwenden können:

    gcloud auth application-default set-quota-project PROJECT_ID

    Ersetzen Sie dabei PROJECT_ID durch die ID Ihres Projekts in Google Cloud .

Verbindung zur Datenbank herstellen

  1. Starten Sie Ihre KI-Agenten-Umgebung und bitten Sie den KI-Agenten, die Datenbankverbindung herzustellen (z. B. „Hilf mir, die Datenbankverbindung einzurichten“). Der Agent führt Sie durch die Erstellung der Konfigurationsdatei .context-engineering/tools.yaml, damit er Schemas lesen und SQL validieren kann. (Bevor .context-engineering/tools.yaml erstellt wird, wird beim Start eine erste MCP-Serververbindungswarnung für toolbox erwartet.)

  2. Laden Sie die MCP-Serververbindung neu, um die .context-engineering/tools.yaml-Konfiguration anzuwenden:

    • Antigravity CLI: Führen Sie /mcp aus und wählen Sie toolbox (oder db-context-engineering_toolbox) aus, um den Neustart durchzuführen.
    • Claude Code: Führen Sie /mcp aus, wählen Sie toolbox und dann Reconnect aus.
    • Gemini CLI: Führen Sie /mcp refresh (oder /mcp reload) aus.

Kontext erstellen und optimieren

Der Context Engineering Agent führt Ihren Kontextsatz durch einen End-to-End-Lebenszyklus, vom ersten Bootstrapping bis zur verifizierten Generalisierbarkeit.

Baseline-Kontextset bootstrappen

Damit der Kontext nicht von Grund auf neu erstellt werden muss, prüft der KI-Agent Ihr Datenbankschema sowie alle verfügbaren Anwendungsartefakte wie Geschäftsanforderungen, Dokumentation oder SQL-Beispielabfragen. Der KI-Agent leitet einen ersten Baseline-Kontextsatz ab, der grundlegende Abfragevorlagen und Abfragefacetten enthält, die auf Ihrem Datenbankmodell basieren.

Nachdem der Agent den Baseline-Kontext generiert und validiert hat, lädt er ihn direkt in Google Cloud hoch und gibt den Ressourcennamen des Kontextsets zurück.

Bewertungs- und Holdout-Datasets aus Anwendungsartefakten erstellen

Wenn Sie die Accuracy systematisch verbessern möchten, benötigen Sie Grundwahrheitsfragen, die mit verifizierten SQL-Abfragen verknüpft sind. Wenn Sie noch keinen Bewertungs-Benchmark haben, kann der Agent einen generieren, indem er Geschäftsszenarien aus Ihrem Anwendungscode, Ihren bisherigen Abfragen und Ihrem Datenbankschema extrahiert.

Während der Dataset-Generierung erstellt der Agent zwei verschiedene Sets:

  • Trainings-Benchmark: Eine Sammlung repräsentativer Frage-SQL-Paare, die während der iterativen Optimierung verwendet werden.
  • Zurückgehaltenes Dataset: Ein separater Satz von Fragen, die dem Trainings-Benchmark ähneln und für Tests zur Verallgemeinerbarkeit reserviert sind.

Accuracy mit Hill-Climbing optimieren

Bei der Hill-Climbing-Optimierung verfeinert der Agent Ihren Kontextsatz iterativ, um die Accuracy von QueryData auf nahezu 100 % zu steigern:

  • Bewerten: Der Agent testet Ihr aktuelles Kontextset anhand des Trainings-Benchmarks mithilfe der QueryData API und bewertet die Genauigkeit.
  • Lücken diagnostizieren: Der KI-Agent analysiert Abfragefehler, identifiziert deren Ursachen (z. B. fehlende Tabellenverknüpfungen, nicht verknüpfte private Entitäten oder komplexe Filterbedingungen) und formuliert gezielte Korrekturen.
  • Verfeinern und hochladen: Der Agent fügt Abfragevorlagen, Abfragefacetten und Wertesuchen hinzu oder verbessert sie, um die Lücken zu schließen, und lädt den aktualisierten Kontextsatz automatisch über Ihre Befehlszeile in Google Cloud hoch.
  • Iterieren: Der Agent wiederholt diesen Zyklus über mehrere Runden, bis die Genauigkeit den optimalen Wert erreicht.

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

Workflow für den iterativen Aufbau von Kontext.

Generalisierbarkeit mit dem zurückgehaltenen Dataset beweisen

Eine hohe Genauigkeit bei einem Trainings-Benchmark ist notwendig, aber der Produktionstraffic umfasst Formulierungen und komplexe zusammengesetzte Fragen, die während der Entwicklung nie aufgetreten sind.

Nachdem die Hill-Climbing-Optimierung konvergiert ist, testet der Agent den resultierenden Kontextsatz mit dem zurückgehaltenen Dataset. In diesem Schritt wird überprüft, ob der Kontextsatz sauber auf neue Nutzereingaben verallgemeinert werden kann, ohne dass es zu einer Überanpassung an den ursprünglichen Benchmark kommt. Der Agent erstellt einen Bericht zur Generalisierbarkeit, der die Genauigkeit bei unbekannten Fragenvarianten und zusammengesetzten Filtern zeigt (z. B. „Finde Häuser in der Nähe guter Schulen in Del Mar für eine junge Familie mit Meerblick“).

On-Demand-Erstellung und -Schlussfolgerung

Zusätzlich zu vollständigen Optimierungsläufen können Sie mit dem Agenten kommunizieren, um gezielte Aktualisierungen vorzunehmen, wenn sich die Geschäftsanforderungen ändern:

  • Zielgerichtetes Erstellen: Beschreiben Sie eine bestimmte Geschäftsanforderung in natürlicher Sprache. Der KI-Agent formatiert das Kontextelement und lädt es direkt über Ihre Befehlszeile hoch, ohne dass eine manuelle Bearbeitung erforderlich ist:

    • „Erstelle eine Vorlage für: ‚Finde Häuser in der Nähe von guten Schulen in Del Mar‘ mit SQL: SELECT p.property_id, p.address FROM properties AS p JOIN schools AS s ON p.school_id = s.school_id WHERE p.city = 'Del Mar' AND s.rating >= 7.“
    • „Erstelle eine Facette für den Filter properties.bedrooms BETWEEN 3 AND 4 AND properties.square_feet BETWEEN 1500 AND 2500 mit dem Label ‚für eine junge Familie‘.“
    • „Erstelle eine Wertsuche für properties.city.“

  • Bulk-Updates für einen Kontextsatz: Wenn Datenbankspalten umbenannt oder Tabellenstrukturen geändert werden, kann der Agent alle betroffenen Kontextelemente gleichzeitig aktualisieren, ohne nicht zugehörige Einträge zu ändern:

    • „Ersetze in meinem Kontextset properties.property_type = 'SFR' durch properties.property_type = 'Single Family Residential' für alle Elemente, die sich auf Einfamilienhäuser beziehen. Lassen Sie nicht zusammenhängende Elemente in Ruhe.“

Nächste Schritte