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

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

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

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

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 には、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 リファレンスをご覧ください。