Google ADK 開發入門

什麼是 Google Agent Development Kit (ADK)?

Agent Development Kit (ADK) 是一套 Google 推出可模組化開發和部署的 AI Agent，高度整合 Google 生態系，ADK 能讓 Agent 開發感覺像在做軟體開發一樣，讓開發、部署和組織 Agent 變得簡單了，還有就是 Google 說它也有能力介接不同平台的 AI Agent 框架，例如 MCP。

今天文章的重點是跟著 Google ADK get started 範例實做看看，然後順便講講自己的心得。

一起來做個 GET startED 範例

參考文件為 https://google.github.io/adk-docs/get-started/quickstart/#run-your-agent，今天的範例程式我們選擇使用 Python。

1. 準備好 GCP project

因為我們的模型預計會用 Gemini 和最後會部署到 Agent Engine 上，所以需要個 GCP project 來取得相關資源，建立專案步驟可參考此 文章。

2. 選擇喜歡的工具建立 python 環境後用 pip 安裝 ADK

小弟使用 miniconda

conda create -n google-adk-env python=3.12
conda activate google-adk-env
pip install google-adk

3. 建立 Agent 專案

接下來必需建立一個下面這種資料夾結構的專案，

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

__init__.py 的內容如下，

from . import agent

agent.py 的內容如下

import datetime
from zoneinfo import ZoneInfo

from google.adk.agents import Agent


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

    Args:
        city (str): The name of the city for which to retrieve the weather report.

    Returns:
        dict: status and result or error msg.
    """
    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:
        city (str): The name of the city for which to retrieve the current time.

    Returns:
        dict: status and result or error msg.
    """

    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)
    report = (
        f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
    )
    return {"status": "success", "report": report}


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=(
        "You are a helpful agent who can answer user questions about the time and weather in a city."
    ),
    tools=[get_weather, get_current_time],
)

可以看到這個 agent 有 2 個方法可呼叫，若 get_weather 的輸入城市是 New York，則會回覆固定天氣資訊，否則回覆不支援，get_current_time 也是相同概念，整個 Agent 的執行流程如下圖：

4. 設定模型

這裡就是要告知 Agent 如何取得授權讓 Agent 能調用 LLM model，有 3 種權限設定方法：

  1. 在 Google AI Studio 取得 API Key 調用模型。
  2. 使用 gcloud CLI 執行 gcloud auth login 登入後，然後呼叫 Google Cloud Vertex AI API 調用。
  3. 設定 Google Cloud project with Vertex AI Express Mode 後，取得 API Key 調用模型。

方法 1 比較簡單，只要進去 Google AI Studio API 頁面後，點右上角的 Create API key，

選擇專案後就可取得，

然後 將 API Key 寫到 .env 中。

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=PASTE_YOUR_ACTUAL_API_KEY_HERE

5. 啟動 Agent

首先開啟 terminal，然後 cd 到 parent_folder 資料夾，

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

這裡也是有 3 種方式在 local 端測試你的 Agent：

(1) Dev UI (adk web)

直接在 terminal 上執行：

adk web

然後連線至 http://127.0.0.1:8000/dev-ui/ 上進行測試。

首先我們可以問 New York 天氣如何來測試 Agent，

What is the weather in New York?

可以看到 Agent 回覆我們的特定訊息等同於我們在 agent.py 的 get_weather 方法中回覆的相同，

然後點選 get_weather 按鈕後能看到 LLM 跟 Agent 交互的 JSON 內容，ADK 就是方便在把我們在 function 中回覆的 {"status": xxxx, "report": "xxxxx"} 轉成 Agent 溝通時使用的格式。

接下來可以來問看看另一個城市的天氣，

What is the weather in Paris?

得到的回覆也是跟 get_weather function 所回覆的意思相同。

用這個 UI 測試 Agent 真的是非常方便啊！

(2) terminal interactive (adk run)

在 terminal 上執行：

adk run multi_tool_agent

然後你就可以在 terminal 上下 prompt 測試。

(3) API Server (adk api_server)

在 terminal 上執行以下指令啟動 API server，

adk api_server

啟動後可連線至 http://localhost:8000/docs 查看 Agent 幫我們包好的 Swegger，

接下來就可用這些 API 進行 Agent 測試，首先是要建立新的 session，

curl -X POST http://localhost:8000/apps/multi_tool_agent/users/u_123/sessions/s_123 \
  -H "Content-Type: application/json"

然後就可用相同的 session 來下 prompt，

curl -X POST http://localhost:8000/run \
-H "Content-Type: application/json" \
-d '{
"appName": "multi_tool_agent",
"userId": "u_123",
"sessionId": "s_123",
"newMessage": {
    "role": "user",
    "parts": [{
    "text": "Hey whats the weather in new york today"
    }]
}
}'

並成功得到以下的 Json 回覆，list 中由上而下的 3 個元素就是我們先前用 adk web 測試時所看到的 event 2, 3, 4。

[
  {
    "content": {
      "parts": [
        {
          "functionCall": {
            "id": "adk-845a4ab0-e237-47eb-8520-08c62e75b31c",
            "args": {
              "city": "new york"
            },
            "name": "get_weather"
          }
        }
      ],
      "role": "model"
    },
    "usageMetadata": {
      "candidatesTokenCount": 6,
      "candidatesTokensDetails": [
        {
          "modality": "TEXT",
          "tokenCount": 6
        }
      ],
      "promptTokenCount": 180,
      "promptTokensDetails": [
        {
          "modality": "TEXT",
          "tokenCount": 180
        }
      ],
      "totalTokenCount": 186
    },
    "invocationId": "e-c4fe931e-d517-4a55-a32f-d855e8edaef6",
    "author": "weather_time_agent",
    "actions": {
      "stateDelta": {

      },
      "artifactDelta": {

      },
      "requestedAuthConfigs": {

      }
    },
    "longRunningToolIds": [

    ],
    "id": "8493c6e2-7be8-4479-8fa5-137c81e88b50",
    "timestamp": 1753339440.617993
  },
  {
    "content": {
      "parts": [
        {
          "functionResponse": {
            "id": "adk-845a4ab0-e237-47eb-8520-08c62e75b31c",
            "name": "get_weather",
            "response": {
              "status": "success",
              "report": "The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit)."
            }
          }
        }
      ],
      "role": "user"
    },
    "invocationId": "e-c4fe931e-d517-4a55-a32f-d855e8edaef6",
    "author": "weather_time_agent",
    "actions": {
      "stateDelta": {

      },
      "artifactDelta": {

      },
      "requestedAuthConfigs": {

      }
    },
    "id": "05c9b6c1-fa57-4490-a159-5335748d2eba",
    "timestamp": 1753339441.512126
  },
  {
    "content": {
      "parts": [
        {
          "text": "OK. The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit).\n"
        }
      ],
      "role": "model"
    },
    "usageMetadata": {
      "candidatesTokenCount": 25,
      "candidatesTokensDetails": [
        {
          "modality": "TEXT",
          "tokenCount": 25
        }
      ],
      "promptTokenCount": 214,
      "promptTokensDetails": [
        {
          "modality": "TEXT",
          "tokenCount": 214
        }
      ],
      "totalTokenCount": 239
    },
    "invocationId": "e-c4fe931e-d517-4a55-a32f-d855e8edaef6",
    "author": "weather_time_agent",
    "actions": {
      "stateDelta": {

      },
      "artifactDelta": {

      },
      "requestedAuthConfigs": {

      }
    },
    "id": "f193925f-7ceb-44e3-95d1-f1ad86bc1e6b",
    "timestamp": 1753339441.515306
  }
]

部署到 Google Agent Engine

現在 (2025-07-24) 的 Agent 部署很麻煩，要寫 code 部署才行，這裡我們就在 parent_folder 資料夾下新增 deploy.py 和 .env，

parent_folder/      
    multi_tool_agent/
        __init__.py
        agent.py
        .env
    deploy.py              <-- add new python file here
    .env                   <-- add new python file here

這裡的 .env 內容需要 GCP 專案 ID 和部署 Agent 時會用到的 GCS bucket，

GOOGLE_CLOUD_PROJECT=PASTE_YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=us-central1
STAGING_BUCKET=gs://PASTE_YOUR_BUCKET

然後 deploy.py 內容如下：

import os

import vertexai
from dotenv import load_dotenv
from vertexai import agent_engines
from vertexai.preview.reasoning_engines import AdkApp

from multi_tool_agent.agent import root_agent


def init():
    load_dotenv()

    GOOGLE_CLOUD_PROJECT = os.getenv("GOOGLE_CLOUD_PROJECT")
    GOOGLE_CLOUD_LOCATION = os.getenv("GOOGLE_CLOUD_LOCATION")
    STAGING_BUCKET = os.getenv("STAGING_BUCKET")

    vertexai.init(
        project=GOOGLE_CLOUD_PROJECT,
        location=GOOGLE_CLOUD_LOCATION,
        staging_bucket=STAGING_BUCKET,
    )


def deploy():
    print("deploying app...")
    init()

    app = AdkApp(
        agent=root_agent,
        enable_tracing=False,
    )

    print("deploying agent to agent engine:")

    remote_app = agent_engines.create(
        app,
        display_name="weather agent",
        requirements=[
            "google-cloud-aiplatform[adk,agent-engines]==1.88.0",
            "google-adk",
            "python-dotenv",
            "google-auth",
            "tqdm",
            "requests",
            "llama-index",
            "absl-py"
        ],
        extra_packages=[
            "./multi_tool_agent"
        ]
    )

    print(f"Deployed agent to Vertex AI Agent Engine successfully, resource name: {remote_app.resource_name}")


if __name__ == "__main__":
    deploy()

執行完後 Agent 就部署完啦！你可以在 Agent Engine UI 上看到已部署的 Agent，

最後可以參考這篇 文章 進行 Agent 測試。

更多的 Agent

Google 官方有提供一些比較進階的 Agent sample 供工程師參考，這裡我用過的 sample 只有 RAG，雖然它看起來是 Agent 但它的 function 實作是直接調用 Google Rag Engine 來進行增強式檢索，有點偷吃步🤣

結論

這幾天用下來有感覺到 Google ADK 很用心的將開發 Agent 這段工作變得簡單許多，真的就像開發後端那樣，將 function 的商業邏輯寫好，function 說明寫好，其它的都可交給 ADK 搞定，進入門檻變很低，但相對的當你想要做 troubleshooting 時就變得困難許多， 雖說如此還是推薦使用 Google ADK 開發 LLM 用的 Agent。

標籤
tshine73
tshine73
文章: 69

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *