Data Engineering Agent API: エージェントを使用してデータ パイプラインを構築する

geminidataanalytics.googleapis.com を介してアクセスできる Data Engineering Agent API を使用すると、BigQuery でデータを読み込んで処理するデータ パイプラインを構築、変更、管理できます。この API は、自然言語プロンプトを使用してデータ エンジニアリングのニーズに合わせてデータ パイプラインを生成および編集できる A2A プロトコルを使用します。

Data Engineering Agent の詳細については、Data Engineering Agent を使用してデータ パイプラインを構築、変更するをご覧ください。

Gemini for Google Cloud がデータを使用する方法とタイミングに関する説明をご覧ください。

始める前に

Data Engineering Agent API を使用する前に、次のセクションの手順を行います。

API を有効にする

必要な API が有効になっており、必要な権限があることを確認します。詳細については、必要な API を有効にするをご覧ください。

クライアント ライブラリのインストール

次のクライアント ライブラリをインストールします。

詳細については、Agent2Agent（A2A）プロトコルをご覧ください。

サポートされている A2A 拡張機能

Data Engineering Agent は次の A2A 拡張機能をサポートしています。これらの拡張機能の一部は、Data Engineering Agent とのやり取りで必要になります。

拡張機能名 要件 説明 URI
GcpResource 必須 エージェントが操作するリソースの Google Cloud リソース ID。これは各リクエストで必須です。 https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1
ConversationToken 省略可 不透明な会話トークンとしてのマルチターン会話履歴の拡張機能。

マルチターン会話で前の状態から会話を続行するには、この拡張機能が必要です。続行するには、エージェントからの前のレスポンスのメタデータ フィールドにある会話トークン値をコピーして、エージェントへの次のリクエストのメタデータ フィールドに含めます。		 https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1
MessageLevel 省略可 メッセージの更新に対するクライアントの可視性制御のメッセージ レベル。

この拡張機能をサポートするエージェントは、クライアントの可視性制御のために各 message に messageLevel を付加します。		 https://geminidataanalytics.googleapis.com/a2a/extensions/messagelevel/v1
Finish Reason 省略可 エージェントが停止した理由を示す拡張機能。

DEADLINE_EXCEEDED が返されると、クライアントは、レスポンスで返された会話トークンをメタデータに含めて、中断したところからタスクを再開します。		 https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1
Instruction 省略可 ユーザー定義のエージェント指示。

この拡張機能をサポートするエージェントは、キー agentInstructions を持つ追加のコンテキストとしてエージェント指示のリストを受け入れます。エージェント指示は、次のスキーマで定義されます。
  • Name: 指示の名前。通常はファイル名です
  • Definition: 指示の定義
 https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/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/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/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 には、Data Engineering Agent を使用するための次のコア エンドポイントが用意されています。

オペレーション 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 リファレンスをご覧ください。