建立具備強大技能的 ADK 代理指南

首页 » 蟒蛇 » 建立具備強大技能的 ADK 代理指南

使用代理開發工具包 (ADK) 建構的智慧代理正迅速成為現代人工智慧應用程式的支柱。這遠遠不止是回答問題的一次性聊天機器人。借助合適的技能係統，這些智能體可以進行推理、規劃、調用工具、與其他智能體協作，甚至循環優化自身工作，同時借助漸進式披露技術控制令牌使用量和延遲。

在本深度指南中，您將逐步了解如何設計、建置和編排具有相應技能的 ADK 代理程式。從基本的單代理到按順序、循環和並行運行的多代理工作流程，您將了解各種實作方式。您還將看到像 Google 的 ADK CodeLabs、社群技能和 AgentKit 2.0 等編排框架這樣的實際技術堆疊如何使用 Router、SequentialAgent、LoopAgent 和 ParallelAgent 等模式，以及像 Q2BSTUDIO 這樣的公司如何將這些模式與雲端平台和網路安全模式結合，從而交付可用於生產環境的系統。

為什麼具備技能的 ADK 代理程式對現代軟體團隊至關重要

人工智慧在軟體開發領域的爆炸性成長，促使團隊尋求將專業知識和工作流程封裝成可重複使用、可組合單元的方法。ADK 滿足了這一需求，它允許您將行為、領域規則和工具打包到代理中，這些代理可以在專案、團隊甚至產品中重複使用。

這種方法的核心是代理技能。這些是獨立的知識模組，代理可以按需加載。技能不會將所有指南和規則一股腦地塞進一個龐大的提示框中，而是應用了… 漸進披露 架構：指令、資源和腳本僅在需要時顯示，即使安裝了數百個技能，也能保持上下文簡潔和效能高。

在代幣預算、延遲和計算成本都受到嚴格限制的今天，這種效率至關重要。將所有樣式指南、API規格和操作規則都載入到單一提示符號中是不可擴充的。技能功能可讓您將「冷知識」保存在磁碟（或儲存庫）中，並僅在特定功能相關時才將其引入代理的上下文中。

Q2BSTUDIO 等公司利用這種模型為企業建構客製化的 AI 系統。它將商業智慧、領域知識和現代網路安全實踐融為一體。這樣，代理不僅能力出眾、具備上下文感知能力，還能抵禦當今威脅情勢下常見的攻擊手段。

了解 ADK 技能的漸進式揭露架構

ADK 風格的技能通常遵循三層加載模型，使智能體始終專注於上下文。 同時，在需要時仍允許進行深度領域專業化。您可以將其視為分階段的知識傳遞管道：

第一級 – 探索對話開始時，智能體只能看到可用技能的目錄：技能名稱和簡短描述。此時尚未載入任何複雜資料。這些資訊足以讓智能體判斷哪個技能可能與使用者的請求相關。

第二級 – 說明一旦技能被判定為匹配，智能體就會讀取其資訊。 SKILL.md 或同等效力的指導文件。該文件提供該技能的詳細指導、模式和規則，僅在必要時才將其引入模型上下文中。

三級 – 資源大型資源（例如大型模式、冗長的清單、腳本或擴充文件）將作為引用保留在檔案系統中。

並按需檢索 只有當技能明確指向它們時才會如此。代理程式會根據需要讀取或執行這些資源，而不是始終將它們顯示在主提示中。

這種模式是 AgentKit 2.0 和基於 Antigravity 的設定等框架的核心。您可以使用諸如以下命令將技能直接安裝到相容的代理（例如 Claude Code、Cursor、Antigravity 等）中： npx add-skill vercel-labs/agent-skills它會克隆技能庫，將它們放入正確的目錄中，並使它們無需手動編輯提示即可被發現。

用於建立 ADK 技能的設計模式

從零開始寫一項新技能，往往不在於工具，而是內容設計。ADK 規範通常會告訴你如何組織軟體包（YAML 格式的 frontmatter， references/, assets/, scripts/ 它會告訴你如何定義目錄等等，但它不會告訴你如何寫實際的指令。這時，可重複使用設計模式就派上用場了。

掌握了數十種技能的從業人員表示，少數幾種結構模式就能涵蓋大多數實際應用場景。其中五種最實用：

工具包裝器這種模式將特定庫或平台的慣例和最佳實踐封裝成一項技能。說明部分描述了需要遵循的規則，而 references/ 包含官方文件。通常沒有範本或腳本；關鍵在於為代理提供一個類似 FastAPI、React 或 Postgres 這類工具的「心智模型」。

發電機在這裡，該技能使用儲存在模板中的模板來產生一致的結構化輸出。 assets/例如，API 文件、提交資訊、技術報告或變更日誌都屬於範本範疇。指令定義了品質規則，而範本定義了輸出格式，因此每次都能獲得內容不同的可重複格式。

評論家這種模式分隔開來 什麼 核實 如何 進行檢查。檢查清單文件 references/ 它列出了需要驗證的項目（安全性、風格、架構等），而說明則定義了審查流程：按嚴重程度對發現的問題進行分組、要求提供理由、提出修復建議。替換清單文件，就相當於獲得了一個全新的審查員，而無需重寫技能。

訪談（倒置）此技能並非立即採取行動，而是先透過分階段的結構化問題與使用者溝通，並設定諸如「所有階段完成後才能開始建置」之類的限制條件。這可以防止智能體做出過大的假設，並迫使其在產生詳細輸出之前明確目標和約束條件。

管道此模式可對多步驟工作流程進行編碼，並在各個步驟之間設定明確的門控，例如「使用者確認後才能進入步驟 3」。它比其他模式更複雜，但也是唯一能夠可靠地防止代理程式跳過驗證階段的模式。管線技能可以將審核員步驟、產生器輸出或訪談階段整合到同一流程中。

來自 Google、Vercel 和 Supabase 的實際技能通常會結合兩種或多種此類模式來完成一項技能例如，治理技能可以詢問使用者有關專案限制的問題，然後使用不同的檢查清單來執行審查流程，並使用範本驅動的生成器產生治理報告。

使用 ADK 從單智能體到多智能體系統

一旦你了解了技能是如何打包知識的，下一步就是了解 ADK 代理如何在工作流程中協調這些知識。Google 官方 ADK 程式碼實驗室是一個很好的參考資料：它們從基本的單一代理開始，逐步引導你了解工具、記憶體和多代理協調，所有這些都在實用的 Colab 筆記本中完成。

旅程始於你用 Runner 創造的第一個代理程式。在代碼實驗室中，你定義了一個 day_trip_agent 其使命是根據用戶偏好和預算制定一日遊行程。 ADK 的一般交互作用模型由以下三個部分組成：

中介 「大腦」由其指令、底層模型（例如 Gemini）以及它可以調用的工具來定義。在本例中，智能體擁有詳細的指導方針，並且可以存取 Google 搜尋。

會議 它充當對話記憶庫，保存用戶訊息和代理回應的完整歷史記錄。重複使用同一個會話物件可以確保跨回合的上下文保持關聯。

奔跑 透過接收代理和會話來協調執行，處理每個使用者查詢並返回答案。

同時不斷更新會話類似這樣的實用助手 run_agent_query() 封裝此循環，以便您可以透過測試或 UI 整合輕鬆觸發代理程式。

閱讀這第一個例子，就能看出好的說明是如何直接與使用者提示連結起來的。測試查詢可能會要求進行一次「經濟實惠」且「輕鬆」的一日遊，由於說明強調要注重成本，因此代理商會可靠地將預算考慮因素融入其答案中。

將自訂工具連接到您的 ADK 代理

當代理程式能夠呼叫您自己的 API 和內部服務，而不僅僅是像網路搜尋這樣的通用工具時，它們才能真正發揮強大的作用。ADK 透過將普通函數根據其簽章和文件字串轉換為工具，使此過程變得簡單。

在程式碼實驗室中，一個簡單的範例使用了一個呼叫即時天氣 API 的 Python 函數。類似這樣的函數 get_live_weather_forecast(location: str) 從公共氣象服務機構獲取當前數據，並以字典形式返回結構化訊息，例如溫度和天氣狀況。

關鍵部分是文檔字串。ADK 會解析函數的文件字串，以了解該工具的功能、參數需求和傳回值。語言模型會讀取這些描述，並在推理過程中決定何時以及如何呼叫工具。

要將該工具整合到代理中，只需在初始化期間將其作為工具清單的一部分傳遞即可。，例如 tools=[get_live_weather_forecast]. 的說明 weather_agent 然後可以明確地告訴模型在提出戶外活動建議之前呼叫此工具。

在測試過程中，諸如「我想在太浩湖附近徒步旅行，那裡的天氣怎麼樣？」之類的提示會直接觸發該工具。因為代理的任務和指示要求在推薦方案之前必須使用即時天氣預報。這種模式可以推廣到您自己的 API：庫存、定價、CRM、分析或任何您可以封裝成函數的後端。

將代理視為工具的模式：建立專家團隊

ADK 鼓勵您創建由小型專家組成的團隊，而不是將所有職責塞進一個單一的、龐大的代理程式中。關鍵在於「代理即工具」模式，即一個代理可以像呼叫另一個工具一樣呼叫另一個代理。

程式設計實驗室的一個典型演示是建立一個分層旅行規劃系統。:

專業代理 處理狹窄領域：a food_critic_agent 那隻會推薦餐廳， db_agent 查詢飯店數據，以及 concierge_agent 它在使用者互動中扮演著禮貌助手的角色。

禮賓部本身就把美食評論家當作工具。，將餐廳選擇權交給評論家，然後用更通俗易懂的語言重新表達結果。

頂層是一個協調代理，例如 trip_data_concierge_agent其職責是理解使用者的整體請求，並透過專門的包裝函數（例如）決定要呼叫哪個專家。 call_db_agent 以及 call_concierge_agent.

當你執行類似「幫我找一家飯店和附近的餐廳」這樣的查詢時工具日誌顯示了一條委託鏈：編排器調用數據庫代理獲取酒店信息，然後調用禮賓代理獲取餐廳建議，禮賓代理再調用美食評論家。每個代理都專注於各自的領域，而編排器則負責組合安排。

這種方法與 AgentKit 2.0 建構其 16 個專用代理程式的方式非常契合。 涵蓋前端、後端、安全、測試和基礎設施。每個代理程式都具備特定領域的技能（React 最佳實踐、資料庫設定、安全審計、部署流程等等），而協調器則將它們組合起來，以實現諸如「建置和部署使用者身份驗證模組」之類的更大目標。

賦予代理記憶：會話和自適應規劃

要真正顯得聰明，智能體必須記住多個回合的上下文。根據回饋調整計劃，而不是把每個訊息都當作全新的開始。這就是會議和記憶管理發揮作用的地方。

在 ADK 程式碼實驗室中，一個多日行程規劃代理人示範了正確記憶和錯誤記憶之間的差異。類似這樣的函數 create_multi_day_trip_agent() 設定一個代理人，其指令強調逐步規劃、記住選擇並認真對待糾正措施。

自適應演示會在多個回合中重複使用單一會話物件。:

打開1用戶要求制定為期兩天的旅行計劃，代理商建議第一天的活動。

打開2用戶表示他們對城堡不感興趣。由於會話中保留了先前的行程安排，代理商知道需要調整哪一部分，並在保持其他細節不變的情況下，為該部分提供替代方案。

打開3使用者確認更改並詢問下一步操作，因此代理在了解所有先前上下文的情況下繼續進行第二天的計劃。

對比鮮明的「失敗」演示為每一輪都創造了一個全新的會話。代理商正確回答了第一個問題，但當用戶稍後提到「第 2 天」時，新的會話沒有歷史記錄，代理基本上失憶了，無法將請求與先前的計劃聯繫起來。

結論簡單卻至關重要：持續對話需要持續溝通。對於生產系統，您需要在 API 呼叫、裝置甚至有時是使用者之間持久化和檢索會話狀態，尤其是在工作流程跨越數天或數週的情況下。

路由代理：將查詢定向到適當的專家

隨著您的代理商和技能庫不斷擴大，您需要一種機制將每個收到的請求分配給合適的專家。這就是路由器代理的工作，它是多代理架構中一個雖小但至關重要的元件。

路由器的主要職責是進行分類，而不是直接回答使用者問題。它的指令通常是讀取使用者查詢，並僅輸出最適合該任務的代理（或工作流程）的名稱。

在程式碼實驗室的多智能體部分，路由器會在不同的域智能體之間進行選擇。 例如一日遊規劃師、美食顧問或交通顧問。執行函數首先向路由系統請求路線，然後使用簡單的條件邏輯，根據路由系統的回答呼叫對應的專家。

這種模式與 AgentKit 2.0 中對多代理編排的描述一致。在那裡，協調代理接收一個高級目標，將模式設計委託給資料庫代理，將表單鷹架委託給前端代理，運行安全審查，然後移交給部署代理，最後將差異和 URL 聚合為用戶一致的摘要。

SequentialAgent：協調有序的多步驟工作流程

有些任務自然分解成若干有序階段，每個階段的產出都會為下一個階段提供資訊。例如，「在帕洛阿爾托找到最好的壽司，然後告訴我如何到達那裡」顯然首先需要一個發現步驟，然後需要一個導航步驟。

ADK 提供了一個專門的工作流程代理，通常稱為 SequentialAgent為了清楚地管理這些鏈條與其手動編寫編排邏輯，不如定義子代理程式清單和共享狀態鍵，框架會負責排序和資料傳遞。

在程式碼實驗室範例中，美食家代理人被重構為在某種情況下發出其結果。 output_key 点讚 "destination"運送代理人的指示中會包含一個佔位符，例如： {destination} ADK 會自動使用共用狀態中儲存的值填入該值。

整體工作流程代理，例如 find_and_navigate_agent，配置為 SequentialAgent 子代理人依固定順序 点讚 [foodie_agent, transportation_agent]被呼叫時，從呼叫者的角度來看，它就像一個單獨的代理，同時在內部協調這兩個步驟並管理共享狀態。

這種方法大大簡化了編排程式碼。條件樹和暫存資料連線方式消失了，取而代之的是子代理程式和鍵的宣告式定義。這也使得工作流程更易於測試和擴展，因為每個子代理程式都保持模組化，可以在其他鏈中重複使用。

LoopAgent：帶有規劃器、評論器和改進器的迭代改進器

許多現實世界的問題透過迭代改進而非一次性解決更為有效。想想看，制定計劃、審查計劃、完善計劃，然後反覆進行，直到達到某個品質標準。循環工作流程正是為了滿足這種需求而發展出來的。

ADKs 透過以下方式捕捉此模式 LoopAgent一個工作流程代理，它會重複執行一系列子代理，直到觸發退出條件為止。這對於需要根據正式標準進行自我審查和修正自身輸出的「完美主義」智能體來說是理想的選擇。

一個經典的循環設定包含三個角色：一個規劃代理，產生一個初始計劃；一個評論代理，根據約束條件評估該計劃；以及一個改進代理，根據評論代理的反饋意見編輯或重寫該計劃。

循環定義將這些角色連結成一個循環，並設定最大迭代次數。 例如，為了避免無限循環。 max_iterations=3每次迭代，評論者都會決定該方案是否可以接受；如果不行，改進者會產生一個修改後的版本，然後循環繼續。

退出循環通常需要用到專門的工具。如 exit_loop當評論者的評估結果為正面時，最佳化器會呼叫此函數。此時，最終驗證後的計劃將返回給用戶或傳遞給下游代理。

這種模式在架構設計、安全審查或內容創作等領域尤其有用。其中，一次性的答案很少能達到理想狀態，而內建的批評循環可以大幅提高平均品質。

ParallelAgent：利用並發子代理程式加速工作

當使用者請求的不同部分相互獨立時，按順序執行它們會浪費時間。例如，「今晚找個博物館、一場音樂會和一家很棒的餐廳」這樣的搜尋不需要每次搜尋都等待其他搜尋完成。

並行工作流程透過同時啟動多個專家來解決這個問題。在 ADK 中， ParallelAgent 同時運行一系列子代理，然後透過共享狀態和最終合成步驟合併它們的結果。

典型的設定定義了三個特定領域的代理。 点讚 museum_finder, concert_finder 以及 restaurant_finder，每個都有自己的 output_key 在共享狀態下，並行代理並行執行所有三個代理的操作，因此總時間接近最慢的單一代理的操作時間，而不是三個代理操作時間的總和。

這些代理完成後，合成代理會讀取佔位符，例如： {museum_result}, {concert_result} 以及 {restaurant_result} 從共享狀態然後，將這三個訊息線索融合起來，形成一個連貫、易懂的答案。

這種模式與 AgentKit 2.0 編排流程中所述的「並行執行」優勢相呼應。獨立的子代理同時交付他們的工作，透過各自的技能相互隔離，因此不會互相干擾，而協調器則保持整體的容錯性和可審計性。

AgentKit 2.0、社群技能與模組化代理商編排

AgentKit 2.0 在實務上展示了成熟的 ADK 技能和代理生態系統是什麼樣子。它配備了 16 個專業代理，涵蓋前端、後端、安全、測試和基礎設施，每個代理都預先配備了領域技能，因此可以自主處理複雜的子任務。

開箱即用，內建超過 40 項領域特定技能。涵蓋身份驗證流程、資料庫配置、即時部署和效能監控等常見領域。這些恰恰是現代技術棧中通常最耗費工程時間的部分。

此外，更廣泛的社區貢獻了超過1,000項維護技能。結合 Agent MD 等框架，這些技能使代理程式能夠解釋詳細的操作規則，並在大型、複雜的程式碼庫和多層部署中一致地應用這些規則。

其核心理念為模組化、代理驅動開發。與其讓一個超級代理商試圖包辦一切，不如組建一支由特定領域專家組成的團隊並進行協調。每個代理人只加載其領域所需的技能，這與技能層級使用的漸進式資訊揭露模型一致。

典型的編曲流程遵循清晰的模式編排代理程式接收一個頂級目標，將資料庫設計交給資料庫代理程式（運用模式識別技能），將使用者介面框架傳送給前端代理程式（運用 React 最佳實務技能），運行安全代理程式進行審計，最後請求部署代理程式將程式碼推送到 InForge 等基礎架構。在整個過程中，編排代理會收集結果，在必要時重試失敗的步驟，並記錄互動以供審計。

這種架構不僅提高了效能和可靠性，還能隨著社群技能成長到數千人而擴展。你不再需要一個「無所不知」的代理人；相反，你依靠的是一個由每個成員組成的團隊，每個成員都在自己的技能範圍內保持敏銳。

實作操作：在 macOS、Linux 和 Windows 上本機執行 ADK Web 代理

當你在自己的機器上啟動一個真正的基於 ADK 的代理程式時，所有這些概念都會變得更加清晰。範例儲存庫中提供的 ADK Web 設定可讓您在本機上執行一日遊規劃代理，並具有簡單的 Web 介面。

在開始之前，你需要準備一些先決條件。需要 Python 3.8 或更高版本（建議 3.9+）、Google AI Studio API 金鑰和網際網路連線。對於較新的 Python 版本，您可以安裝 google-adk==1.5.0而 Python 3.8 使用者則應使用相容版本，例如 google-adk==0.3.0.

macOS 和 Linux 的基本流程始於複製儲存庫並設定虛擬環境。。運行後 git clone 以及 cd 在專案中，您可以執行類似這樣的自動腳本： ./setup_venv.sh （在授予執行權限後）或手動建立並啟動虛擬環境 python3 -m venv .adk_env 以及 source .adk_env/bin/activate， 其次是 pip install -r requirements.txt.

一個重要的步驟是透過以下方式設定環境變數： .env 文件中 agent/ 目錄您創建此文件，在編輯器中打開它，並添加如下行： GOOGLE_GENAI_USE_VERTEXAI=FALSE 以及 GOOGLE_API_KEY=your_actual_api_key_here請將佔位符替換為您的真實 API 金鑰。跳過此步驟將導致代理無法呼叫底層模型。

環境啟動後，只需運行即可 adk web 啟動本機 Web 介面終端機會顯示一個網址，通常 http://localhost:8000您可以在那裡打開瀏覽器，選擇 agent 從下拉式選單中選擇該選項，即可開始與一日遊規劃師聊天。聊天結束後，您可以使用該選項停用虛擬環境。 deactivate 命令。

Windows 使用者在使用命令提示字元或 PowerShell 時也遵循非常相似的模式。複製倉庫並切換到該倉庫後，您可以執行一個便利腳本，例如： setup_venv.bat 或手動建立虛擬環境 python -m venv .adk_env 並通過以下方式激活它 .adk_env\Scripts\activate 在命令提示字元中或 .adk_env\Scripts\Activate.ps1 在 PowerShell 中。

这 .env Windows 系統上的檔案位於相同位置。 agent\ 目錄例如，用以下方式建立 type nul > agent\.env 並使用記事本進行編輯。然後，新增相同的鍵值對來配置 Google AI 存取權限。如果在 PowerShell 中遇到執行策略問題，可以使用類似這樣的指令： Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 為本地腳本解析它們。

安裝依賴項並配置環境變數後，執行 adk web 為您提供相同的基於瀏覽器的代理體驗 在 Windows、macOS 或 Linux 系統上，都可以隨時使用下列指令停用該環境： deactivate.

綜合所有因素，具備技能的 ADK 代理、漸進式揭露和多代理編排功能，為建立可擴展、安全且高度專業化的 AI 系統提供了一種強大的方法。 與實際軟體工作流程相契合。透過使用可靠的設計模式建立技能，將代理與您自己的工具和 API 連接起來，利用路由、順序、循環和平行代理，並在本地或雲端運行設置，團隊可以從簡單的聊天機器人過渡到強大的 AI 協作工具，與開發人員、分析師和維運人員在日常工作中並肩工作。