使用 TypeScript 智能体开发套件（ADK）构建 AI 智能体
本教程将使用 TypeScript 和 Agent Development Kit（ADK）的原生 TypeScript 版本，构建一个入门级的「Hello World」风格智能体。完整示例项目可在 GitHub 上查看：xbill9 (xbill) · GitHub 12032025/16785778。xbill9 共有 209 个公开仓库，可在 GitHub 上关注他的代码。github.com
什么是 TypeScript？
TypeScript 是一种强类型编程语言，建立在 JavaScript 之上，由微软维护。它会编译成纯 JavaScript，可以在任何 JavaScript 能运行的地方运行——包括 Node.js，后者正是 TypeScript 版 ADK 的目标运行环境。静态类型系统与智能体开发天然契合：工具参数、工具返回值以及智能体配置，都会在模型看到它们之前，于编译阶段就完成检查。
安装 Node.js
TypeScript 版 ADK 需要 Node.js 20 或更高版本。如果你的环境中尚未安装 Node.js，Node Version Manager（nvm）是最简单的安装与版本管理方式：nvm.sh · GitHub nvm - node version manager。nvm.sh 共有 4 个公开仓库，可在 GitHub 上关注它的代码。github.com
安装并启用一个当前版本的 Node.js 发行版：
你可以通过版本命令来验证安装是否成功：
什么是 Agent Development Kit（ADK）？
Agent Development Kit（ADK）是一个灵活、模块化的框架，用于开发和部署 AI 智能体。ADK 针对 Gemini 和 Google 生态做了优化，但它不限定模型、不限定部署方式，并且设计上兼容其他框架。Google 在此提供了 ADK 的完整文档：Agent Development Kit (ADK) - Agent Development Kit (ADK)Agent Development Kit (ADK) Build powerful multi-agent systems with Agent Development Kit (ADK) adk.dev
Google 还提供了 ADK 项目完整 TypeScript 版本的源代码：Google · GitHub Google ❤️ Open Source。Google 共有 2888 个公开仓库，可在 GitHub 上关注它的代码。github.com
ADK 以 @google/adk 的名称发布到 npm，开发工具则位于 @google/adk-devtools。本教程使用的是 ADK 1.4.0。
Gemini API 密钥
如果不使用 Application Default Credentials（ADC），你需要一个 Gemini API 密钥。
可以从 Google AI Studio 获取 Gemini 密钥：accounts.google.com
检查开发环境
安装好 Node.js 后，克隆示例仓库并运行 init.sh 脚本。脚本会安装 npm 依赖，并生成一个初始的 .env 文件：
输出：
编辑 .env 并选择一种身份验证方式：
- Gemini Developer API：设置
GOOGLE_API_KEY - Vertex AI：设置
GOOGLE_GENAI_USE_VERTEXAI=TRUE、GOOGLE_CLOUD_PROJECT和GOOGLE_CLOUD_LOCATION，然后通过 ADC 完成身份验证：
注意：切勿把 .env 提交到版本库——它已经列在 .gitignore 中了。
排查 API 权限错误
如果应用默认凭据（ADC）过期，或 Google Cloud 身份验证失效，请重新执行以下命令完成身份验证：
另一个常见问题是环境变量缺失。代理会通过 dotenv 自动加载 .env 文件；对于需要相同环境变量的 shell 命令，项目还提供了 set_env.sh 脚本：
TypeScript ADK 代理
整个代理只存在于一个文件中——src/agent.ts
使用 cli.sh 或直接运行 npm 脚本：
与 ADK Web UI 交互
在本地开发环境启动 Web GUI 后，就能在浏览器里调试 agent。如果你是在远程虚拟机或容器里开发，需要让外部也能访问这个 UI，可以把服务绑定到所有网络接口：
这个 UI 与 Python、Java、Go 版 ADK 提供的是同一个开发界面——从下拉框中选择 agent，即可开始对话，并看到完整的工具调用追踪。
如果不想带 UI，只想把 agent 暴露成一个普通的 HTTP API：
使用 ADK CLI 部署到 Cloud Run
更多部署选项请查阅官方文档。TypeScript ADK CLI 内置了部署功能，cloudrun.sh 脚本会加载 .env 环境变量，然后调用 deploy 命令：
加上 --with_ui true 参数，可以把开发 UI 一起打包进部署后的 Cloud Run 服务。
在 Google Cloud Console 中检查
部署完成后，可以在 Google Cloud Console 中验证 Cloud Run 服务，或者通过 CLI 获取服务地址：
小结
TypeScript Agent Development Kit（ADK）让你使用标准的 TypeScript 和 Node.js 特性快速开发 agent：
- 干净的工具定义：用 Zod schema 定义带类型的工具。
- 确定性的测试：借助 Node 内置的测试运行器（
node:test）进行快速单元测试。 - 本地追踪：提供交互式 CLI 和 Web UI（
adk web）。 - 直接部署到云端：一条命令部署到 Cloud Run（
adk deploy cloud_run）。