Data Engineering Agent API: Datenpipelines mit einem Agenten erstellen

Sie können die Data Engineering Agent API, auf die über geminidataanalytics.googleapis.com zugegriffen wird, verwenden, um Datenpipelines zum Laden und Verarbeiten von Daten in BigQuery zu erstellen, zu ändern und zu verwalten. Die API verwendet das A2A-Protokoll, mit dem Sie Datenpipelines für Ihre Data-Engineering-Anforderungen mithilfe von Prompts in natürlicher Sprache generieren und bearbeiten können.

Weitere Informationen zum Data-Engineering-Agenten finden Sie unter Data-Engineering-Agenten zum Erstellen und Ändern von Datenpipelines verwenden.

Weitere Informationen dazu, wie und wann Gemini for Google Cloud Ihre Daten verwendet

Hinweis

Bevor Sie die Data Engineering Agent API verwenden, müssen Sie die Schritte in den folgenden Abschnitten ausführen.

APIs aktivieren

Prüfen Sie, ob Sie die erforderlichen APIs aktiviert haben und die erforderlichen Berechtigungen besitzen. Weitere Informationen finden Sie unter Erforderliche APIs aktivieren.

Clientbibliotheken installieren

Installieren Sie die folgenden Clientbibliotheken:

Weitere Informationen finden Sie unter Agent2Agent-Protokoll (A2A).

Unterstützte A2A-Erweiterungen

Der Data Engineering Agent unterstützt die folgenden A2A-Erweiterungen. Einige davon sind für die Interaktion mit dem Data Engineering Agent erforderlich.

Name der Erweiterung Anforderung Beschreibung URI
GcpResource Erforderlich Die Google Cloud -Ressourcen-ID für die Ressource, auf die der Agent zugreift. Dies ist für jede Anfrage erforderlich. https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1
ConversationToken Optional Eine Erweiterung für den Multi-Turn-Unterhaltungsverlauf als undurchsichtiges Unterhaltungstoken.

Diese Erweiterung ist für Multi-Turn-Unterhaltungen erforderlich, um die Unterhaltung aus einem vorherigen Zustand fortzusetzen. Kopieren Sie den Wert des Konversationstokens im Metadatenfeld der vorherigen Antwort des Agenten und fügen Sie ihn in das Metadatenfeld der nächsten Anfrage an den Agenten ein.		 https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1
MessageLevel Optional Die Nachrichtenebene für die Client-Sichtbarkeitssteuerung von Nachrichtenaktualisierungen.

Der Agent, der diese Erweiterung unterstützt, fügt jedem message das messageLevel hinzu, um die Sichtbarkeit für den Kunden zu steuern.		 https://geminidataanalytics.googleapis.com/a2a/extensions/messagelevel/v1
Finish Reason Optional Eine Erweiterung, die den Grund für das Anhalten des KI-Agenten angibt.

Wenn DEADLINE_EXCEEDED zurückgegeben wird, setzt der Client die Aufgabe an der Stelle fort, an der sie unterbrochen wurde. Das Konversationstoken, das in der Antwort zurückgegeben wird, befindet sich in den Metadaten.		 https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1
Instruction Optional Vom Nutzer definierte Agent-Anweisung.

Der Agent, der diese Erweiterung unterstützt, akzeptiert eine Liste von Agent-Anweisungen als zusätzlichen Kontext mit dem Schlüssel agentInstructions. Die Anweisung für den KI-Agenten wird durch das folgende Schema definiert:
  • Name: Name der Anleitung. Das ist in der Regel der Dateiname.
  • Definition: Definition der Anleitung
 https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/v1

A2A-Erweiterung aktivieren

Damit die A2A-Erweiterung aktiviert wird, muss Ihr Client den Header A2A-Extensions in die HTTP-Anfrage an den Agent aufnehmen. Der Wert ist eine durch Kommas getrennte Liste von Erweiterungs-URIs für die Aktivierung.

Die GcpResource-Erweiterung muss aktiviert sein, damit Sie mit der Data Engineering Agent A2A API interagieren können.

Das folgende Beispiel zeigt eine HTTP-Anfrage zum Aktivieren der A2A-Erweiterung.

POST /v1/a2a/projects/{project}/locations/{location}/agents/dataengineeringagent/v1/message:stream HTTP/1.1
Host: geminidataanalytics.googleapis.com
Content-Type: application/json
Authorization: Bearer $(gcloud auth print-access-token)
A2A-Extensions: https://geminidataanalytics.googleapis.com/a2a/extensions/messagelevel/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1
Content-Length: 869

{
  "request": {
    "messageId": "0ad14bfa-8d17-48ce-8669-52a856129a66",
    "role": "ROLE_USER",
    "contextId": "test-context-id",
    "content": [{
      "text": "hi"
    }]
  },
  "metadata": {
    "https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1": "cmVxdWVzdGNvbnZlcnNhdGlvbnRva2Vu",
    "https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1": {
      "gcpResourceId": "projects/{project}/locations/{location}/repositories/{repository}/workspaces/{workspace}"
    },
   "https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/v1": {
      "agentInstructions": [{
        "definition": "Always use uppercase for SQL keywords.",
        "name": "style_guide.md"
      }]
    }
  },
  "tenant": "projects/{project}/locations/{location}/agents/dataengineeringagent"
}

Die Antwort könnte so aussehen:

HTTP/1.1 200 OK
Content-Type: application/json
A2A-Extensions: https://geminidataanalytics.googleapis.com/a2a/extensions/messagelevel/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1
Transfer-Encoding: chunked

{
  "statusUpdate": {
    "status": {
      "state": "TASK_STATE_COMPLETED",
      "timestamp": "example-timestamp"
    },
    "final": true,
    "metadata": {
      "https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1": "Y29udmVyc2F0aW9udG9rZW4=",
      "https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1": "FINISHED"
    }
  }
}

Wichtige API-Vorgänge

Die API bietet die folgenden Kernendpunkte für die Verwendung des Data Engineering Agent:

Vorgang HTTP-Methode Endpunkt Beschreibung
Agentenkarte abrufen GET /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/card Ruft die Informationen der Agent-Karte ab.
Streamingnachricht senden POST /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/message:stream Eine Streamingmethode zum Senden eines Prompts an den Agenten und zum Empfangen von Streamingantworten.

Die folgende Berechtigung ist erforderlich: geminidataanalytics.locations.useDataEngineeringAgent.
Nachricht senden POST /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/message:send Eine unäre Methode zum Senden eines Prompts an den Agenten und zum Empfangen einer synchronen Antwort. Das kann für eine schnelle Validierung oder Fragen mit nur einer Antwort hilfreich sein.

Die folgende Berechtigung ist erforderlich: geminidataanalytics.locations.useDataEngineeringAgent.

Zusätzliche Ressourcen

Detaillierte Beschreibungen von Methoden, Endpunkten und Typdefinitionen für Anfrage- und Antwortstrukturen finden Sie in der REST-Referenz zur Data Engineering Agent API.