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

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

本快速入門導覽課程假設您使用本機 IDE (VS Code、PyCharm 等)，並具備 Python 3.10 以上版本和終端機存取權。代理程式完全在本機上執行，建議用於本機應用程式開發。

此外，請參閱這份 ADK 快速入門指南，其中假設您使用本機 IDE (例如 VS Code、PyCharm 或 IntelliJ IDEA)，並具備 Python 3.9 以上版本或 Java 17 以上版本，以及終端機存取權。這個方法會在您的電腦上完整執行應用程式，建議用於內部開發。

事前準備

操作步驟如下：

設定 Google Cloud 專案

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

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.
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
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 Vertex AI API.
Enable the API
Make sure that you have the following role or roles on the project: Vertex AI User
Check for the roles
1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.

3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.
Grant the roles
1. In the Google Cloud console, go to the IAM page.

   前往 IAM
2. 選取專案。
3. 按一下「授予存取權」。

4. 在「New principals」(新增主體) 欄位中，輸入您的使用者 ID。 這通常是 Google 帳戶的電子郵件地址。

5. 在「Select a role」(選取角色) 清單中，選取角色。
6. 如要授予其他角色，請按一下 「新增其他角色」，然後新增每個其他角色。
7. 按一下 [Save]。

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

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 Vertex AI API.

Enable the API

Make sure that you have the following role or roles on the project: Vertex AI User

Check for the roles

1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.

3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

Grant the roles

1. In the Google Cloud console, go to the IAM page.

   前往 IAM
2. 選取專案。
3. 按一下「授予存取權」。

4. 在「New principals」(新增主體) 欄位中，輸入您的使用者 ID。 這通常是 Google 帳戶的電子郵件地址。

5. 在「Select a role」(選取角色) 清單中，選取角色。
6. 如要授予其他角色，請按一下 「新增其他角色」，然後新增每個其他角色。
7. 按一下 [Save]。

設定憑證

在本機終端機中，設定並驗證 Google Cloud CLI。如果您熟悉 Google AI Studio 中的 Gemini API，請注意，Vertex AI 中的 Gemini API 使用 Identity and Access Management 管理存取權，而非 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. 執行下列指令，啟動開發人員 Web UI。

   adk web
   

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

注意： 如要透過指令列介面執行及測試代理程式，請執行 adk run multi_tool_agent 指令。舉例來說，如果本機沒有網路瀏覽器，這個方法就很有用。

建議提示詞

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

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

後續步驟

• 瞭解代理程式

• 部署至 Agent Engine