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 data engineering.

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 for 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 abilitato 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 A2A (Agent2Agent).

Estensioni A2A supportate

Data Engineering Agent supporta le seguenti estensioni A2A, alcune delle quali sono obbligatorie quando interagisci con Data Engineering Agent.

Nome estensione	Requisito	Descrizione	URI
`GcpResource`	Obbligatorio	L'ID risorsa per la risorsa su cui opera l'agente. Google Cloud Questo è obbligatorio per ogni richiesta.	`https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1`
`ConversationToken`	Facoltativo	Un'estensione per la cronologia delle conversazioni a più turni come token di conversazione opaco. Questa estensione è necessaria per le conversazioni a più turni 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 del messaggio per il controllo della visibilità del client sugli aggiornamenti dei messaggi. L'agente che supporta questa estensione associa `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à dal punto in cui l'aveva interrotta con il token di conversazione restituito nei metadati della risposta.	`https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/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 A2A di Data Engineering Agent.

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

Operazioni API chiave

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

Operazione	Metodo HTTP	Endpoint	Descrizione
Recupera 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 le domande a turno singolo. È necessaria la seguente autorizzazione: `geminidataanalytics.locations.useDataEngineeringAgent`.

Risorse aggiuntive

Per descrizioni dettagliate dei metodi, degli endpoint e delle definizioni dei tipi per strutture di richiesta e risposta, consulta la documentazione di riferimento dell'API REST di Data Engineering Agent.