第一個 ADK Agent

Google ADK(Agent Development Kit)是 Google 開源的 agent 開發框架。它為 Gemini 最佳化,但不綁模型、也不綁部署方式 —— 你可以把同一段 agent 程式接到 OpenAI 或 Anthropic 的模型上(第 2 課會做),也可以打包成容器丟到任何地方跑。

這一課只做一件事:把最小可用的 agent 寫出來、跑起來。

這一課會學到

• 怎麼建立一個最基本的 ADK agent
• ADK 的四個必要參數各自在做什麼
• agent 的生命週期:輸入 → 處理 → 輸出
• 怎麼用 adk web 把 agent 叫起來測

核心概念:ADK agent 是什麼

一個 ADK agent 是可程式化的 AI 助理,它能:

• 接收使用者的輸入(文字、圖片等)
• 用 AI 模型(例如 Gemini)去理解並回應
• 依照你給的指示執行特定任務
• 回傳結構化或非結構化的結果

可以把它想成一個用 AI 來處理複雜任務的函式。差別在於:普通函式的行為由你寫的程式碼決定,agent 的行為由你寫的指示(instruction)決定。

關鍵元件

LlmAgent 類別

ADK 裡建立 agent 的主要積木:

from google.adk.agents import LlmAgent

四個必要參數

參數	作用
name	agent 的唯一識別名稱
model	要用哪個模型(例如 "gemini-3-flash-preview")
description	這個 agent 是做什麼的
instruction	這個 agent 該怎麼表現

description 與 instruction 常被混為一談,但它們給的對象不同:description 是給別的 agent 看的(多 agent 系統靠它決定要不要把任務交給你,見第 8 課);instruction 是給模型自己看的行為指引。

基本流程

1. 輸入 —— 使用者送出一則訊息
2. 處理 —— agent 用模型去理解並產生回應
3. 輸出 —— agent 回傳結果

這一課要做的東西

一個創意寫作 agent,用來:

• 幫使用者發展故事點子與角色
• 提供寫作提示與靈感
• 協助處理情節結構與節奏
• 示範 ADK 最基本的用法

程式碼

creative_writing_agent/agent.py 的全部內容 —— 沒有省略,一個最小的 ADK agent 就是這麼多:

from google.adk.agents import LlmAgent

# 建立一個創意寫作 agent
root_agent = LlmAgent(
    name="creative_writing_agent",
    model="gemini-3-flash-preview",
    description="A creative writing assistant that helps with stories, poems, and creative content",
    instruction="""
    You are a creative writing assistant.

    Your role is to:
    - Help users develop story ideas
    - Assist with character development
    - Provide writing prompts and inspiration
    - Help with plot structure and pacing
    - Offer feedback on creative writing

    When users want to write creatively:
    - Ask engaging questions to develop ideas
    - Suggest creative elements and themes
    - Help structure stories and narratives
    - Provide constructive feedback

    Keep responses creative, inspiring, and supportive of artistic expression.
    """
)

⚠️ 變數名一定要叫 root_agent。ADK 是靠這個名字去目錄裡找進入點的,改成 agent 或 my_agent 就會找不到 —— 而錯誤訊息不會直接告訴你原因。這是整個 ADK crash course 從頭到尾都要遵守的約定。

專案結構

1_starter_agent/
├── README.md              # 概念說明
├── requirements.txt       # 相依套件
└── creative_writing_agent/
    ├── __init__.py        # 讓它成為 Python package
    └── agent.py           # agent 本體

__init__.py 不能省。ADK 掃描的是 Python package,少了它,agent.py 不會被載入。

跑起來

1. 準備 API key —— 到 Google AI Studio 申請,設成環境變數 GOOGLE_API_KEY。

2. 裝相依套件:

   pip install -r requirements.txt
   

3. 啟動 ADK 的網頁介面:

   adk web
   

   在網頁上選擇 creative_writing_agent。

4. 測試:

   • 要故事點子:「我想寫一個關於魔法森林的故事」
   • 要角色設定:「幫我想一個科幻故事的主角」
   • 要寫作提示:「給我一個創意寫作題目」
   • 問情節建議:「故事的高潮該怎麼安排?」

動手練習

• 把 instruction 整段改掉,換成一個程式碼審查 agent,再問同樣的問題,看行為差多少。
• 把 model 換成別的 Gemini 版本,比較回應速度與品質。
• 把 instruction 縮到只剩一句話,觀察回應變得多發散 —— 這是後面幾課要一直處理的問題。

小提醒

• 從簡單開始:先讓最小版本跑起來,再一層一層加。
• 常常測:adk web 就是為了讓你邊改邊試。
• 指示寫清楚:instruction 寫得含糊,agent 的行為就含糊。

---

內容來源:本頁改寫自 awesome-llm-apps
的 ai_agent_framework_crash_course,原文連結:https://github.com/Shubhamsaboo/awesome-llm-apps/blob/main/ai_agent_framework_crash_course/google_adk_crash_course/1_starter_agent/README.md

Apache License 2.0, Copyright (c) Shubham Saboo。
本頁是碼力獅社群的翻譯與編排:原文為英文,譯成繁體中文,
並把原 repo 放在 .py 範例檔裡的關鍵程式碼折進課文
(原文的 README 只講概念、程式碼另存他處,分開讀會斷掉)。
內容如與原文有出入,以原文為準。完整可執行的範例請直接使用原始 repo。