資料工程代理 API：使用代理建構資料管道

您可以透過 geminidataanalytics.googleapis.com 存取 Data Engineering Agent API，藉此建構、修改及管理資料管道，以便在 BigQuery 中載入及處理資料。這項 API 採用 A2A 通訊協定，可讓您使用自然語言提示詞，生成及編輯資料管道，滿足資料工程需求。

如要進一步瞭解資料工程代理程式，請參閱「使用資料工程代理程式建構及修改資料管道」。

瞭解 Gemini for Google Cloud 如何使用您的資料。

事前準備

使用 Data Engineering Agent API 前，請先完成這些章節中的步驟。

啟用 API

請確認您已啟用必要 API，並具備必要權限。詳情請參閱「啟用必要 API」。

安裝用戶端程式庫

安裝下列用戶端程式庫：

詳情請參閱「Agent2Agent (A2A) 通訊協定」。

支援的 A2A 擴充功能

資料工程代理程式支援下列 A2A 擴充功能，其中部分功能與資料工程代理程式互動時必須使用。

擴充功能名稱	條件	說明	URI
`GcpResource`	必填	代理程式運作的資源 Google Cloud 資源 ID。每個要求都必須提供這項資訊。	`https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1`
`ConversationToken`	選用	多輪對話記錄的擴充功能，以不透明的對話權杖形式呈現。如要進行多輪對話，並從先前的狀態繼續對話，就必須使用這項擴充功能。如要繼續對話，請複製代理程式先前回應中繼資料欄位的對話權杖值，並將其納入下一個代理程式要求的中繼資料欄位。	`https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1`
`MessageLevel`	選用	訊息層級，用於控制訊息更新的用戶端顯示設定。支援這項擴充功能的代理程式會將 `messageLevel` 附加至每個 `message`，以控管用戶端可見度。	`https://geminidataanalytics.googleapis.com/a2a/extensions/messagelevel/v1`
`Finish Reason`	選用	擴充功能，指出代理程式停止的原因。傳回 `DEADLINE_EXCEEDED` 時，用戶端會從中繼資料回應中傳回的對話權杖，繼續執行工作。	`https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1`

啟用 A2A 擴充功能

如要啟用 A2A 擴充功能，用戶端必須在傳送給代理程式的 HTTP 要求中加入 A2A-Extensions 標頭。這個值是以半形逗號分隔的擴充功能 URI 清單，用於啟用擴充功能。

如要與 Data Engineering Agent A2A API 互動，必須啟用 GcpResource 擴充功能。

以下範例顯示啟用 A2A 擴充功能的 HTTP 要求。

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

回覆內容可能如下所示。

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

重要 API 作業

這個 API 提供下列核心端點，可供使用資料工程代理程式：

作業	HTTP 方法	端點	說明
取得代理資訊卡	GET	`/v1/a2a/{tenant=projects//locations//agents/dataengineeringagent}/v1/card`	擷取代理程式資訊卡資訊。
傳送串流訊息	POST	`/v1/a2a/{tenant=projects//locations//agents/dataengineeringagent}/v1/message:stream`	將提示傳送至代理程式並接收串流回應的串流方法。需要下列權限：`geminidataanalytics.locations.useDataEngineeringAgent`。
傳送訊息	POST	`/v1/a2a/{tenant=projects//locations//agents/dataengineeringagent}/v1/message:send`	單元方法，可將提示傳送給代理程式，並接收同步回應。這項功能適用於快速驗證或單輪問題。需要下列權限：`geminidataanalytics.locations.useDataEngineeringAgent`。

其他資源

如要詳細瞭解要求和回應結構的方法、端點和型別定義，請參閱 Data Engineering Agent API REST 參考資料。