使用 Agent Development Kit (ADK) 在 Agent Runtime 開發及部署代理

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

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

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

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

  • ADK 快速入門導覽課程：ADK 快速入門導覽課程完全在您的機器上執行，並假設您使用本機 IDE 和終端機存取權。
  • Agent Starter Pack：專為 Agent Platform 建構的一組生成式 AI 代理範本，可用於正式環境。

如要瞭解如何使用 ADK 以外的支援框架，請參閱「在 Agent Runtime 開發及部署代理」快速入門導覽課程。

事前準備

  1. 登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎 建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

  2. 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.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Agent Platform and Cloud Storage APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  5. 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.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Agent Platform and Cloud Storage APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    8.

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

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

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

安裝並初始化 Agent Platform SDK for Python

  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.
)

    其中：

開發代理

  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-3.5-flash",
    name='currency_exchange_agent',
    tools=[get_exchange_rate],
)

app = agent_engines.AdkApp(agent=agent)

  3. 在本機測試代理：

    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 資源，部署代理：

from vertexai import types

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 代管執行階段的代理。

指南

透過 Agent Platform Runtime 使用代理。

資源

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