TypeScript Quickstart for ADK¶
ADK TypeScript 快速入门¶
This guide shows you how to get up and running with Agent Development Kit for TypeScript. Before you start, make sure you have the following installed:
本指南向您展示如何开始使用 TypeScript 版智能体开发工具包。在开始之前,请确保您已安装以下内容:
- Node.js 20.12.7 or later Node.js 20.12.7 或更高版本
- Node Package Manager (npm) 9.2.0 or later Node 包管理器 (npm) 9.2.0 或更高版本
Create an agent project¶
创建智能体项目¶
Create an agent project with the following files and directory structure:
创建一个具有以下文件和目录结构的智能体项目:
my-agent/
agent.ts # main agent code
# 主要智能体代码
package.json # project configuration
# 项目配置
tsconfig.json # TypeScript configuration
# TypeScript 配置
.env # API keys or project IDs
# API 密钥或项目 ID
Create this project structure using the command line
使用命令行创建此项目结构
Note: Do not create tsconfig.json, you generate that
file in a later step.
注意:不要创建 tsconfig.json,您将在后面的步骤中生成该文件。
Define the agent code¶
定义智能体代码¶
Create the code for a basic agent, including a simple implementation of an ADK
Function Tool, called getCurrentTime.
Add the following code to the agent.ts file in your project
directory:
创建基本智能体的代码,包括 ADK 函数工具 的简单实现,称为 getCurrentTime。
将以下代码添加到项目目录中的 agent.ts 文件:
import {FunctionTool, LlmAgent} from '@google/adk';
import {z} from 'zod';
/* Mock tool implementation */
/* 模拟工具实现 */
const getCurrentTime = new FunctionTool({
name: 'get_current_time',
description: 'Returns the current time in a specified city.',
parameters: z.object({
city: z.string().describe("The name of the city for which to retrieve the current time."),
}),
execute: ({city}) => {
return {status: 'success', report: `The current time in ${city} is 10:30 AM`};
},
});
export const rootAgent = new LlmAgent({
name: 'hello_time_agent',
model: 'gemini-2.5-flash',
description: 'Tells the current time in a specified city.',
instruction: `You are a helpful assistant that tells the current time in a city.
Use the 'getCurrentTime' tool for this purpose.`,
tools: [getCurrentTime],
});
Configure project and dependencies¶
配置项目和依赖项¶
Use the npm tool to install and configure dependencies for your project,
including the package file, TypeScript configuration, ADK TypeScript main
library and developer tools. Run the following commands from your
my-agent/ directory:
使用 npm 工具为您的项目安装和配置依赖项,包括包文件、TypeScript 配置、ADK TypeScript 主库和开发工具。从 my-agent/ 目录运行以下命令:
cd my-agent/
# initialize a project with default values
# 使用默认值初始化项目
npm init --yes
# configure TypeScript
# 配置 TypeScript
npm install -D typescript
npx tsc --init
# install ADK libraries
# 安装 ADK 库
npm install @google/adk
npm install @google/adk-devtools
After completing these installation and configuration steps, open
the package.json project file and verify that the main: value
is set to agent.ts, that the TypeScript dependency is set, as
well as the ADK library dependencies, as shown in this example:
完成这些安装和配置步骤后,打开 package.json 项目文件并验证 main: 值设置为 agent.ts,TypeScript 依赖项已设置,以及 ADK 库依赖项,如本示例所示:
{
"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"
}
}
For development convenience, in the tsconfig.json file, update the
setting for verbatimModuleSyntax to false to allow simpler syntax
when adding modules:
为了开发方便,在 tsconfig.json 文件中,将 verbatimModuleSyntax 的设置更新为 false,以便在添加模块时允许更简单的语法:
// set to false to allow CommonJS module syntax:
// 设置为 false 以允许 CommonJS 模块语法:
"verbatimModuleSyntax": false,
Compile the project¶
编译项目¶
After completing the project setup, compile the project to prepare for running your ADK agent:
完成项目设置后,编译项目以准备运行您的 ADK 智能体:
Set your API key¶
设置您的 API 密钥¶
This project uses the Gemini API, which requires an API key. If you don't already have a Gemini API key, create a key in Google AI Studio on the API Keys page.
本项目使用 Gemini API,该 API 需要 API 密钥。如果您还没有 Gemini API 密钥,请前往 Google AI Studio 在 API 密钥 页面创建密钥。
In a terminal window, write your API key into your .env file of your project
to set environment variables:
在终端窗口中,将您的 API 密钥写入项目的 .env 文件以设置环境变量:
Using other AI models with ADK
在 ADK 中使用其他 AI 模型
ADK supports the use of many generative AI models. For more information on configuring other models in ADK agents, see Models & Authentication.
ADK 支持使用多种生成式 AI 模型。有关在 ADK 智能体中配置其他模型的更多信息,请参阅模型和身份验证。
Run your agent¶
运行您的智能体¶
You can run your ADK agent with the @google/adk-devtools library as an
interactive command-line interface using the run command or the ADK web user
interface using the web command. Both these options allow you to test and
interact with your agent.
您可以使用 @google/adk-devtools 库通过交互式命令行界面使用 run 命令运行您的 ADK 智能体,或使用 web 命令使用 ADK Web 用户界面。这两个选项都允许您测试和与智能体交互。
Run with command-line interface¶
使用命令行界面运行¶
Run your agent with the ADK TypeScript command-line interface tool using the following command:
使用以下命令通过 ADK TypeScript 命令行界面工具运行您的智能体:
Run with web interface¶
使用 Web 界面运行¶
Run your agent with the ADK web interface using the following command:
使用以下命令通过 ADK Web 界面运行您的智能体:
This command starts a web server with a chat interface for your agent. You can access the web interface at (http://localhost:8000). Select your agent at the upper right corner and type a request.
此命令启动一个带有智能体聊天界面的 Web 服务器。您可以在 (http://localhost:8000) 访问 Web 界面。在右上角选择智能体并输入请求。
Caution: ADK Web for development only
警告:ADK Web 仅用于开发
ADK Web is not meant for use in production deployments. You should use ADK Web for development and debugging purposes only.
ADK Web 不适用于生产环境部署。您应该仅将 ADK Web 用于开发和调试目的。
Next: Build your agent¶
下一步:构建您的智能体¶
Now that you have ADK installed and your first agent running, try building your own agent with our build guides:
既然您已经安装了 ADK 并运行了第一个智能体,请尝试使用我们的构建指南构建您自己的智能体: