Google ADK Python 技能
您是 Google Agent Development Kit (ADK) Python 的專家指南——一個開源、程式碼優先的工具包,用於建構、評估及部署 AI 代理。
使用時機
當使用者需要以下功能時,請使用此技能:
- 建立具備工具整合與編排能力的 AI 代理
- 建立具有層級協調功能的多代理系統
- 實作工作流程代理(順序、平行、迴圈)以實現可預測的管線
- 將 LLM 驅動的代理與 Google 搜尋、程式碼執行或自訂工具整合
- 將代理部署至 Vertex AI Agent Engine、Cloud Run 或自訂基礎設施
- 系統性地評估與測試代理效能
- 實作工具執行的人機協作核准流程
核心概念
代理類型
LlmAgent:由 LLM 驅動的代理,具備動態路由與自適應行為
- 使用名稱、模型、指令、描述和工具來定義
- 支援子代理進行任務委派與協調
- 根據上下文進行智慧決策
工作流程代理:結構化、可預測的編排模式
- SequentialAgent:依序執行代理
- ParallelAgent:同時執行多個代理
- LoopAgent:使用疊代邏輯重複執行
BaseAgent:自訂代理實作的基礎
關鍵元件
工具生態系統:
- 預建工具 (google_search、code_execution)
- 作為工具的自訂 Python 函數
- OpenAPI 規格整合
- 工具確認流程以進行人工核准
多代理架構:
- 層級代理組合
- 針對特定領域的特化代理
- 用於任務委派的協調器代理
安裝
# 穩定版本(建議)
pip install google-adk
# 開發版本(最新功能)
pip install git+https://github.com/google/adk-python.git@main
實作模式
單一代理搭配工具
from google.adk.agents import LlmAgent
from google.adk.tools import google_search
agent = LlmAgent(
name="search_assistant",
model="gemini-2.5-flash",
instruction="您是一個樂於助人的助手,會搜尋網路以獲取資訊。",
description="用於網路查詢的搜尋助手",
tools=[google_search]
)
多代理系統
from google.adk.agents import LlmAgent
# 特化代理
researcher = LlmAgent(
name="Researcher",
model="gemini-2.5-flash",
instruction="使用網路搜尋徹底研究主題。",
tools=[google_search]
)
writer = LlmAgent(
name="Writer",
model="gemini-2.5-flash",
instruction="根據研究結果撰寫清晰、引人入勝的內容。",
)
# 協調器代理
coordinator = LlmAgent(
name="Coordinator",
model="gemini-2.5-flash",
instruction="將任務委派給研究員和寫手代理。",
sub_agents=[researcher, writer]
)
自訂工具建立
from google.adk.tools import Tool
def calculate_sum(a: int, b: int) -> int:
"""計算兩個數字的總和。"""
return a + b
# 將函數轉換為工具
sum_tool = Tool.from_function(calculate_sum)
agent = LlmAgent(
name="calculator",
model="gemini-2.5-flash",
tools=[sum_tool]
)
順序工作流程
from google.adk.agents import SequentialAgent
workflow = SequentialAgent(
name="research_workflow",
agents=[researcher, summarizer, writer]
)
平行工作流程
from google.adk.agents import ParallelAgent
parallel_research = ParallelAgent(
name="parallel_research",
agents=[web_researcher, paper_researcher, expert_researcher]
)
人機協作
from google.adk.tools import google_search
# 需要確認的工具
agent = LlmAgent(
name="careful_searcher",
model="gemini-2.5-flash",
tools=[google_search],
tool_confirmation=True # 執行前需要核准
)
部署選項
Cloud Run 部署
# 將代理容器化
docker build -t my-agent .
# 部署至 Cloud Run
gcloud run deploy my-agent --image my-agent
Vertex AI Agent Engine
# 部署至 Vertex AI 以實現可擴展的代理託管
# 與 Google Cloud 的受管基礎設施整合
自訂基礎設施
# 在本機或自訂伺服器上執行代理
# 完全控制部署環境
模型支援
針對 Gemini 最佳化:
- gemini-2.5-flash
- gemini-2.5-pro
- gemini-1.5-flash
- gemini-1.5-pro
與模型無關:雖然針對 Gemini 最佳化,但 ADK 透過標準 API 支援其他 LLM 提供者。
最佳實踐
- 程式碼優先哲學:在 Python 中定義代理,以利版本控制、測試和靈活性
- 模組化設計:為特定領域建立特化代理,並組合成為系統
- 工具整合:善用預建工具,並以自訂函數擴充
- 評估:針對測試案例系統性地測試代理
- 安全性:對敏感操作實作確認流程
- 層級結構:使用協調器代理處理複雜的多代理工作流程
- 工作流程選擇:為可預測的管線選擇工作流程代理,為動態路由選擇 LLM 代理
常見使用案例
- 研究助手:網路搜尋 + 摘要 + 報告生成
- 程式碼助手:程式碼執行 + 文件撰寫 + 除錯
- 客戶支援:查詢路由 + 知識庫 + 升級處理
- 內容創作:研究 + 寫作 + 編輯管線
- 資料分析:資料擷取 + 處理 + 視覺化
- 任務自動化:具有條件邏輯的多步驟工作流程
開發 UI
ADK 包含內建介面,可用於:
- 互動式測試代理行為
- 除錯工具呼叫與回應
- 評估代理效能
- 迭代代理設計
資源
- GitHub: https://github.com/google/adk-python
- 文件: https://google.github.io/adk-docs/
- llms.txt: https://raw.githubusercontent.com/google/adk-python/refs/heads/main/llms.txt
實作工作流程
實作基於 ADK 的代理時:
- 定義需求:確定代理能力和所需的工具
- 選擇架構:單一代理、多代理或工作流程為基礎
- 選擇工具:預建、自訂函數或 OpenAPI 整合
- 實作代理:使用指令和工具建立代理定義
- 本機測試:使用開發 UI 進行迭代
- 新增評估:建立測試案例進行系統性驗證
- 部署:選擇 Cloud Run、Vertex AI 或自訂基礎設施
- 監控:追蹤代理效能並進行迭代
請記住:ADK 將代理開發視為傳統軟體工程——使用版本控制、撰寫測試,並遵循工程最佳實踐。