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 afin de charger et de traiter des données dans BigQuery. L'API utilise le protocole A2A qui vous permet d'utiliser des prompts 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 d'ingénierie des données, consultez Utiliser l'agent d'ingénierie des données 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 d'extension Exigence Description URI
GcpResource Obligatoire ID de ressource sur laquelle l'agent opère. Google Cloud Cette valeur est requise pour chaque requête. https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1
ConversationToken Facultatif Extension pour 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 requête suivante adressée à l'agent.		 https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1
MessageLevel Facultatif Niveau de message pour le contrôle de la visibilité des mises à jour des messages par le client.

L'agent compatible avec cette extension associe le messageLevel à chaque message pour contrôler la visibilité du 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

Activer l'extension A2A

Pour activer l'extension A2A, votre client doit inclure l'en-tête A2A-Extensions dans la requête HTTP adressé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 d'ingénierie des données.

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/pipelinecontext/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 être semblable à la suivante.

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/pipelinecontext/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 d'ingénierie des données :

Opération Méthode HTTP Point de terminaison Description
Obtenir la carte de l'agent GET /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/card Récupère les informations de la carte de l'agent.
Envoyer un message en streaming POST /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/message:stream Méthode de streaming permettant d'envoyer un prompt à 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 un prompt à l'agent et de recevoir une réponse synchrone. Cela peut être utile pour une validation rapide ou des questions à un seul tour.

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 REST de l'APIData Engineering Agent.