API Data Engineering Agent: crea pipeline di dati con un agente

Puoi utilizzare l'API Data Engineering Agent, a cui si accede tramite geminidataanalytics.googleapis.com, per creare, modificare e gestire pipeline di dati per caricare ed elaborare i dati in BigQuery. L'API utilizza il protocollo A2A che ti consente di utilizzare prompt in linguaggio naturale per generare e modificare pipeline di dati per le tue esigenze di ingegneria dei dati.

Per saperne di più su Data Engineering Agent, consulta Utilizzare Data Engineering Agent per creare e modificare pipeline di dati.

Scopri come e quando Gemini per Google Cloud utilizza i tuoi dati.

Prima di iniziare

Prima di utilizzare l'API Data Engineering Agent, esegui i passaggi descritti in queste sezioni.

Abilita API

Assicurati di aver attivato le API richieste e di disporre delle autorizzazioni necessarie. Per saperne di più, consulta Abilitare le API richieste.

Installazione delle librerie client

Installa le seguenti librerie client:

Per saperne di più, consulta Protocollo Agent2Agent (A2A).

Estensioni A2A supportate

Data Engineering Agent supporta le seguenti estensioni A2A, alcune delle quali sono necessarie per interagire con Data Engineering Agent.

Nome estensione Requisito Descrizione URI
GcpResource Obbligatorio L'ID risorsa Google Cloud per la risorsa su cui opera l'agente. Questo è obbligatorio per ogni richiesta. https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1
ConversationToken Facoltativo Un'estensione della cronologia delle conversazioni a turni multipli come token di conversazione opaco.

Questa estensione è necessaria per le conversazioni multi-turno per continuare la conversazione da uno stato precedente. Per continuare, copia il valore del token di conversazione nel campo dei metadati della risposta precedente dell'agente e includilo nel campo dei metadati della richiesta successiva all'agente.		 https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1
MessageLevel Facoltativo Il livello di messaggio per il controllo della visibilità del client sugli aggiornamenti dei messaggi.

L'agente che supporta questa estensione allega il messageLevel a ogni message per il controllo della visibilità del client.		 https://geminidataanalytics.googleapis.com/a2a/extensions/messagelevel/v1
Finish Reason Facoltativo Un'estensione che indica il motivo per cui l'agente si è fermato.

Quando viene restituito DEADLINE_EXCEEDED, il client riprende l'attività da dove l'aveva interrotta con il token di conversazione restituito nella risposta nei metadati.		 https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1
Instruction Facoltativo Istruzione dell'agente definita dall'utente.

L'agente che supporta questa estensione accetta un elenco di istruzioni dell'agente come contesto aggiuntivo con la chiave agentInstructions. L'istruzione dell'agente è definita dal seguente schema:
  • Name: il nome dell'istruzione. Di solito è il nome del file
  • Definition: definizione dell'istruzione
 https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/v1

Attivare l'estensione A2A

Per attivare l'estensione A2A, il client deve includere l'intestazione A2A-Extensions nella richiesta HTTP all'agente. Il valore è un elenco separato da virgole di URI di estensione per l'attivazione.

L'estensione GcpResource deve essere attivata per interagire con l'API Data Engineering Agent A2A.

L'esempio seguente mostra una richiesta HTTP per attivare l'estensione 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 risposta potrebbe essere simile alla seguente.

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

Operazioni API chiave

L'API fornisce i seguenti endpoint principali per l'utilizzo dell'agente di Data Engineering:

Operazione Metodo HTTP Endpoint Descrizione
Recupera la scheda Agente GET /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/card Recupera le informazioni della scheda dell'agente.
Invia messaggio in streaming POST /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/message:stream Un metodo di streaming per inviare un prompt all'agente e ricevere risposte in streaming.

È necessaria la seguente autorizzazione: geminidataanalytics.locations.useDataEngineeringAgent.
Invia messaggio POST /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/message:send Un metodo unario per inviare un prompt all'agente e ricevere una risposta sincrona. Può essere utile per la convalida rapida o per domande a un solo turno.

È necessaria la seguente autorizzazione: geminidataanalytics.locations.useDataEngineeringAgent.

Risorse aggiuntive

Per descrizioni dettagliate di metodi, endpoint e definizioni di tipo per le strutture di richiesta e risposta, consulta il riferimento all'API REST di Data Engineering Agent.