数据工程代理 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) Protocol。

支持的 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 可选 用于控制消息更新的客户端可见性的消息级别。

支持此扩展程序的代理会将 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 的列表。

必须激活 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/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 参考。