数据工程代理 API：使用代理构建数据流水线

您可以使用 Data Engineering Agent API（通过 geminidataanalytics.googleapis.com 访问）来构建、修改和管理数据流水线，以便在 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 必需 代理所操作资源的资源 ID。 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
Instruction 可选 用户定义的代理指令。

支持此扩展程序的代理接受代理指令列表作为附加上下文，键为 agentInstructions。代理指令由以下架构定义：
  • Name：指令的名称。这通常是文件名
  • Definition：指令的定义
 https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/v1

激活 A2A 扩展程序

如需激活 A2A 扩展程序，您的客户端必须在向代理发出的 HTTP 请求中包含 A2A-Extensions 标头。该值是以英文逗号分隔的扩展程序 URI 列表，用于激活。

必须激活 GcpResource 扩展程序，才能与 Data Engineering Agent A2A API 互动。

以下示例展示了用于激活 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 参考。