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

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

Data Engineering Agent の詳細については、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 必須 エージェントが動作するリソースのリソース ID。 Google Cloud これはリクエストごとに必要です。 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 リファレンスをご覧ください。