名称： adk
描述： 使用 Botpress 智能体开发套件 (ADK) 构建 AI 机器人的指南
版本： 1.0.0
作者： yueranlu
标签： [botpress, adk, chatbot, ai, typescript]
主页： https://github.com/botpress/adk
使用 Botpress 智能体开发套件 (ADK) 构建 AI 机器人的综合指南。
adk CLI 命令的帮助（init、dev、deploy、link）ADK 是一个基于约定的 TypeScript 框架，其中文件结构直接映射到机器人行为。
你的角色： 引导用户完成整个机器人开发生命周期——从项目设置到部署。使用本技能中的模式和代码示例来编写正确、可运行的 ADK 代码。
核心原则： 在 ADK 中，文件放置的位置至关重要。每种组件类型都有特定的 src/ 子目录，文件根据位置自动被发现。
本技能是你构建 Botpress 机器人的主要参考。 当用户要求你使用 ADK 构建某些功能时：
src/ 子目录中adk --help - 对于此处未涵盖的 CLI 命令，或运行 adk <command> --help 获取特定帮助决策指南 - 创建什么组件：
| 用户想要... | 创建此组件 | 位置 |
|---|---|---|
| 处理用户消息 | 对话 | src/conversations/ |
| 添加 AI 可以调用的函数 | 工具 | src/tools/ |
| 添加可复用的业务逻辑 | 动作 | src/actions/ |
| 运行后台/计划任务 | 工作流 | src/workflows/ |
| 存储结构化数据 | 表 | src/tables/ |
| 响应事件（用户创建等） | 触发器 | src/triggers/ |
| 让 AI 访问文档/数据 | 知识库 | src/knowledge/ |
| 连接外部服务（Slack 等） | 集成 | adk add <name> |
如果本技能中的信息不够，请获取相应的 GitHub 参考文件（每节都提供了链接）以获取更详细的规范。
ADK 不使用传统的聊天机器人模式。不要创建意图、实体或对话流。
替代方案：
- 定义意图 (greet, orderPizza, checkStatus)
- 训练实体提取 (@pizzaSize, @toppings)
- 手动路由到意图处理器
ADK 使用：
- execute() - AI 根据指令自然理解用户意图
- 工具 - AI 自主决定何时调用你的函数
- zai.extract() - 基于模式的结构化数据提取
- 知识库 - 基于你的文档进行 RAG 以生成有根据的响应
文档： https://www.botpress.com/docs/adk/
GitHub： https://github.com/botpress/skills/tree/master/skills/adk
在使用 ADK 之前，请确保用户已具备：
node --version 检查安装 ADK CLI：
macOS & Linux：
curl -fsSL https://github.com/botpress/adk/releases/latest/download/install.sh | bash
Windows (PowerShell)：
powershell -c "irm https://github.com/botpress/adk/releases/latest/download/install.ps1 | iex"
验证安装：
adk --version
如果安装失败，请检查 https://github.com/botpress/adk/releases 以获取手动下载选项。
文档： https://www.botpress.com/docs/adk/quickstart
GitHub： https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/cli.md
安装 ADK CLI 后，创建一个新机器人：
adk init my-bot # 创建项目（为初学者选择 "Hello World" 模板）
cd my-bot
npm install # 或使用 bun/pnpm/yarn
adk login # 使用 Botpress Cloud 进行身份验证
adk add chat # 添加聊天集成以进行测试
adk dev # 启动开发服务器（支持热重载）
adk chat # 在 CLI 中测试（在单独的终端中运行）
adk deploy # 准备就绪后部署到生产环境
http://localhost:3001/ 处的可视化控制台允许你配置集成和测试机器人。
文档： https://www.botpress.com/docs/adk/quickstart
GitHub： https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/cli.md
重要提示： 你的机器人必须链接到 Botpress Cloud 并部署才能正常工作。ADK 在开发期间本地运行，但机器人本身存在于 Botpress Cloud 中。
按照此顺序使你的机器人正常工作：
# 1. 链接 - 将你的项目连接到 Botpress Cloud（创建 agent.json）
adk link
# 2. 开发 - 启动开发服务器（热重载、测试）
adk dev
# 3. 部署 - 准备就绪后推送到生产环境
adk deploy
分步说明：
adk link - 将你的本地项目链接到 Botpress Cloud 中的一个机器人。这会创建包含你的工作区和机器人 ID 的 agent.json。在任何其他操作之前首先运行此命令。
adk dev - 启动本地开发服务器并启用热重载。在 http://localhost:3001 打开开发控制台，你可以在其中配置集成和测试机器人。在单独的终端中使用 adk chat 进行测试。
adk deploy - 将你的机器人部署到生产环境。当你准备好让机器人通过生产渠道（Slack、WhatsApp、网页聊天等）实时访问时运行此命令。
如果在运行 adk dev 或 adk deploy 时遇到错误：
常见错误场景：
- 集成配置错误： 通常意味着需要在 localhost:3001 的 UI 中配置集成
- 类型错误： 通常由不正确的导入或模式不匹配引起
- 部署失败： 可能表示缺少环境变量或配置无效
修复错误的示例工作流：
1. 运行 `adk dev` 或 `adk deploy`
2. 在终端/日志中看到错误
3. 复制错误信息
4. 告诉 AI："我在运行 adk dev 时遇到此错误：[粘贴错误]"
5. AI 将帮助诊断并修复问题
文档： https://www.botpress.com/docs/adk/quickstart
GitHub： https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/cli.md
关键规则： 文件位置决定行为。将组件放在正确的 src/ 子目录中，否则它们将不会被发现。
my-bot/
├── agent.config.ts # 机器人配置：名称、模型、状态模式、集成
├── agent.json # 工作区/机器人 ID（由 adk link/dev 自动生成，添加到 .gitignore）
├── package.json # Node.js 依赖项和脚本（dev、build、deploy）
├── tsconfig.json # TypeScript 配置
├── .env # API 密钥和密钥（切勿提交！）
├── .gitignore # 应包含：agent.json、.env、node_modules/、.botpress/
├── src/
│ ├── conversations/ # 处理传入消息 → 使用 execute() 获取 AI 响应
│ ├── workflows/ # 后台进程 → 使用 step() 进行可恢复的操作
│ ├── actions/ # 可复用函数 → 从任何地方使用 actions.name() 调用
│ ├── tools/ # AI 可调用函数 → AI 决定何时调用这些函数
│ ├── tables/ # 数据存储 → 自动同步到云端，支持语义搜索
│ ├── triggers/ # 事件处理器 → 响应 user.created、集成事件等
│ └── knowledge/ # RAG 源 → 为 AI 上下文索引文档、网站或表
└── .botpress/ # 自动生成的类型（切勿手动编辑）
关键配置文件：
adk link 或 adk dev 自动生成。添加到 .gitignore - 包含每个开发人员不同的环境特定 ID@botpress/runtime 依赖项和 dev、build、deploy 脚本agent.json、.env、node_modules/、.botpress/文档： https://www.botpress.com/docs/adk/project-structure
GitHub： https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/agent-config.md
agent.config.ts 文件定义你的机器人身份、AI 模型、状态模式和集成。设置新机器人时始终从这里开始。
import { defineConfig, z } from "@botpress/runtime";
export default defineConfig({
name: "my-support-bot",
description: "AI 客户支持助手",
// 用于不同操作的 AI 模型
defaultModels: {
autonomous: "openai:gpt-4o", // 由 execute() 用于对话
zai: "openai:gpt-4o-mini" // 用于 zai 操作（更便宜、更快）
},
// 全局机器人状态 - 在所有对话和用户之间共享
bot: {
state: z.object({
maintenanceMode: z.boolean().default(false),
totalConversations: z.number().default(0)
})
},
// 每个用户的状态 - 为每个用户在所有对话中持久化
user: {
state: z.object({
name: z.string().optional(),
tier: z.enum(["free", "pro"]).default("free"),
preferredLanguage: z.enum(["en", "es", "fr"]).default("en")
}),
tags: {
source: z.string(),
region: z.string().optional()
}
},
// 每个对话的状态
conversation: {
state: z.object({
context: z.string().optional()
}),
tags: {
category: z.enum(["support", "sales", "general"]),
priority: z.enum(["low", "medium", "high"]).optional()
}
},
// 你的机器人使用的集成（ADK 1.9+ 格式）
dependencies: {
integrations: {
chat: { version: "chat@0.7.3", enabled: true },
slack: { version: "slack@2.5.5", enabled: true }
}
}
});
可用模型：
- OpenAI：openai:gpt-4o、openai:gpt-4o-mini、openai:gpt-4-turbo
- Anthropic：anthropic:claude-3-5-sonnet、anthropic:claude-3-opus
- Google：google:gemini-1.5-pro、google:gemini-1.5-flash
文档： https://www.botpress.com/docs/adk/project-structure
GitHub： https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/agent-config.md
何时创建动作：
- 你需要从多个地方（工作流、对话、触发器）调用的可复用逻辑
- 你正在包装外部 API 或数据库操作
- 你想要可测试、可组合的业务逻辑
- 你需要使用自定义逻辑调用集成 API（Slack、Linear 等）
何时不使用动作（改用工具）：
- 你希望 AI 自主决定何时调用它
- 该函数应在 execute() 期间可用
动作不能直接被 AI 调用 - 如果 AI 需要使用它们，请使用 .asTool() 将它们转换为工具。
位置： src/actions/*.ts
import { Action, z } from "@botpress/runtime";
export const fetchUser = new Action({
name: "fetchUser",
description: "从数据库检索用户详细信息",
// 使用 Zod 模式定义输入/输出以确保类型安全
input: z.object({ userId: z.string() }),
output: z.object({ name: z.string(), email: z.string() }),
// 重要：处理器接收 { input, client } - 必须在处理器内部解构 input
async handler({ input, client }) {
const { user } = await client.getUser({ id: input.userId });
return { name: user.name, email: user.tags.email };
}
});
调用动作：
import { actions } from "@botpress/runtime";
const userData = await actions.fetchUser({ userId: "123" });
// 要使动作可被 AI 调用，将其转换为工具：
tools: [actions.fetchUser.asTool()]
关键规则：
- 处理器接收 { input, client } - 必须在处理器内部解构 input
- 不能在参数中直接解构输入字段
- 可以调用其他动作、集成动作、访问状态
- 可以使用 .asTool() 转换为工具
文档： https://www.botpress.com/docs/adk/concepts/actions
GitHub： https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/actions.md
何时创建工具：
- 你希望 AI 自主决定何时使用此函数
- 该函数检索 AI 需要的信息（搜索、查找、获取）
- 该函数代表用户执行操作（创建工单、发送消息）
- 你正在构建 AI 在对话期间应具备的能力
AI 根据以下因素决定何时使用工具：
1. 工具的 description - 使其清晰具体地说明何时使用它
2. 输入模式的 .describe() 字段 - 帮助 AI 理解参数含义
3. 对话上下文和用户意图
与动作的关键区别： 工具可以直接解构输入；动作不能。
位置： src/tools/*.ts
import { Autonomous, z } from "@botpress/runtime";
export const searchProducts = new Autonomous.Tool({
name: "searchProducts",
// 此描述至关重要 - 它告诉 AI 何时使用此工具
description: "搜索产品目录。当用户询问产品、可用性、定价或想要浏览商品时使用。",
input: z.object({
query: z.string().describe("搜索关键词"),
category: z.string().optional().describe("按类别筛选")
}),
output: z.object({
products: z.array(z.object({ id: z.string(), name: z.string(), price: z.number() }))
}),
// 与动作不同，工具可以在处理器中直接解构输入
handler: async ({ query, category }) => {
// 你的搜索逻辑在这里
return { products: [] };
}
});
使用 ThinkSignal： 当工具无法完成但你想给 AI 提供上下文时：
import { Autonomous } from "@botpress/runtime";
// 在处理器内部 - AI 将看到此消息并可以适当响应
throw new Autonomous.ThinkSignal(
"未找到结果",
"未找到匹配该查询的产品。请用户尝试不同的搜索词。"
);
高级工具属性：
``typescript
export const myTool = new Autonomous.Tool({
name: "myTool",
description: "工具描述",
input: z.object({...}),
output: z.object({...}),
aliases: ["searchDocs", "findDocs"], // 替代名称
handler: async (input, ctx) => {
console.log(调用 ID: ${ctx.callId}`); // 唯一的调用标识符
// ...