GENAI120

Agent2Agent (A2A) 通訊協定可解決 AI 領域的一項重大挑戰：讓不同公司在獨立伺服器上，執行以各種架構建構的生成式 AI 代理，以便有效地進行通訊和協作，讓代理不再只是工具。A2A 的目標是為代理提供通用語言，促進更緊密相互連結、更強大且創新的 AI 生態系統。

A2A 是以下列幾個核心概念設計而成，因此功能強大且靈活：

• 標準化通訊：透過 HTTP(S) 的 JSON-RPC 2.0。
• 代理探索：代理資訊卡提供代理功能和連線資訊的相關詳情，因此代理可以互相探索，瞭解彼此的功能。
• 交換豐富資料：處理文字、檔案和結構化 JSON 資料。
• 彈性互動：支援同步要求/回覆、串流 (SSE) 和非同步推播通知。
• 企業適用：在設計時便已考量到安全性、驗證和觀測功能。

目標

本實驗室的學習內容如下：

• 將 ADK 代理部署為 A2A 伺服器。
• 準備 JSON 代理資訊卡，說明 A2A 代理的功能。
• 啟用其他 ADK 代理，以便讀取已部署 A2A 代理的代理資訊卡，並將其當做子代理使用。

設定和需求

瞭解以下事項後，再點選「Start Lab」按鈕

請詳閱以下操作說明。實驗室活動會計時，中途無法暫停。點選「Start Lab」後就會開始計時，顯示可使用 Google Cloud 資源的時間。

您會在實際雲端環境中完成 Qwiklabs 實作實驗室活動，而非模擬或示範環境。為此，我們會提供新的暫時憑證，供您在實驗室活動期間登入及存取 Google Cloud。

需求條件

為了順利完成這個實驗室，請先確認：

• 可以使用標準的網際網路瀏覽器 (Chrome 瀏覽器為佳)。
• 已預留充足時間可完成實驗室。

注意：如果您擁有個人 Google Cloud 或專案，請勿用於本實驗室。

注意：如果您使用的是 Pixelbook，請在無痕視窗執行本實驗室。

如何開始研究室及登入 Google Cloud 控制台

1. 點選「Start Lab」按鈕。如果實驗室會產生費用，畫面上會出現選擇付款方式的對話方塊。左側的「Lab Details」窗格會顯示下列項目：

   • 「Open Google Cloud console」按鈕
   • 剩餘時間
   • 必須在這個研究室中使用的臨時憑證
   • 完成這個實驗室所需的其他資訊 (如有)

2. 點選「Open Google Cloud console」；如果使用 Chrome 瀏覽器，也能按一下滑鼠右鍵，選取「在無痕視窗中開啟連結」。

   接著，實驗室會啟動相關資源，並開啟另一個分頁，顯示「登入」頁面。

   提示：您可以在不同的視窗中並排開啟分頁。

   注意：如果頁面中顯示「選擇帳戶」對話方塊，請點選「使用其他帳戶」。

3. 如有必要，請將下方的 Username 貼到「登入」對話方塊。

   {{{user_0.username | "Username"}}}

   您也可以在「Lab Details」窗格找到 Username。

4. 點選「下一步」。

5. 複製下方的 Password，並貼到「歡迎使用」對話方塊。

   {{{user_0.password | "Password"}}}

   您也可以在「Lab Details」窗格找到 Password。

6. 點選「下一步」。

   重要事項：請務必使用實驗室提供的憑證，而非自己的 Google Cloud 帳戶憑證。 注意：如果使用自己的 Google Cloud 帳戶來進行這個實驗室，可能會產生額外費用。

7. 按過後續的所有頁面：

   • 接受條款及細則。
   • 由於這是臨時帳戶，請勿新增救援選項或雙重驗證機制。
   • 請勿申請免費試用。

Google Cloud 控制台稍後會在這個分頁開啟。

注意：如要使用 Google Cloud 產品和服務，請點選「導覽選單」，或在「搜尋」欄位輸入服務或產品名稱。

工作 1：安裝 ADK 並設定環境

在本實驗室環境中，系統已為您啟用 Vertex AI API 和 Cloud Run API。如要在您的專案中執行這些步驟，請前往 Vertex AI，然後按照提示啟用。

準備 Cloud Shell 編輯器分頁

1. 選取 Google Cloud 控制台視窗，然後依序按下鍵盤上的 G 和 S 鍵，開啟 Cloud Shell。或者，您也可以點按 Cloud 控制台右上方的「Activate Cloud Shell」(啟用 Cloud Shell) 按鈕 ()。

2. 按一下「Continue」(繼續)。

3. 如果系統提示您為 Cloud Shell 提供授權，請按一下「Authorize」(授權)。

4. 在 Cloud Shell 終端機面板的右上角，按一下「Open in new window」(在新視窗中開啟) 按鈕 。

5. 在 Cloud Shell 終端機中輸入下列指令，開啟 Cloud Shell 編輯器並前往主目錄：

   cloudshell workspace ~

6. 關閉畫面右側顯示的任何其他教學課程或 Gemini 面板，為程式碼編輯器保留更多視窗空間。

7. 在本實驗室的其餘部分，您可以在這個視窗中，將 Cloud Shell 編輯器和 Cloud Shell 終端機當做 IDE 使用。

下載並安裝本實驗室的 ADK 和程式碼範例

1. 在 Cloud Shell 終端機中執行下列指令，安裝 ADK。注意：您將指定版本，以確保安裝的 ADK 版本與本實驗室使用的版本相符：

   # Install ADK and the A2A Python SDK cd ~ export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install google-adk==1.8.0 a2a-sdk==0.2.16 pip install --upgrade google-genai # Correcting a typo in this version sed -i 's/{a2a_option}"/{a2a_option} "/' ~/.local/lib/python3.12/site-packages/google/adk/cli/cli_deploy.py

2. 將下列指令貼到 Cloud Shell 終端機，從 Cloud Storage bucket 複製實驗室程式碼並解壓縮：

   gcloud storage cp gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_and_a2a.zip ./adk_and_a2a.zip unzip adk_and_a2a.zip

   點按「Check my progress」(確認進度)，確認目標已達成。 安裝 ADK 並設定環境。

工作 2：瀏覽您要遠端提供的 ADK 代理

在本實驗室中，假設您在體育場維護公司 Cymbal Stadiums 工作。在最近的專案中，您開發了圖像生成代理，可根據品牌宣傳指南製作插圖。現在，貴組織的幾個不同團隊也想使用該代理。

如果複製程式碼供多位代理當做子代理使用，維護及改善所有副本的難度會非常高。

您可以改為將代理部署為以 A2A 伺服器包裝的代理，其他團隊的代理則可透過遠端查詢方式納入該代理。

1. 在 Cloud Shell 編輯器的檔案總管窗格中，前往 adk_and_a2a/illustration_agent 目錄。這個目錄包含您要遠端提供的 ADK 代理。按一下目錄即可開啟。

2. 開啟這個目錄中的 agent.py 檔案，然後捲動至標示為「# Tools」的部分。

3. 請注意 generate_image() 函式，這個函式會當做這個代理的工具，用於接收提示詞並執行兩步驟程序。首先，這個函式會使用 Google Gen AI SDK 呼叫 generate_content()，直接在回應中傳回原始圖像資料。接著，該函式會使用 Cloud Storage 程式庫，將這些圖像位元組上傳至 GCS bucket。最後，這項工具會傳回新建圖像檔案的公開網址。

4. 請注意，提供給 root_agent 的指令含有具體指示，可要求代理使用符合公司品牌宣傳指南的圖像生成提示詞。比方說，該指令可指定：

   • 特定插畫風格：(Corporate Memphis)
   • 調色盤 (日落漸層時的紫色和綠色)
   • 體育館/運動和維護的圖像範例，因為這是體育館維護公司

5. 如要查看實際運作情況，請先編寫 .env 檔案，設定 ADK 代理所需的環境變數。在 Cloud Shell 終端機中執行下列指令，將這個檔案寫入這個目錄。

   cd ~/adk_and_a2a cat << EOF > illustration_agent/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION=global MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} IMAGE_MODEL={{{project_0.startup_script.gemini_flash_image_model_id | gemini_flash_image_model_id}}} EOF

6. 執行下列指令，將 .env 複製到本實驗室要使用的另一個代理目錄：

   cp illustration_agent/.env slide_content_agent/.env

7. 在 Cloud Shell 終端機中輸入下列指令，啟動 ADK 開發人員使用者介面：

   adk web

   輸出內容

   INFO: Started server process [2434] INFO: Waiting for application startup. +-------------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8000. | +-------------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

8. 按一下終端機輸出內容底部的 http://127.0.0.1:8000 連結，在新分頁中開啟網頁介面。

9. 系統會開啟新的瀏覽器分頁，顯示 ADK 開發人員使用者介面。

10. 在左側的「Select an agent」(選取代理) 下拉式選單中，選取「illustration_agent」。

11. 使用可用於招募投影片的文字查詢代理：

    互相扶持能夠成就大事！

12. 大約 10 秒後，代理應會回覆生成的提示詞，以及圖像預覽網址。按一下圖像網址即可預覽圖像。預覽完成後按一下瀏覽器的「Back」(返回)，即可返回開發人員使用者介面。

    輸出內容範例

    

    範例圖像

    

13. 請注意，您提供給代理的提示詞並未提及運動、體育場或維護工作，但代理會將您的文字內容和品牌宣傳指南合併為單一提示詞，供圖像生成模型使用。

    探索完基礎代理後，請關閉瀏覽器分頁。

14. 點按 Cloud Shell 終端機窗格，然後按下 CTRL + C 鍵來停止伺服器。

    點按「Check my progress」(確認進度)，確認目標已達成。 探索 ADK 代理。

工作 3：將代理部署為 A2A 伺服器

現在請按照以下步驟，將這個代理部署為遠端 A2A 代理。

1. A2A 代理會提供代理資訊卡，說明其身分和功能。請執行下列指令來建立 agent.json 檔案。

   touch illustration_agent/agent.json

2. 開啟 adk_and_a2a/illustration_agent 目錄中的 agent.json 檔案，然後貼上以下內容：

   { "name": "illustration_agent", "description": "An agent designed to generate branded illustrations for Cymbal Stadiums.", "defaultInputModes": ["text/plain"], "defaultOutputModes": ["application/json"], "skills": [ { "id": "illustrate_text", "name": "Illustrate Text", "description": "Generate an illustration to illustrate the meaning of provided text.", "tags": ["illustration", "image generation"] } ], "url": "https://illustration-agent-{{{project_0.startup_script.project_number|Project Number}}}.{{{project_0.default_region| GCP_LOCATION}}}.run.app/a2a/illustration_agent", "capabilities": {}, "version": "1.0.0" }

3. 儲存檔案。

4. 查看 agent.json 檔案中的 JSON。請注意，這會為代理提供名稱和說明、識別一些技能，並指出可呼叫代理的 url。

   按照本實驗室的指示部署代理後，代理的 url 會建構為 Cloud Run 服務網址。

   雖然名稱與 skills 相似，但這裡保留的 capabilities 參數是用於表示串流等功能。

5. 執行下列指令，在 illustration_agent 目錄中建立 requirements.txt 檔案。

   touch illustration_agent/requirements.txt

6. 選取檔案，並在當中貼上以下內容。

   google-adk==1.8.0 a2a-sdk==0.2.16

7. 儲存檔案。

8. 在下列指令中，您將使用 adk deploy cloud_run 和 --a2a 旗標，將代理部署至 Cloud Run 做為 A2A 伺服器。想進一步瞭解如何將代理部署至 Cloud Run，請搜尋「將 ADK 代理部署至 Cloud Run」實驗室。在這個指令中：

   • --project 和 --region 會定義要部署 Cloud Run 服務的專案和區域
   • --service_name 會定義 Cloud Run 服務的名稱
   • --a2a 旗標表示應以 A2A 代理程式的形式託管代理。這意謂著兩點：
     • 您的代理會由類別包裝，以橋接 ADK 和 A2A 代理：A2aAgentExecutor。這個類別會將 A2A 通訊協定的工作和訊息語言，翻譯成 ADK Runner 的事件語言。
     • 代理資訊卡也會託管在 CLOUD_RUN_URL/a2a/AGENT_NAME/.well-known/agent.json。注意：這個版本的資訊卡即將開放使用，但動態重寫代理網址的功能目前不適用於 Cloud Run，因此我們不會在本實驗室版本中使用這項功能。

   使用下列指令將代理部署至 Cloud Run 做為 A2A 伺服器：

   adk deploy cloud_run \ --project {{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} \ --region {{{project_0.default_region| GCP_LOCATION}}} \ --service_name illustration-agent \ --a2a \ illustration_agent

9. 系統會提示您允許這個容器的未驗證回覆。為了進行實驗室測試，請在 Cloud Shell 終端機中輸入 Y (代表「是」)，然後按下 Return 鍵。

   注意：部署作業約需 5 到 10 分鐘。如果發生 PERMISSION_DENIED 錯誤，請嘗試再次執行上述指令。

   預期的輸出內容：

   您會看到建構 Dockerfile 及部署容器，然後部署服務的相關步驟，接著：

   Service [illustration-agent] revision [illustration-agent-00001-xpp] has been deployed and is serving 100 percent of traffic. Service URL: https://illustration-agent-{{{project_0.startup_script.project_number|Project Number}}}.{{{project_0.default_region| GCP_LOCATION}}}.run.app

   點按「Check my progress」(確認進度)，確認目標已達成。 將代理部署為 A2A 伺服器。

工作 4：允許其他 ADK 代理遠端呼叫這個代理

在這項工作中，您將為第二個 ADK 代理提供識別插畫代理功能的機制，並遠端呼叫該代理。第二個代理負責建立投影片內容。該代理會撰寫標題和幾句內文，然後轉交給插畫代理，以便生成圖片來說明文字。

1. 在 Cloud Shell 終端機執行下列指令，將代理資訊卡 JSON 檔案複製到 adk_and_a2a 目錄，並變更檔案名稱，指出該檔案代表 illustration_agent。

   cp illustration_agent/agent.json illustration-agent-card.json

2. 在 Cloud Shell 編輯器的檔案總管窗格中，前往 adk_and_a2a/slide_content_agent，然後開啟 agent.py 檔案。

   請查看這個代理的指示，瞭解代理會根據使用者提供的投影片建議撰寫標題和內文，然後轉交給 A2A 代理生成投影片。

3. 在「# Agents」標題下方貼上以下程式碼，使用 ADK 的 RemoteA2aAgent 類別新增遠端代理：

   illustration_agent = RemoteA2aAgent( name="illustration_agent", description="Agent that generates illustrations.", agent_card=( "illustration-agent-card.json" ), )

4. 在 root_agent 中新增下列參數，將 illustration_agent 新增為 root_agent 的子代理：

   sub_agents=[illustration_agent]

5. 儲存檔案。

6. 在 Cloud Shell 終端機輸入以下指令，啟動使用者介面：

   cd ~/adk_and_a2a adk web

7. 再次點按終端機輸出內容中的 http://127.0.0.1:8000 連結。

8. 系統會開啟新的瀏覽器分頁，顯示 ADK 開發人員使用者介面。在左側的「Select an agent」(選取代理) 下拉式選單中，選取「slide_content_agent」。

9. 向代理查詢投影片構想：

   製作投影片內容，說明我們優質的訓練課程。

您應該會看到以下的輸出內容：

• slide_content_agent 撰寫的標題和內文
• 呼叫 transfer_to_agent，表示要轉移至 illustration_agent
• illustration_agent 的回覆，內含可點按的新圖像連結

點按「Check my progress」(確認進度)，確認目標已達成。 啟用其他 ADK 代理，以便遠端呼叫代理。

恭喜！

在本實驗室中，您已將 ADK 代理部署為 A2A 伺服器，準備好 JSON 代理資訊卡來說明 A2A 代理的功能，以及讓另一個 ADK 代理讀取已部署 A2A 代理的代理資訊卡，並將其做為子代理使用

Google Cloud 教育訓練與認證

協助您瞭解如何充分運用 Google Cloud 的技術。我們的課程會介紹專業技能和最佳做法，讓您可以快速掌握要領並持續進修。我們提供從基本到進階等級的訓練課程，並有隨選、線上和虛擬課程等選項，方便您抽空參加。認證可協助您驗證及證明自己在 Google Cloud 技術方面的技能和專業知識。

使用手冊上次更新日期：2025 年 10 月 6 日

實驗室上次測試日期：2025 年 10 月 6 日

Copyright 2022 Google LLC 保留所有權利。Google 和 Google 標誌是 Google LLC 的商標，其他公司和產品名稱則有可能是其關聯公司的商標。