Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

透過 A2A 自動調度管理資料代理

對話式數據分析 API Google Cloud 實作了開放式代理對代理 (A2A) 通訊協定，可讓多代理工作流程中的代理探索功能、委派分析查詢，以及串流處理結構化回應，例如可執行的 SQL 查詢和圖表視覺化。

您可以在 API 要求中傳遞資料集環境，藉此查詢 Conversational Analytics API for BigQuery 和 Looker 內建的資料代理程式，也可以查詢根據貴機構商業邏輯設定的自訂資料代理程式。

如要直接建構及查詢資料代理程式，請參閱「使用 Python SDK 建構資料代理程式」或「使用 HTTP 建構資料代理程式」。

瞭解 Gemini for Google Cloud 如何使用您的資料。

資料代理自動調度的運作方式

將對話式數據分析 API 資料代理程式整合至應用程式或多代理系統時，自動化調度管理工作流程會執行下列作業：

在委派分析查詢之前，協調器代理程式會檢查資料代理程式的代理程式資訊卡，探索其功能和技能。
協調器代理程式會傳送訊息，藉由在要求中指定資料來源，查詢內建資料代理程式 (agents/bigquery-ca 或 agents/looker-ca)，或是查詢已設定網域商業邏輯的自訂資料代理程式 (dataAgents/DATA_AGENT_ID)。
資料代理程式會處理要求、執行必要查詢，並傳回結果 (完整回覆，或串流推論進度和結構化構件，例如可執行的 SQL 和 Vega-Lite 圖表規格)。

事前準備

開始之前，請先完成下列必要條件：

在 Google Cloud 專案中啟用 Conversational Analytics API、BigQuery API 和 Looker API。
確認您具備必要的 IAM 角色和權限。
向 Conversational Analytics API 進行驗證，並安裝用戶端程式庫或取得授權權杖。

必要的角色

如要取得透過 A2A 探索及查詢資料代理程式所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

Gemini Data Analytics 資料代理使用者 (roles/geminidataanalytics.dataAgentUser)
無狀態查詢： Gemini Data Analytics 資料代理無狀態使用者 (roles/geminidataanalytics.dataAgentStatelessUser)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

如要查詢基礎資料來源，您也必須具備目標 BigQuery 資料集 (例如 roles/bigquery.dataViewer) 或 Looker 探索的讀取權限。

瞭解代理功能

將查詢委派給資料代理程式之前，協調器代理程式或用戶端應用程式可以檢查代理程式卡片，查看代理程式的功能和設定，例如說明、可用技能和支援的擴充功能。您可以針對內建資料代理 (agents/bigquery-ca 和 agents/looker-ca) 和自訂資料代理 (dataAgents/DATA_AGENT_ID)，使用 getCard 方法擷取代理程式資訊卡。

擷取代理資訊卡

下列程式碼範例說明如何擷取代理程式資訊卡。這些範例以內建的 BigQuery 資料代理 (agents/bigquery-ca) 為例，但您可以變更要求中的代理資源名稱，擷取內建 Looker 代理 (agents/looker-ca) 或自訂資料代理 (dataAgents/DATA_AGENT_ID) 的資訊卡：

Python SDK

from google.cloud import geminidataanalytics_v1

client = geminidataanalytics_v1.DataA2AServiceClient()

agent_name = "projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca"

request = geminidataanalytics_v1.GetAgentCardRequest(tenant=agent_name)
card = client.get_agent_card(request=request)

print(card)

在上述範例中，請依下列方式替換值：

PROJECT_ID：您 Google Cloud 專案的 ID
LOCATION：代理程式資源的位置 (例如 us、us-east4、eu 或 global)

HTTP

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  "https://geminidataanalytics.googleapis.com/v1/a2a/projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca/v1/card"

在上述範例中，請依下列方式替換值：

PROJECT_ID：您 Google Cloud 專案的 ID
LOCATION：代理程式資源的位置 (例如 us、us-east4、eu 或 global)

瞭解代理程式資訊卡結構

如果要求成功，系統會傳回包含中繼資料、支援的技能和擴充功能的代理程式資訊卡物件：

{
  "name": "BigQuery Conversational Analytics Agent",
  "description": "This agent can answer questions about your data using BigQuery.",
  "protocolVersion": "1.0",
  "skills": [
    {
      "id": "data-analysis",
      "name": "Data Analysis",
      "description": "Provides data analysis assistance",
      "examples": [
        "What is the total sales for the last 3 months?"
      ],
      "inputModes": [
        "text/plain"
      ],
      "outputModes": [
        "text/plain",
        "application/json"
      ]
    }
  ],
  "capabilities": {
    "streaming": true,
    "extensions": [
      {
        "uri": "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1",
        "description": "Google Data Analytics BigQuery Context extension"
      }
    ]
  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ]
}

代理程式資訊卡包含下列欄位：

name：資料代理程式的顯示名稱
description：資料代理的分析功能摘要
protocolVersion：端點支援的 A2A 通訊協定版本 (例如 1.0)
skills：資料代理程式可執行的工作，包括提示範例 (examples) 和支援的資料格式 (inputModes 和 outputModes，例如 text/plain 或 application/json)
capabilities.streaming：布林值，指出資料代理程式是否支援透過 stream 方法進行即時串流
capabilities.extensions：資料代理程式支援的 A2A 擴充功能，例如 bigquery_context/v1、stateless/v1 和 kms/v1
defaultInputModes 和 defaultOutputModes：要求和回應酬載的預設資料格式 (例如 text/plain 或 application/json)

傳送訊息給資料代理人

如要傳送訊息給資料代理程式，請使用 send 方法。資料代理程式會處理要求、針對資料生成並執行必要的 SQL 查詢，然後傳回自然語言答案和生成的資料構件。

傳送訊息

傳送訊息時，請在資源路徑中指定目標資料代理人：

如果是內建資料代理程式 (agents/bigquery-ca 或 agents/looker-ca)，請使用 bigquery_context/v1 或 looker_context/v1 擴充功能，在 metadata 欄位中傳遞目標資料表或探索參照。
如果是自訂資料代理 (dataAgents/DATA_AGENT_ID)，請省略 metadata 欄位，因為背景資訊、結構定義和指令會直接在代理資源上設定。

如要處理查詢，但不要在 Google Cloud中儲存對話記錄，請在要求中加入 stateless/v1 擴充功能。如要使用客戶自行管理的加密金鑰加密儲存的對話資料和中繼資料，請傳遞含有 Cloud KMS 金鑰名稱的 kms/v1 擴充功能。詳情請參閱「客戶自行管理的加密金鑰 (CMEK)」。

下列程式碼範例說明如何將訊息傳送至內建的 BigQuery 資料代理程式：

Python SDK

from google.cloud import geminidataanalytics_v1

client = geminidataanalytics_v1.DataA2AServiceClient()

agent_name = "projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca"

request = geminidataanalytics_v1.SendMessageRequest(
    tenant=agent_name,
    message=geminidataanalytics_v1.Message(
        role="ROLE_USER",
        # Optional: Pass context_id to continue an existing conversation
        # context_id="projects/PROJECT_ID/locations/LOCATION/conversations/CONVERSATION_ID",
        parts=[
            geminidataanalytics_v1.Part(
                text="What are the top 5 countries where our users are located?"
            )
        ],
    ),
    configuration=geminidataanalytics_v1.SendMessageConfiguration(
        return_immediately=False
    ),
    metadata={
        "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1": {
            "datasource_references": {
                "bq": {
                    "tableReferences": [
                        {
                            "projectId": "DATASET_PROJECT_ID",
                            "datasetId": "DATASET_ID",
                            "tableId": "TABLE_ID",
                        }
                    ]
                }
            }
        },
        # Optional: Process queries without storing conversation history in Google Cloud
        # "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/stateless/v1": {},
        # Optional: Encrypt conversation history and metadata with a customer-managed encryption key (CMEK)
        # "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/kms/v1": {
        #     "kmsKey": "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"
        # },
    },
)

response = client.send_message(request=request)

print(response)

在上述範例中，請依下列方式替換值：

PROJECT_ID：您 Google Cloud 專案的 ID
LOCATION：代理程式資源的位置 (例如 us、us-east4、eu 或 global)
CONVERSATION_ID：(選用) 要繼續的現有對話工作階段 ID
What are the top 5 countries where our users are located?：向資料代理提出的自然語言問題
DATASET_PROJECT_ID：包含 BigQuery 資料集的 Google Cloud 專案 ID (例如 bigquery-public-data)
DATASET_ID：BigQuery 資料集的 ID (例如 thelook_ecommerce)
TABLE_ID：BigQuery 資料表的 ID (例如 users)
KEY_RING：(選用) 使用 CMEK 時的 Cloud KMS 金鑰環名稱
KEY_NAME：(選用) 使用 CMEK 時的 Cloud KMS 加密編譯金鑰名稱

HTTP

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "A2A-Extensions: https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1" \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "parts": [
        {
          "text": "What are the top 5 countries where our users are located?"
        }
      ]
    },
    "configuration": {
      "return_immediately": false
    },
    "metadata": {
      "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1": {
        "datasource_references": {
          "bq": {
            "tableReferences": [
              {
                "projectId": "DATASET_PROJECT_ID",
                "datasetId": "DATASET_ID",
                "tableId": "TABLE_ID"
              }
            ]
          }
        }
      }
    }
  }' \
  "https://geminidataanalytics.googleapis.com/v1/a2a/projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca/v1/message:send"

在上述範例中，請依下列方式替換值：

PROJECT_ID：您 Google Cloud 專案的 ID
LOCATION：代理程式資源的位置 (例如 us、us-east4、eu 或 global)
What are the top 5 countries where our users are located?：向資料代理提出的自然語言問題
DATASET_PROJECT_ID：包含 BigQuery 資料集的 Google Cloud 專案 ID (例如 bigquery-public-data)
DATASET_ID：BigQuery 資料集的 ID (例如 thelook_ecommerce)
TABLE_ID：BigQuery 資料表的 ID (例如 users)

瞭解回覆結構

如果要求成功，系統會傳回 task 物件，其中包含最終狀態、對話 ID 和產生的構件：

{
  "task": {
    "id": "ab12d1f2-e170-4c4f-aff4-be466c6beaaa",
    "contextId": "projects/my-project/locations/us/conversations/conv-67890",
    "status": {
      "state": "TASK_STATE_COMPLETED"
    },
    "artifacts": [
      {
        "artifactId": "synthetic-8a368e8e-378a-4b80-9f07-0b1a397c221d",
        "name": "Final response",
        "description": "Final response from the agent.",
        "parts": [
          {
            "text": "The top 5 countries where our users are located are China (33,783), the United States (22,701), Brasil (14,620), South Korea (5,302), and France (4,645)."
          }
        ]
      },
      {
        "artifactId": "synthetic-50483808-b231-4b30-a859-2c30d0355a8d",
        "name": "Generated SQL",
        "description": "Generated SQL from the agent.",
        "parts": [
          {
            "text": "SELECT country, COUNT(DISTINCT id) AS user_count FROM `bigquery-public-data.thelook_ecommerce.users` GROUP BY country ORDER BY user_count DESC LIMIT 5",
            "mediaType": "text/x-sql"
          }
        ]
      }
    ]
  }
}

回應會包括下列重要欄位：

task.id：執行工作的專屬 ID
task.contextId：對話的資源路徑，您會在後續要求的 message.contextId 欄位中傳遞這個路徑，以繼續工作階段
task.status.state：工作執行狀態 (例如 TASK_STATE_COMPLETED)
task.artifacts[]：由資料代理程式產生的結構化資產，例如自然語言答案 (Final response)、可執行的 SQL 查詢 (Generated SQL) 和表格結果列 (Data result)

串流資料代理程式的回覆

如要在資料代理程式透過查詢進行推論時接收即時更新，請使用 stream 方法。回應會串流傳送狀態更新 (status_update)，以及中間想法和增量構件 (artifact_update)，例如產生的 SQL 查詢和 Vega-Lite 圖表規格。

串流要求也支援繼續對話 (context_id)、無狀態處理 (stateless/v1) 和客戶自行管理的加密金鑰 (kms/v1)。

傳送串流訊息

下列程式碼範例說明如何從內建的 BigQuery 資料代理串流事件。如要從自訂資料代理 (dataAgents/DATA_AGENT_ID) 串流，請指定自訂代理資源路徑，並省略 metadata 欄位：

Python SDK

from google.cloud import geminidataanalytics_v1

client = geminidataanalytics_v1.DataA2AServiceClient()

agent_name = "projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca"

request = geminidataanalytics_v1.SendMessageRequest(
    tenant=agent_name,
    message=geminidataanalytics_v1.Message(
        role="ROLE_USER",
        parts=[
            geminidataanalytics_v1.Part(
                text="What are the top 5 countries where our users are located? Please show a pie chart."
            )
        ],
    ),
    metadata={
        "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1": {
            "datasource_references": {
                "bq": {
                    "tableReferences": [
                        {
                            "projectId": "DATASET_PROJECT_ID",
                            "datasetId": "DATASET_ID",
                            "tableId": "TABLE_ID",
                        }
                    ]
                }
            }
        },
        # Optional: Process queries without storing conversation history in Google Cloud
        # "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/stateless/v1": {},
        # Optional: Encrypt conversation history and metadata with a customer-managed encryption key (CMEK)
        # "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/kms/v1": {
        #     "kmsKey": "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"
        # },
    },
)

# Stream response events
stream = client.send_streaming_message(request=request)

for chunk in stream:
  print(chunk)

在上述範例中，請依下列方式替換值：

PROJECT_ID：您 Google Cloud 專案的 ID
LOCATION：代理程式資源的位置 (例如 us、us-east4、eu 或 global)
What are the top 5 countries where our users are located? Please show a pie chart.：向資料代理提出的自然語言問題
DATASET_PROJECT_ID：包含 BigQuery 資料集的 Google Cloud 專案 ID (例如 bigquery-public-data)
DATASET_ID：BigQuery 資料集的 ID (例如 thelook_ecommerce)
TABLE_ID：BigQuery 資料表的 ID (例如 users)
KEY_RING：(選用) 使用 CMEK 時的 Cloud KMS 金鑰環名稱
KEY_NAME：(選用) 使用 CMEK 時的 Cloud KMS 加密編譯金鑰名稱

HTTP

curl -X POST \
  -N \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: text/event-stream, application/json" \
  -H "A2A-Extensions: https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1" \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "parts": [
        {
          "text": "What are the top 5 countries where our users are located? Please show a pie chart."
        }
      ]
    },
    "metadata": {
      "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1": {
        "datasource_references": {
          "bq": {
            "tableReferences": [
              {
                "projectId": "DATASET_PROJECT_ID",
                "datasetId": "DATASET_ID",
                "tableId": "TABLE_ID"
              }
            ]
          }
        }
      }
    }
  }' \
  "https://geminidataanalytics.googleapis.com/v1/a2a/projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca/v1/message:stream"

在上述範例中，請依下列方式替換值：

PROJECT_ID：您 Google Cloud 專案的 ID
LOCATION：代理程式資源的位置 (例如 us、us-east4、eu 或 global)
What are the top 5 countries where our users are located? Please show a pie chart.：向資料代理提出的自然語言問題
DATASET_PROJECT_ID：包含 BigQuery 資料集的 Google Cloud 專案 ID (例如 bigquery-public-data)
DATASET_ID：BigQuery 資料集的 ID (例如 thelook_ecommerce)
TABLE_ID：BigQuery 資料表的 ID (例如 users)

瞭解串流回應結構

傳送串流要求時，伺服器會傳回一連串的事件物件 (StreamResponse)。每個事件都包含狀態更新或構件更新。

狀態更新事件會在資料代理程式推論查詢時，傳送中間進度通知和想法訊息：

{
  "statusUpdate": {
    "taskId": "f41cd8e3-e665-460c-aceb-7b337f1848ef",
    "status": {
      "state": "TASK_STATE_WORKING",
      "message": {
        "role": "ROLE_AGENT",
        "parts": [
          {
            "text": "Analyzing context"
          },
          {
            "text": "Retrieved context for 1 table."
          }
        ]
      }
    }
  }
}

構件更新事件會提供結構化輸出物件，例如可執行的 SQL 查詢、自然語言答案或圖表規格：

{
  "artifactUpdate": {
    "taskId": "f41cd8e3-e665-460c-aceb-7b337f1848ef",
    "artifact": {
      "artifactId": "synthetic-7ca98286-0a15-4ca0-a8bc-f14dc231b3ba",
      "name": "Chart result",
      "description": "Chart visualization generated by the data agent.",
      "parts": [
        {
          "data": {
            "title": "Top 5 Countries by User Population",
            "mark": "arc",
            "encoding": {
              "color": {
                "field": "country",
                "type": "nominal"
              },
              "theta": {
                "field": "user_count",
                "type": "quantitative"
              }
            },
            "data": {
              "values": [
                {
                  "country": "China",
                  "user_count": 33783
                },
                {
                  "country": "United States",
                  "user_count": 22701
                },
                {
                  "country": "Brasil",
                  "user_count": 14620
                },
                {
                  "country": "South Korea",
                  "user_count": 5302
                },
                {
                  "country": "France",
                  "user_count": 4645
                }
              ]
            }
          }
        }
      }
    },
    "lastChunk": true
  }
}

串流回應包含下列重要欄位：

statusUpdate.status.state：任務的中間或最終狀態 (例如 TASK_STATE_WORKING 或 TASK_STATE_COMPLETED)
statusUpdate.status.message.parts[]：執行期間發出的想法或進度說明
artifactUpdate.artifact：資料代理程式產生的結構化資產，例如 Vega-Lite 圖表規格 (data) 或 SQL 查詢 (text)
artifactUpdate.lastChunk：布林值標記，表示構件串流是否完整

如要在 Python 或前端應用程式中算繪傳回的 Vega 或 Vega-Lite 規格，請參閱「將代理程式回覆算繪為視覺化內容」。

後續步驟

瞭解如何使用 Vega-Lite 和 Altair，將代理程式回覆內容算繪為視覺化內容。
瞭解如何使用撰寫的內容引導服務專員行為，設定業務規則和已驗證的查詢。
瞭解多代理系統的架構整合模式。
查看 Gemini Data Analytics API REST 參考資料。

透過 A2A 自動調度管理資料代理 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

資料代理自動調度的運作方式

事前準備

必要的角色

瞭解代理功能

擷取代理資訊卡

Python SDK

HTTP

瞭解代理程式資訊卡結構

傳送訊息給資料代理人

傳送訊息

Python SDK

HTTP

瞭解回覆結構

串流資料代理程式的回覆

傳送串流訊息

Python SDK

HTTP

瞭解串流回應結構

後續步驟

透過 A2A 自動調度管理資料代理