npx skills add https://github.com/botpress/skills --skill adk当您对 Botpress Agent Development Kit (ADK) 有疑问时,请使用此技能——例如当您构建涉及表格、操作、工具、工作流、对话、文件、知识库、触发器或 Zai 的功能时。
Botpress ADK 是一个基于约定的 TypeScript 框架,其中文件结构直接映射到机器人行为。将文件放置在正确的目录中,它们就会自动成为机器人的可用能力。
ADK 为以下内容提供了基础构建块:
所有基础构建块必须放置在 src/ 目录中:
/ # 项目根目录
├── src/
│ ├── actions/ # 强类型函数 → 自动注册
│ ├── tools/ # AI 可调用工具 → 通过 execute() 可用
│ ├── workflows/ # 长时间运行的流程 → 可恢复/可调度
│ ├── conversations/ # 消息处理器 → 按渠道路由
│ ├── tables/ # 数据库模式 → 自动创建并支持搜索
│ ├── triggers/ # 事件处理器 → 订阅事件
│ ├── knowledge/ # 知识库 → 支持语义搜索的 RAG
│ └── utils/ # 共享辅助函数(非自动注册)
└── agent.config.ts # 机器人配置(包含集成)
注意: 已在 ADK 1.9+ 中移除。所有配置,包括集成,现在都位于 中。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
dependencies.jsonagent.config.ts关键:
src/目录外的文件不会被发现。位置 = 行为。
当用户提出与 ADK 相关的问题时,请激活此技能,例如:
ADK 问题分为两类:CLI 查询和文档查找。
对于集成发现和 CLI 查询,使用 Bash 工具直接运行命令:
集成发现:
# 搜索集成
adk search <query>
# 列出所有可用集成
adk list --available
# 获取详细的集成信息(操作、渠道、事件)
adk info <integration-name>
# 检查已安装的集成(必须在 ADK 项目中)
adk list
项目信息:
# 检查 CLI 版本
adk --version
# 显示项目状态
adk
# 获取帮助
adk --help
何时使用 CLI 命令:
响应模式:
adk 命令adk add slack@3.0.0 来安装”)对于文档、模式和操作指南问题,直接搜索和引用文档文件:
何时使用文档:
如何回答文档问题:
查找相关文件 - 使用 Glob 发现文档:
pattern: **/references/*.md
搜索关键词 - 使用 Grep 查找相关内容:
pattern: <用户问题中的关键词> path: <步骤 1 中获取的 references 目录路径> output_mode: files_with_matches
读取文件 - 使用 Read 加载相关文档
提供答案,包含: * 简洁的解释 * 来自参考资料的代码示例 * 带行号的文件引用(例如,“来自 references/actions.md:215”) * 相关的常见陷阱 * 供进一步阅读的相关主题
文档应位于相对于此技能的 ./references/ 目录中。回答问题时,请搜索以下主题:
访问 ADK 运行时服务的快速参考:
// 始终从 @botpress/runtime 导入
import {
Action,
Autonomous,
Workflow,
Conversation,
z,
actions,
adk,
user,
bot,
conversation,
context,
} from "@botpress/runtime";
// 机器人状态(在 agent.config.ts 中定义)
bot.state.maintenanceMode = true;
bot.state.lastDeployedAt = new Date().toISOString();
// 用户状态(在 agent.config.ts 中定义)
user.state.preferredLanguage = "en";
user.state.onboardingComplete = true;
// 用户标签
user.tags.email; // 访问用户元数据
// 调用机器人操作
await actions.fetchUser({ userId: "123" });
await actions.processOrder({ orderId: "456" });
// 调用集成操作
await actions.slack.sendMessage({ channel: "...", text: "..." });
await actions.linear.issueList({ teamId: "..." });
// 将操作转换为工具
tools: [fetchUser.asTool()];
// 获取运行时服务
const client = context.get("client"); // Botpress 客户端
const cognitive = context.get("cognitive"); // AI 模型客户端
const citations = context.get("citations"); // 引用管理器
myAction.ts, searchDocs.ts (camelCase)Users.ts, Orders.ts (PascalCase)chat.ts, slack.ts (lowercase)回答问题时,请始终根据文档验证这些模式:
# 支持所有包管理器
bun install # 推荐(最快)
npm install # 可用
yarn install # 可用
pnpm install # 可用
# ADK 根据锁文件自动检测
# - bun.lockb → 使用 bun
# - package-lock.json → 使用 npm
# - yarn.lock → 使用 yarn
# - pnpm-lock.yaml → 使用 pnpm
// ✅ 正确 - 始终从 @botpress/runtime 导入
import { Action, Autonomous, Workflow, z } from "@botpress/runtime";
// ❌ 错误 - 切勿从 zod 或 @botpress/sdk 导入
import { z } from "zod"; // ❌ 错误
import { Action } from "@botpress/sdk"; // ❌ 错误
// ✅ 两种模式都有效 - 推荐使用 export const
export const myAction = new Action({ ... }); // 推荐
export default new Action({ ... }); // 同样有效
// 为什么使用 export const?
// - 支持直接导入:import { myAction } from "./actions/myAction"
// - 可以传递给 execute(): tools: [myAction.asTool()]
// ✅ 正确 - 处理器接收 { input, client }
export const fetchUser = new Action({
name: "fetchUser",
async handler({ input, client }) { // ✅ 从 props 解构
const { userId } = input; // ✅ 然后解构字段
return { name: userId };
}
});
// ❌ 错误 - 不能直接解构 input 字段
handler({ userId }) { // ❌ 错误 - 必须是 { input }
return { name: userId };
}
// ✅ 正确 - 工具可以直接解构
export const myTool = new Autonomous.Tool({
handler: async ({ query, maxResults }) => {
// ✅ 直接解构 OK
return search(query, maxResults);
},
});
// ✅ 正确 - 使用 conversation.send() 方法
await conversation.send({
type: "text",
payload: { text: "Hello!" }
});
// ❌ 错误 - 切勿直接使用 client.createMessage()
await client.createMessage({ ... }); // ❌ 错误
回答 ADK 问题时,请遵循以下结构:
示例响应结构:
操作是强类型函数,可以从机器人的任何地方调用。
**示例:**
[代码示例]
**常见陷阱:** 记住先解构 `input`(参见故障排除部分)
**相关:** 您可以使用 `.asTool()` 将操作转换为工具 - 参见“何时使用什么”决策树。
**后续步骤:** 在 `src/actions/myAction.ts` 中创建您的操作,它将自动注册。
每周安装数
222
代码仓库
GitHub Stars
6
首次出现
2026年1月23日
安全审计
安装于
codex203
opencode199
gemini-cli191
github-copilot180
amp171
kimi-cli169
Use this skill when you've got questions about the Botpress Agent Development Kit (ADK) - like when you're building a feature that involves tables, actions, tools, workflows, conversations, files, knowledge bases, triggers, or Zai.
The Botpress ADK is a convention-based TypeScript framework where file structure maps directly to bot behavior. Place files in the correct directories, and they automatically become available as bot capabilities.
The ADK provides primitives for:
All primitives must be placed in src/ directory:
/ # Project root
├── src/
│ ├── actions/ # Strongly-typed functions → auto-registered
│ ├── tools/ # AI-callable tools → available via execute()
│ ├── workflows/ # Long-running processes → resumable/scheduled
│ ├── conversations/ # Message handlers → routes by channel
│ ├── tables/ # Database schemas → auto-created with search
│ ├── triggers/ # Event handlers → subscribe to events
│ ├── knowledge/ # Knowledge bases → RAG with semantic search
│ └── utils/ # Shared helpers (not auto-registered)
└── agent.config.ts # Bot configuration (includes integrations)
Note:
dependencies.jsonwas removed in ADK 1.9+. All configuration including integrations now lives inagent.config.ts.
Critical: Files outside
src/are not discovered. Location = behavior.
Activate this skill when users ask ADK-related questions like:
ADK questions fall into two categories: CLI queries and documentation lookups.
For integration discovery and CLI queries, use the Bash tool to run commands directly:
Integration Discovery:
# Search for integrations
adk search <query>
# List all available integrations
adk list --available
# Get detailed integration info (actions, channels, events)
adk info <integration-name>
# Check installed integrations (must be in ADK project)
adk list
Project Info:
# Check CLI version
adk --version
# Show project status
adk
# Get help
adk --help
When to use CLI commands:
Response pattern:
adk commandadk add slack@3.0.0 to install")For documentation, patterns, and how-to questions, search and reference the documentation files directly:
When to use documentation:
How to answer documentation questions:
Find relevant files - Use Glob to discover documentation:
pattern: **/references/*.md
Search for keywords - Use Grep to find relevant content:
pattern: <keyword from user question>
path: <path to references directory from step 1>
output_mode: files_with_matches
Read the files - Use Read to load relevant documentation
Provide answer with:
Documentation should be located in ./references/ directory relative to this skill. When answering questions, search for these topics:
Quick reference for accessing ADK runtime services:
// Always import from @botpress/runtime
import {
Action,
Autonomous,
Workflow,
Conversation,
z,
actions,
adk,
user,
bot,
conversation,
context,
} from "@botpress/runtime";
// Bot state (defined in agent.config.ts)
bot.state.maintenanceMode = true;
bot.state.lastDeployedAt = new Date().toISOString();
// User state (defined in agent.config.ts)
user.state.preferredLanguage = "en";
user.state.onboardingComplete = true;
// User tags
user.tags.email; // Access user metadata
// Call bot actions
await actions.fetchUser({ userId: "123" });
await actions.processOrder({ orderId: "456" });
// Call integration actions
await actions.slack.sendMessage({ channel: "...", text: "..." });
await actions.linear.issueList({ teamId: "..." });
// Convert action to tool
tools: [fetchUser.asTool()];
// Get runtime services
const client = context.get("client"); // Botpress client
const cognitive = context.get("cognitive"); // AI model client
const citations = context.get("citations"); // Citation manager
myAction.ts, searchDocs.ts (camelCase)Users.ts, Orders.ts (PascalCase)chat.ts, slack.ts (lowercase)When answering questions, always verify these patterns against the documentation:
# All package managers are supported
bun install # Recommended (fastest)
npm install # Works fine
yarn install # Works fine
pnpm install # Works fine
# ADK auto-detects based on lock files
# - bun.lockb → uses bun
# - package-lock.json → uses npm
# - yarn.lock → uses yarn
# - pnpm-lock.yaml → uses pnpm
// ✅ CORRECT - Always from @botpress/runtime
import { Action, Autonomous, Workflow, z } from "@botpress/runtime";
// ❌ WRONG - Never from zod or @botpress/sdk
import { z } from "zod"; // ❌ Wrong
import { Action } from "@botpress/sdk"; // ❌ Wrong
// ✅ Both patterns work - export const is recommended
export const myAction = new Action({ ... }); // Recommended
export default new Action({ ... }); // Also valid
// Why export const?
// - Enables direct imports: import { myAction } from "./actions/myAction"
// - Can pass to execute(): tools: [myAction.asTool()]
// ✅ CORRECT - Handler receives { input, client }
export const fetchUser = new Action({
name: "fetchUser",
async handler({ input, client }) { // ✅ Destructure from props
const { userId } = input; // ✅ Then destructure fields
return { name: userId };
}
});
// ❌ WRONG - Cannot destructure input fields directly
handler({ userId }) { // ❌ Wrong - must be { input }
return { name: userId };
}
// ✅ CORRECT - Tools CAN destructure directly
export const myTool = new Autonomous.Tool({
handler: async ({ query, maxResults }) => {
// ✅ Direct destructuring OK
return search(query, maxResults);
},
});
// ✅ CORRECT - Use conversation.send() method
await conversation.send({
type: "text",
payload: { text: "Hello!" }
});
// ❌ WRONG - Never use client.createMessage() directly
await client.createMessage({ ... }); // ❌ Wrong
When answering ADK questions, follow this structure:
Example Response Structure:
Actions are strongly-typed functions that can be called from anywhere in your bot.
**Example:**
[code example]
**Common Pitfall:** Remember to destructure `input` first (see troubleshooting section)
**Related:** You can convert Actions to Tools using `.asTool()` - see the "When to Use What" decision tree.
**Next Steps:** Create your action in `src/actions/myAction.ts` and it will be auto-registered.
Weekly Installs
222
Repository
GitHub Stars
6
First Seen
Jan 23, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
codex203
opencode199
gemini-cli191
github-copilot180
amp171
kimi-cli169
AI Elements:基于shadcn/ui的AI原生应用组件库,快速构建对话界面
56,200 周安装