google/adk-js 评估：把 Agent 编排写回 TypeScript 代码里
An open-source, code-first Typescript toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.
秒懂
- 它是什么？
- ADK 的 TypeScript 版本把 Agent 定义、工具绑定和多 Agent 编排都放进代码，用 Zod 做参数校验，并提供 adk run、adk web、adk deploy cloud_run 三条 CLI 路径。本文只看仓库与 README 能确认的部分，同时指出它的边界。
- 适合谁用？
- 适合已经用 TypeScript 写业务、希望 Agent 定义与工具签名都受编译器约束、并且接受把运行时绑在 Google 模型与 Vertex AI 上的团队。不适合只想用任意模型做一次性原型、或者不愿意引入 Node.js 20.19 以上运行时约束的项目。
- 能商用吗？
- 可以。Apache-2.0 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库在最近一天内有新的提交。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它要解决的是 Agent 定义散落在配置里的问题
多数 Agent 框架把行为写在 YAML、JSON 或者可视化面板里，调试时要在配置和代码之间来回跳。ADK 的 TypeScript 版本选择相反的方向：README 的定位是 code-first，Agent 的行为、编排和工具调用都直接在代码里声明。它面向的是 Node.js 与浏览器生态里的工程师，前提是这些人已经熟悉 TypeScript，并且愿意把 Agent 当成一个普通的模块来版本管理和部署。仓库的 topics 里出现 multi-agent、multi-agent-systems 这类标签，说明多 Agent 协作是它主打的使用场景，而不是单轮对话包装。
一个 Agent 就是一个带 instruction 和 tools 的对象
README 给出的最小例子很直白：从 @google/adk 导入 LlmAgent 和 GOOGLE_SEARCH，然后 new 一个 LlmAgent，传入 name、description、model、instruction、tools 五个字段，最后导出为 rootAgent。模型名写成 'gemini-flash-latest'，工具数组里放的是内置的 GOOGLE_SEARCH 常量。这里没有隐藏的注册步骤，也没有单独的配置文件，导出的 rootAgent 就是 CLI 的入口。工具参数这一层由 Zod v3 和 v4 schema 承担，README 的说法是支持编译期类型推断，也就是说工具函数的入参类型和模型实际传进来的 JSON 之间有一道 schema 校验。内置工具列表里还有 Google Maps、Vertex AI Search 和 URL context，另外可以接 MCP server、把任意函数包成工具、或者加代码执行。
编排方式与运行时的两条轴线
README 把编排拆成 sequential、parallel、loop、routed 四种组合方式，跨进程则通过 A2A 协议委派给远端 Agent。这四类覆盖的是控制流，不涉及具体模型调用细节。运行时这条轴线更值得注意：包同时提供 ESM、CommonJS 和 web 三种产物，意味着同一份 Agent 代码可以在 Node.js 里跑，也可以直接在浏览器里跑。对需要在前端做本地工具调用或者减少一次服务端往返的场景，这个选择是有意义的；代价是浏览器环境里能用的工具集必然比服务端窄，内置的 Google Search、Maps、Vertex AI Search 这些依赖服务端凭据的能力，在浏览器里怎么处理凭据，README 没有交代。
安装、认证与三条 CLI 命令
前置条件是 Node.js 20.19 或更新版本。安装分两步：npm install @google/adk 装核心 SDK，npm install -D @google/adk-devtools 把 CLI 和 dev UI 作为开发依赖装上，yarn 的写法对应为 yarn add 与 yarn add -D。认证有两种。走 API key 的话，从 Google AI Studio 取 key 写进 Agent 同目录的 .env，键名是 GOOGLE_GENAI_API_KEY。走 Vertex AI 的话，改用 GOOGLE_GENAI_USE_VERTEXAI=1 加上 GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_LOCATION，并用 gcloud auth application-default login 完成认证。运行命令有三条：npx @google/adk-devtools run agent.ts 进交互式 CLI，npx @google/adk-devtools web 起开发 UI，adk deploy cloud_run 负责部署。README 专门用一段提示强调必须写全包名，因为如果本地没装 @google/adk-devtools，裸写 npx adk 会静默地从公共 registry 下载并运行一个同名的无关包。这是文档里少见的、明确写出来的坑。
开发 UI 能看什么，看不到什么
adk web 启动的是一个用于测试和调试 Agent 的开发界面，README 附的截图文件名是 adk-web-dev-ui-function-call，从命名可以推断界面会展示函数调用过程。除此之外，README 没有说明这个 UI 是否持久化会话、是否支持回放、是否能对比两次运行的差异。对于一个宣称覆盖 build、evaluate、deploy 三个环节的工具包，评估这一环在 README 里几乎没有展开，只有一句描述性的定位。如果你需要的是可复现的评估流水线，比如固定数据集上的回归对比，现有材料不足以判断 ADK 是否提供，这一点需要自己去查 adk.dev 上的文档再决定。
模型绑定与部署路径是两道硬边界
认证配置里只有 Google 的两条路：AI Studio 的 API key，或者 Vertex AI 加 GCP 项目与区域。README 没有提到任何非 Google 模型的接入方式，内置工具也全部指向 Google 自家的检索与地图服务。这意味着两件事。第一，如果你的团队已经在用其他厂商的模型，ADK 的 TypeScript 版不是中立选择。第二，部署命令只给了 adk deploy cloud_run 一条，Cloud Run 之外的目标环境需要自己解决打包和凭据注入。浏览器运行时这条线同样如此：能跑起来不等于能在浏览器里安全地持有凭据。这不是实现缺陷，而是框架的边界，评估时应当把它当成选型的第一道筛子。
和 LangGraph.js 的路线差异
同在 TypeScript 生态里做 Agent 编排，LangGraph.js 的思路是把流程显式建模成状态图：节点、边、共享状态对象，控制流由图的拓扑决定。ADK 的路线是把 Agent 当对象组合，用 sequential、parallel、loop、routed 这几种预置编排把多个 Agent 串起来，控制流藏在组合结构里而不是一张显式的图上。差别在调试体验上会体现出来：图模型更容易画出执行路径，也更容易在某个节点上做中断和恢复；对象组合写起来更短，但流程一复杂，执行顺序就得靠读代码推断。ADK 这边的补偿是 TypeScript 类型和 Zod 校验，把错误尽量提前到编译期和工具调用入口。选哪个取决于你更怕哪一类问题：怕流程不可见，还是怕类型不安全。
维护成本与许可
仓库未归档，最近一次 push 是 2026 年 9 月 10 日，三个包在 2026 年 8 月 21 日同日发布了 v2.0.0：main、integrations、devtools。三个包同版本号同日发布，说明它们被当作一套协同发布的组件，升级时应当整体对齐，不要只动其中一个。许可为 Apache-2.0，允许商用和修改，附带专利授权条款；具体条款如何适用于你的分发方式，需要自行阅读 LICENSE 并咨询法务，这里不做判断。升级成本主要来自两处：Zod 主版本升级（README 明确同时支持 v3 和 v4，说明跨版本兼容被当作一项承诺在维护），以及模型名这类字符串常量，例子里的 'gemini-flash-latest' 属于跟随式命名，长期稳定性取决于上游如何维护这个别名。
编辑结论
适合已经用 TypeScript 写业务、希望 Agent 定义与工具签名都受编译器约束、并且接受把运行时绑在 Google 模型与 Vertex AI 上的团队。不适合只想用任意模型做一次性原型、或者不愿意引入 Node.js 20.19 以上运行时约束的项目。动手前先确认三件事：npx 调用必须写成 @google/adk-devtools，否则会拉到公共 registry 上同名的无关包；工具参数是否真的用 Zod schema 声明，这决定了类型安全是不是空话；以及部署路径是否只走 Cloud Run，如果生产环境在别处，adk deploy 这条命令帮不上忙。
社区笔记