google/adk-js：用 TypeScript 把 agent 寫成可版控的程式碼
An open-source, code-first Typescript toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.
秒懂
- 它是什麼？
- ADK for TypeScript 把 agent 的行為、工具與多 agent 編排全部收進程式碼，並附帶 CLI 與開發用 Web UI。它適合已經在 Node.js 生態裡、想要型別安全與本地除錯流程的團隊；但它的工具生態與模型預設明顯偏向 Google 自家服務。
- 適合誰用？
- 如果你已經在 Node.js 20.19 以上的環境工作，而且接受以 Google 的模型與工具為主要路徑，ADK for TypeScript 值得先在一個 agent 上做原型：用 npx @google/adk-devtools run agent.ts 跑起來，再用 adk web 看工具呼叫的軌跡。若你的工具鏈綁定其他供應商，或需要瀏覽器端執行但無法接受打包體積與金鑰暴露的風險，先不要投入。
- 可以商用嗎？
- 可以。Apache-2.0 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫在最近一天內有新的提交。
- 用什麼語言寫的？
- 主要是 TypeScript（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
ADK for TypeScript 想解決的是 agent 邏輯散落的問題
多數人第一次寫 agent，是把提示詞、工具定義與流程控制塞進一份設定檔或一段腳本。等到要加第二個工具、第二個 agent，或是要重現某次失敗的對話時，才發現沒有任何東西可以 diff、可以 code review、可以回滾。ADK for TypeScript 的定位就是把這些東西拉回程式碼：README 的敘述是「Define agent behavior, orchestration, and tool use directly in code, enabling robust debugging, versioning, and deployment anywhere」。
目標讀者寫得很清楚。這是給已經在 Node.js 或瀏覽器生態裡工作的 TypeScript 開發者，尤其是那些在意型別推斷與 schema 驗證的人。README 明講工具參數支援 Zod v3 與 v4 schema，並具備編譯期型別推斷。換句話說，工具的輸入不是一段自由文字描述，而是一個可以被 tsc 檢查的結構。
另一個容易被忽略的賣點是執行環境。這個套件同時提供 ESM、CommonJS 與 web bundle，agent 可以跑在 Node.js，也可以直接在瀏覽器裡跑。這件事對做內部工具或 demo 的人有用，因為你不必先架一台後端才能驗證 agent 行為。
LlmAgent 是入口，工具與編排才是主體
README 給的最小範例只有一個檔案 agent.ts，從 @google/adk 匯入 LlmAgent 與 GOOGLE_SEARCH，然後匯出一個名為 rootAgent 的常數。這個命名不是隨意的：CLI 要靠它找到進入點。
LlmAgent 的建構參數包含 name、description、model、instruction 與 tools。model 在這個範例裡是字串 'gemini-flash-latest'，instruction 是一段自然語言指令，tools 則是一個陣列，範例中放的是 GOOGLE_SEARCH 這個內建工具常數。整個 agent 的定義因此是一個普通的物件實例，可以被 import、被測試、被放進版控。
編排層面，README 列出 sequential、parallel、loop 與 routed 四種組合方式，並提到可以透過 A2A 協定把工作委派給遠端 agent。這裡值得注意的設計取向：ADK 沒有把多 agent 協作包成一個黑盒，而是把順序、並行、迴圈、路由當成可組合的結構。對需要除錯的人來說這是優點，因為出錯時你能指出是哪一層的哪一個節點。對只想快速串起兩個 agent 的人來說，這也意味著要自己決定拓樸。
工具生態方面，README 列出 Google Search、Google Maps、Vertex AI Search 與 URL context 四種內建工具，另外可以連接 MCP server、把任意函式包成工具，或加入程式碼執行。這個清單的組成值得直說：內建項目幾乎都指向 Google 自家服務。MCP 與函式包裝是通用出口，但預設路徑是 Google 的。
安裝與啟動：兩個套件、一個環境變數、三個 CLI 指令
前置條件寫得很明確：Node.js 20.19 或更新版本。安裝分成兩塊，核心 SDK 與開發工具分開：
npm install @google/adk npm install -D @google/adk-devtools
yarn 的版本是把 add 換掉，其餘相同。把 devtools 放在 devDependency 是合理的，因為 CLI 與 Web UI 只在開發階段需要。
認證有兩條路。走 Google AI Studio 的話，把金鑰寫進 agent 旁邊的 .env：
echo "GOOGLE_GENAI_API_KEY=your-api-key-here" > .env
走 Vertex AI 的話，README 說改用 GOOGLE_GENAI_USE_VERTEXAI=1、GOOGLE_CLOUD_PROJECT 與 GOOGLE_CLOUD_LOCATION 三個環境變數取代 API key，並用 gcloud auth application-default login 完成認證。
執行階段有三個指令。互動式命令列是 npx @google/adk-devtools run agent.ts，Web UI 是 npx @google/adk-devtools web，部署則是 adk deploy cloud_run。README 另外提到 adk create 用於 scaffold。
這裡有一個很容易踩的坑，而且 README 特別用警示框寫出來：永遠要帶上完整的套件名稱。如果 @google/adk-devtools 沒有安裝，直接打 npx adk 會靜默地從公開 registry 下載並執行一個無關的 adk 套件。這不是理論風險，是 npx 的既有行為，而 README 選擇把它寫進文件，說明確實有人中招。
瀏覽器可執行是特色，也是要自己承擔的邊界
README 把瀏覽器支援列為主要特色之一，並說這個套件提供 web bundle。對做內部展示或需要在前端即時互動的場景，這省掉一層後端。
但文件沒有交代瀏覽器情境下的認證安排。你不可能把 GOOGLE_GENAI_API_KEY 放進前端 bundle 而不暴露它，而 README 的認證章節只給了 .env 與 Vertex AI 兩條伺服器端路徑，沒有提到任何代理層或權杖交換機制。這代表瀏覽器支援在文件層面是「可以執行」，至於「怎麼安全地執行」，材料裡沒有答案。如果你的用途是公開網站，這一點必須先自己驗證，不能靠 README 的敘述推論。
同樣地，README 對 ESM、CommonJS 與 web 三種 bundle 只給了存在性描述，沒有提到各自的體積或 tree-shaking 效果。對前端專案來說，打包後的大小是採用與否的關鍵數字之一，而這個數字在提供的材料裡找不到。
工具生態的預設方向決定了它的適用範圍
內建工具是 Google Search、Google Maps、Vertex AI Search、URL context。這四個項目裡有三個直接綁定 Google 的服務，第四個是通用的網頁抓取。如果你的 agent 主要工作是查 Google 生態裡的資料，這個預設組合省下大量接線工作。
反過來說，如果你的工具鏈圍繞其他供應商，你實際會用到的是「把任意函式包成工具」與 MCP server 這兩條通用路徑，內建工具清單對你幾乎沒有價值。這時候要問的問題是：ADK 在通用路徑上提供了什麼其他框架沒有的東西？從材料能看到的答案是型別安全與編排原語，而不是工具數量。
A2A 協定的支援也值得放在這個脈絡裡看。README 說可以「Delegate to remote agents via the A2A protocol」，這意味著跨程序、甚至跨團隊的 agent 協作是被納入設計的。但材料沒有提供 A2A 的設定範例或程式碼片段，所以實際要寫多少程式才能接上，從現有資訊無法判斷。
一個務實的判斷方式：先確認你的工具呼叫裡有多少比例落在內建清單上。比例高的話，ADK 的預設值就是你的加速器；比例低的話，你買到的是編排與型別，其餘要自己來。
替代路線：LangGraph.js 的圖與 ADK 的程式碼優先
在 TypeScript 的 agent 框架裡，LangGraph.js 是最直接可以拿來對照的選項。兩者都支援多 agent 編排，差別在於抽象的位置。
LangGraph.js 把工作流表達成一張圖：節點是步驟，邊是轉移，狀態在圖上流動。這種做法的好處是流程本身是一個資料結構，可以被視覺化、可以被檢查，條件分支與迴圈在圖上是一等公民。代價是你需要先接受圖這個心智模型，並且把邏輯拆成節點與邊。
ADK 走的是另一條路。從 README 的範例看，agent 就是一個 LlmAgent 實例，編排是 sequential、parallel、loop、routed 這些組合方式，全部寫在 TypeScript 裡。你得到的是普通的控制流：if、for、函式呼叫，以及 tsc 的檢查。熟悉 TypeScript 的人幾乎沒有學習曲線，但流程的整體形狀不會自動變成一張可以畫出來的圖。
這個差異會影響除錯方式。圖框架可以在執行前檢查拓樸，程式碼優先的框架則要靠執行時的軌跡。ADK 對此的答案是 adk web 這個開發 UI，README 的截圖標題是 function call，說明它會呈現工具呼叫的過程。這是一個合理的補償，但它是事後觀察，不是事前驗證。
選哪一邊，取決於你的流程是否複雜到需要先看見全貌。三個 agent 以內的順序流程，程式碼優先更直接。分支與迴圈交錯、需要反覆調整拓樸的場景，圖的形式會更省力。
版本節奏、授權與維護成本
授權是 Apache-2.0，README 與 badge 一致。這是一個寬鬆授權，允許商業使用與修改，並附帶專利授權條款。實際使用前仍應自行閱讀 LICENSE 全文，這裡不做法律判斷。
版本方面，最近的 release 有三個，分別對應 main、integrations 與 devtools 三個發佈線，版本號都是 v2.0.0，時間集中在 2026 年 8 月 21 日。這代表專案把核心、整合與開發工具拆成獨立的發佈單元，可以各自推進。對使用者的實際影響是：@google/adk 與 @google/adk-devtools 的版本可能不同步，升級時要分別確認。
維護成本有幾塊要算進去。第一是 Node.js 版本門檻 20.19，這會排除掉還在舊 LTS 的環境。第二是模型名稱寫在程式碼裡，範例用的是 'gemini-flash-latest'，這種帶 latest 的別名會隨時間指向不同模型，行為可能在你沒有改任何程式碼的情況下改變。要穩定就得換成具體版本號，但那需要你自己去查有哪些版本可用，材料裡沒有提供。第三是認證方式的切換，從 API key 換到 Vertex AI 涉及三個環境變數與一次 gcloud 登入，在 CI 環境裡要另外安排。
部署方面，README 只提到 adk deploy cloud_run 這一個目標。如果你的基礎設施不在 Cloud Run，這個指令幫不上忙，你得自己把 agent 包成服務。這不是缺點，只是範圍界線，但要在採用前就認清。
編輯結論
如果你已經在 Node.js 20.19 以上的環境工作，而且接受以 Google 的模型與工具為主要路徑，ADK for TypeScript 值得先在一個 agent 上做原型：用 npx @google/adk-devtools run agent.ts 跑起來，再用 adk web 看工具呼叫的軌跡。若你的工具鏈綁定其他供應商，或需要瀏覽器端執行但無法接受打包體積與金鑰暴露的風險，先不要投入。動手前務必確認三件事：Node 版本是否達到 20.19、npx 是否明確帶上 @google/adk-devtools 這個套件名、以及你的部署目標是否在 adk deploy cloud_run 的涵蓋範圍內。
社群筆記