快速入門導覽課程：使用 Agent Development Kit 建構代理程式

本快速入門導覽課程會逐步引導您設定 Google Cloud 專案、安裝 Agent Development Kit (ADK)、設定基本代理程式，以及執行其開發人員使用者介面。

本快速入門導覽課程假設您使用的是本機 IDE (VS Code、PyCharm 等)，並且有 Python 3.10 以上版本和終端機存取權。代理程式會完全在您的電腦上執行，建議您在本機應用程式開發時使用此方法。

事前準備

操作步驟如下：

設定 Google Cloud 專案

設定 Google Cloud 專案並啟用 Vertex AI API。

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Enable the API

    5.

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

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI API.

    Enable the API

    8.

    設定憑證

    在本機終端機中，設定並驗證 Google Cloud CLI。如果您熟悉 Google AI Studio 中的 Gemini API，請注意，Vertex AI 中的 Gemini API 會使用身分和存取權管理功能，而非 API 金鑰來管理存取權。

    1. 安裝並初始化 Google Cloud CLI。

    2. 如果您先前已安裝 gcloud CLI，請執行這項指令，確保 gcloud 元件已更新。

      gcloud components update

    3. 執行下列指令，產生本機應用程式預設憑證 (ADC) 檔案。代理程式會在本機應用程式開發期間使用這些憑證存取 Vertex AI。

      gcloud auth application-default login

      詳情請參閱「設定應用程式預設憑證」。

    設定虛擬環境並安裝 ADK

    • 建立並啟用虛擬環境 (建議)：

      # Create
python -m venv .venv
# Activate (uncomment the line relevant to your environment)
# macOS/Linux: source .venv/bin/activate
# Windows CMD: .venv\Scripts\activate.bat
# Windows PowerShell: .venv\Scripts\Activate.ps1

    • 安裝 ADK：

      pip install google-adk

    建立虛擬服務專員

    使用終端機建立資料夾結構：

    mkdir multi_tool_agent/
touch \
multi_tool_agent/__init__.py \
multi_tool_agent/agent.py \
multi_tool_agent/.env

    你的結構體：

    parent_folder/
    multi_tool_agent/
        __init__.py
        agent.py
        .env

    複製並貼上以下程式碼到您建立的以下三個檔案中：

    • \_\_init\_\_.py

      from . import agent

    • .env

      # If using Gemini via Vertex AI on Google CLoud
GOOGLE_CLOUD_PROJECT="your-project-id"
GOOGLE_CLOUD_LOCATION="your-location" #e.g. us-central1
GOOGLE_GENAI_USE_VERTEXAI="True"

    • agent.py

      from google.adk.agents import Agent

def get_weather(city: str) -> dict:
    """Retrieves the current weather report for a specified city.

    Returns:
        dict: A dictionary containing the weather information with a 'status' key ('success' or 'error') and a 'report' key with the weather details if successful, or an 'error_message' if an error occurred.
    """
    if city.lower() == "new york":
        return {"status": "success",
                "report": "The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit)."}
    else:
        return {"status": "error",
                "error_message": f"Weather information for '{city}' is not available."}

def get_current_time(city:str) -> dict:
    """Returns the current time in a specified city.

    Args:
        dict: A dictionary containing the current time for a specified city information with a 'status' key ('success' or 'error') and a 'report' key with the current time details in a city if successful, or an 'error_message' if an error occurred.
    """
    import datetime
    from zoneinfo import ZoneInfo

    if city.lower() == "new york":
        tz_identifier = "America/New_York"
    else:
        return {"status": "error",
                "error_message": f"Sorry, I don't have timezone information for {city}."}

    tz = ZoneInfo(tz_identifier)
    now = datetime.datetime.now(tz)
    return {"status": "success",
            "report": f"""The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}"""}

root_agent = Agent(
    name="weather_time_agent",
    model="gemini-2.0-flash",
    description="Agent to answer questions about the time and weather in a city.",
    instruction="I can answer your questions about the time and weather in a city.",
    tools=[get_weather, get_current_time]
)

    這個代理程式配備了兩個函式工具，其中包含模擬實作項目。

    執行及測試服務專員

    1. 在終端機中，前往代理程式的父項目錄 (例如使用 cd ..)：

      parent_folder/      <-- navigate to this directory
    multi_tool_agent/
        __init__.py
        agent.py
        .env

    2. 執行下列指令，啟動開發人員網頁 UI。

      adk web

      在瀏覽器中開啟提供的網址 (通常為 http://localhost:8000 或 http://127.0.0.1:8000)。這個連線會完全保留在本機電腦上。選取 multi_tool_agent 並與服務專員互動。

    試試以下範例提示詞

    您可以嘗試使用以下提示：

    • 紐約的天氣如何？
    • 紐約現在幾點？
    • 巴黎的天氣如何？
    • 巴黎現在幾點？

    後續步驟