API Data Engineering Agent : créer des pipelines de données avec un agent

Vous pouvez utiliser l'API Data Engineering Agent, accessible via geminidataanalytics.googleapis.com, pour créer, modifier et gérer des pipelines de données permettant de charger et de traiter des données dans BigQuery. L'API utilise le protocole A2A, qui vous permet d'utiliser des requêtes en langage naturel pour générer et modifier des pipelines de données en fonction de vos besoins en ingénierie des données.

Pour en savoir plus sur l'agent Data Engineering, consultez Utiliser l'agent Data Engineering pour créer et modifier des pipelines de données.

Découvrez comment et quand Gemini pour Google Cloud utilise vos données.

Avant de commencer

Avant d'utiliser l'API Data Engineering Agent, suivez les étapes décrites dans ces sections.

Activer les API

Assurez-vous d'avoir activé les API requises et de disposer des autorisations nécessaires. Pour en savoir plus, consultez Activer les API requises.

Installer les bibliothèques clientes

Installez les bibliothèques clientes suivantes :

Pour en savoir plus, consultez Protocole Agent2Agent (A2A).

Extensions A2A compatibles

L'agent d'ingénierie des données est compatible avec les extensions A2A suivantes, dont certaines sont requises lors de l'interaction avec l'agent d'ingénierie des données.

Nom de l'extension Exigence Description URI
GcpResource Obligatoire ID de ressource Google Cloud pour la ressource sur laquelle l'agent opère. Cette opération est obligatoire pour chaque demande. https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1
ConversationToken Facultatif Extension de l'historique des conversations multitours sous forme de jeton de conversation opaque.

Cette extension est requise pour que les conversations multitours puissent reprendre à partir d'un état précédent. Pour continuer, copiez la valeur du jeton de conversation dans le champ de métadonnées de la réponse précédente de l'agent, puis incluez-la dans le champ de métadonnées de la prochaine requête à l'agent.		 https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1
MessageLevel Facultatif Niveau du message pour le contrôle de la visibilité des mises à jour des messages par le client.

L'agent compatible avec cette extension associe messageLevel à chaque message pour contrôler la visibilité par le client.		 https://geminidataanalytics.googleapis.com/a2a/extensions/messagelevel/v1
Finish Reason Facultatif Extension qui indique la raison pour laquelle l'agent s'est arrêté.

Lorsque DEADLINE_EXCEEDED est renvoyé, le client reprend la tâche là où il l'avait laissée avec le jeton de conversation renvoyé dans la réponse dans les métadonnées.		 https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1
Instruction Facultatif Instruction de l'agent définie par l'utilisateur.

L'agent prenant en charge cette extension accepte une liste d'instructions de l'agent comme contexte supplémentaire avec la clé agentInstructions. L'instruction de l'agent est définie par le schéma suivant :
  • Name : nom de l'instruction. Il s'agit généralement du nom de fichier.
  • Definition : définition de l'instruction
 https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/v1

Activer l'extension A2A

Pour activer l'extension A2A, votre client doit inclure l'en-tête A2A-Extensions dans la requête HTTP envoyée à l'agent. La valeur est une liste d'URI d'extension séparés par une virgule pour l'activation.

L'extension GcpResource doit être activée pour interagir avec l'API A2A de l'agent Data Engineering.

L'exemple suivant montre une requête HTTP permettant d'activer l'extension A2A.

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"
}

La réponse peut ressembler à ce qui suit :

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"
    }
  }
}

Principales opérations d'API

L'API fournit les principaux points de terminaison suivants pour utiliser l'agent Data Engineering :

Opération Méthode HTTP Point de terminaison Description
Obtenir la carte d'agent GET /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/card Récupère les informations de la fiche de l'agent.
Envoyer un message de streaming POST /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/message:stream Méthode de streaming permettant d'envoyer une requête à l'agent et de recevoir des réponses en streaming.

L'autorisation suivante est requise : geminidataanalytics.locations.useDataEngineeringAgent.
Envoyer un message POST /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/message:send Méthode unaire permettant d'envoyer une requête à l'agent et de recevoir une réponse synchrone. Cela peut être utile pour une validation rapide ou des questions ponctuelles.

L'autorisation suivante est requise : geminidataanalytics.locations.useDataEngineeringAgent.

Autres ressources

Pour obtenir des descriptions détaillées des méthodes, des points de terminaison et des définitions de type pour les structures des requêtes et des réponses, consultez la documentation de référence de l'API REST Data Engineering Agent.