使用 Agent Development Kit 在 Agent Runtime 上開發及部署代理

使用 Agent Development Kit 在 Agent Runtime 上開發及部署代理

您可以使用 Agent Runtime 託管透過 Agent Development Kit (ADK) 開發的代理。本文說明如何使用 ADK 建立、部署及測試代理程式。

本快速入門導覽課程會逐步引導您完成下列步驟：

• 設定您的 Google Cloud 專案。
• 安裝 Python 適用的 Agent Platform SDK 和 ADK。
• 開發貨幣兌換代理程式。
• 將代理部署至 Agent Runtime。
• 測試已部署的代理。

您也可以使用下列 ADK 替代快速入門導覽課程：

• ADK 快速入門：ADK 快速入門完全在本機執行，並假設您使用本機 IDE 和終端機存取權。
• Agent Starter Pack：一系列可部署於正式環境的生成式 AI 代理範本，專為 Agent Platform 而建。

如要使用 Agent Development Kit 以外的支援架構，請參閱在 Agent Runtime 上開發及部署代理程式。

事前準備

注意： 您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果沒有這項權限，請要求管理員授予服務用量管理員 (roles/serviceusage.serviceUsageAdmin) 角色。

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform and Cloud Storage APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform and Cloud Storage APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

如要取得使用 Agent Runtime 所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

• Agent Platform 使用者 (roles/aiplatform.user)
• 儲存空間管理員 (roles/storage.admin)

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

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

安裝並初始化 Python 專用的 Agent Platform SDK

1. 執行下列指令，安裝 Agent Platform SDK for Python 和其他必要套件：

   pip install --upgrade --quiet google-cloud-aiplatform[agent_engines,adk]>=1.112

2. 以使用者身分進行驗證

   本機殼層

   執行下列指令：

   gcloud auth application-default login

   Colab

   請執行下列程式碼：

   from google.colab import auth
   
   auth.authenticate_user(project_id="PROJECT_ID")
   

   Cloud Shell

   您無需採取任何動作。

3. 執行下列程式碼，匯入 Agent Platform 並初始化 SDK：

   Google Cloud 專案

   import vertexai
   
   client = vertexai.Client(
       project="PROJECT_ID",               # Your project ID.
       location="LOCATION",                # Your cloud region.
   )
   

   其中：

   • PROJECT_ID 是您開發及部署代理程式的專案 ID Google Cloud

   • LOCATION 是支援的區域。

開發代理

1. 為代理開發貨幣匯率工具：

   def get_exchange_rate(
       currency_from: str = "USD",
       currency_to: str = "EUR",
       currency_date: str = "latest",
   ):
       """Retrieves the exchange rate between two currencies on a specified date."""
       import requests
   
       response = requests.get(
           f"https://api.frankfurter.app/{currency_date}",
           params={"from": currency_from, "to": currency_to},
       )
       return response.json()
   

2. 例項化代理程式：

   from google.adk.agents import Agent
   from vertexai import agent_engines
   
   agent = Agent(
       model="gemini-2.0-flash",
       name='currency_exchange_agent',
       tools=[get_exchange_rate],
   )
   
   app = agent_engines.AdkApp(agent=agent)
   

3. 在本機測試代理：

   注意： 在本機測試 ADK 代理時，系統會使用記憶體內的工作階段。

   async for event in app.async_stream_query(
       user_id="USER_ID",
       message="What is the exchange rate from US dollars to SEK today?",
   ):
       print(event)
   

   其中 USER_ID 是使用者定義的 ID，字元上限為 128 個。

部署代理程式

在 Agent Platform 中建立 reasoningEngine 資源，即可部署代理程式：

注意： 將 ADK 代理部署至 Agent Platform 時，系統會自動產生代管工作階段資源。您可以在清理部分中，連同代理程式一併刪除受管理的工作階段資源。

remote_agent = client.agent_engines.create(
    agent=app,
    config={
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
        "staging_bucket": "STAGING_BUCKET",
        "identity_type": types.IdentityType.AGENT_IDENTITY,
    }
)

其中 STAGING_BUCKET 是以 gs:// 為前置字元的 Cloud Storage bucket。

使用代理

傳送查詢內容，測試已部署的代理：

async for event in remote_agent.async_stream_query(
    user_id="USER_ID",
    message="What is the exchange rate from US dollars to SEK today?",
):
    print(event)

清除所用資源

為了避免系統向您的 Google Cloud 帳戶收取本頁面所用資源的費用，請按照下列步驟操作。

remote_agent.delete(force=True)

後續步驟

指南

Agent Platform Runtime 設定

設定環境以使用 Agent Platform Runtime。

指南

部署代理程式

瞭解如何根據開發需求，在 Agent Platform Runtime 部署代理程式。

指南

管理已部署的代理程式

瞭解如何管理已部署至 Agent Platform 代管執行階段的代理程式。

指南

使用代理

使用 Agent Platform Runtime 執行代理程式。

資源

取得支援

尋找 Google Agent Platform 的相關資源和支援。