ADK 的 TypeScript 快速入门¶

本指南展示如何开始使用 Agent Development Kit TypeScript 版。开始之前，请确保已安装以下内容：

Node.js 20.12.7 或更高版本
Node Package Manager (npm) 9.2.0 或更高版本

创建一个智能体项目¶

创建一个包含以下文件和目录结构的智能体项目：

my-agent/
    agent.ts        # 主智能体代码
    package.json    # 项目配置
    tsconfig.json   # TypeScript 配置
    .env            # API 密钥或项目 ID

使用命令行创建此项目结构

MacOS / LinuxWindows

mkdir -p my-agent/ && \
    touch my-agent/agent.ts \
    touch my-agent/package.json \
    touch my-agent/.env

mkdir my-agent\
type nul > my-agent\agent.ts
type nul > my-agent\package.json
type nul > my-agent\.env

注意： 不要创建 tsconfig.json，你将在后面的步骤中生成该文件。

定义智能体代码¶

创建一个基本智能体的代码，包括一个 ADK 函数工具的简单实现，名为 getCurrentTime。将以下代码添加到项目目录中的 agent.ts 文件：

my-agent/agent.ts

import {FunctionTool, LlmAgent} from '@google/adk';
import {z} from 'zod';

/* 模拟工具实现 */
const getCurrentTime = new FunctionTool({
  name: 'get_current_time',
  description: '返回指定城市中的当前时间。',
  parameters: z.object({
    city: z.string().describe("要检索当前时间的城市名称。"),
  }),
  execute: ({city}) => {
    return {status: 'success', report: `${city} 的当前时间是上午 10:30`};
  },
});

export const rootAgent = new LlmAgent({
  name: 'hello_time_agent',
  model: 'gemini-2.5-flash',
  description: '告诉指定城市中的当前时间。',
  instruction: `你是一个有帮助的助手，告诉你一个城市中的当前时间。
                为此目的使用 'getCurrentTime' 工具。`,
  tools: [getCurrentTime],
});

配置项目和依赖项¶

使用 npm 工具安装和配置项目的依赖项，包括包文件、TypeScript 配置、ADK TypeScript 主库和开发工具。从你的 my-agent/ 目录运行以下命令：

cd my-agent/
# 使用默认值初始化项目
npm init --yes
# 配置 TypeScript
npm install -D typescript
npx tsc --init
# 安装 ADK 库
npm install @google/adk
npm install @google/adk-devtools

完成这些安装和配置步骤后，打开 package.json 项目文件并验证 main: 值是否设置为 agent.ts，TypeScript 依赖项是否已设置，以及 ADK 库依赖项，如本示例所示：

my-agent/package.json

{
  "name": "my-agent",
  "version": "1.0.0",
  "description": "My ADK Agent",
  "main": "agent.ts",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "devDependencies": {
    "typescript": "^5.9.3"
  },
  "dependencies": {
    "@google/adk": "^0.2.0",
    "@google/adk-devtools": "^0.2.0"
  }
}

为方便开发，在 tsconfig.json 文件中，将 verbatimModuleSyntax 设置更新为 false 以允许更简单的语法在添加模块时：

my-agent/tsconfig.json

    // 设置为 false 以允许 CommonJS 模块语法：
    "verbatimModuleSyntax": false,

编译项目¶

完成项目设置后，编译项目以准备运行你的 ADK 智能体：

npx tsc

设置你的 API 密钥¶

此项目使用 Gemini API，需要一个 API 密钥。如果你还没有 Gemini API 密钥，请在 Google AI Studio 的 API 密钥页面创建一个。

在终端窗口中，将你的 API 密钥写入项目的 .env 文件以设置环境变量：

Update: my-agent/.env

echo 'GEMINI_API_KEY="YOUR_API_KEY"' > .env

在 ADK 中使用其他 AI 模型

ADK 支持使用许多生成式 AI 模型。有关在 ADK 智能体中配置其他模型的更多信息，请参见模型和认证。

运行你的智能体¶

你可以使用 @google/adk-devtools 库以交互式命令行界面运行你的 ADK 智能体使用 run 命令或使用 ADK Web 用户界面使用 web 命令。这两个选项都允许你测试和与你的智能体交互。

使用命令行界面运行¶

使用 ADK TypeScript 命令行界面工具运行你的智能体使用以下命令：

npx @google/adk-devtools run agent.ts

使用网页界面运行¶

使用以下命令通过 ADK Web 界面运行你的智能体：

npx @google/adk-devtools web

此命令启动一个具有聊天界面的网页服务器供你的智能体使用。你可以在 (http://localhost:8000) 访问网页界面。在右上角选择你的智能体并输入请求。

注意：ADK Web 仅供开发使用

ADK Web不适用于生产部署。你应该仅将 ADK Web 用于开发和调试目的。

下一步：构建你的智能体¶

现在你已经安装了 ADK 并运行了你的第一个智能体，尝试使用我们的构建指南构建你自己的智能体：

构建你的智能体