botpress-adk

---
name: adk
description: A guide to build AI bots with Botpress's Agent Development Kit (ADK)
version: 1.0.0
author: yueranlu
tags: [botpress, adk, chatbot, ai, typescript]
homepage: https://github.com/botpress/adk
---

# Botpress ADK Development Guide

A comprehensive guide for building AI bots with the Botpress Agent Development Kit (ADK).

## When to Use

- User asks to build a Botpress bot or chatbot
- User mentions ADK, Agent Development Kit, or Botpress
- User wants to create actions, tools, workflows, conversations, tables, triggers, or knowledge bases
- User needs help with `adk` CLI commands (init, dev, deploy, link)
- User has ADK-related errors or needs troubleshooting
- User asks about bot configuration, state management, or integrations

## Quick Reference

The ADK is a **convention-based TypeScript framework** where **file structure maps directly to bot behavior**.

**Your role:** Guide users through the entire bot development lifecycle - from project setup to deployment. Use the patterns and code examples in this skill to write correct, working ADK code.

**Key principle:** In ADK, **where you put files matters**. Each component type has a specific `src/` subdirectory, and files are auto-discovered based on location.

## How to Use This Skill

**This skill is your primary reference for building Botpress bots.** When a user asks you to build something with the ADK:

1. **Identify what they need** - Is it a new bot, a feature (action, tool, workflow), data storage (table), or event handling (trigger)?
2. **Check the correct directory** - Each component type goes in a specific `src/` subdirectory
3. **Use the patterns below** - Follow the code examples exactly, they represent the correct ADK conventions
4. **Run `adk --help`** - For CLI commands not covered here, or `adk <command> --help` for specific help

**Decision Guide - What Component to Create:**

| User Wants To... | Create This | Location |
|------------------|-------------|----------|
| Handle user messages | Conversation | `src/conversations/` |
| Add a function the AI can call | Tool | `src/tools/` |
| Add reusable business logic | Action | `src/actions/` |
| Run background/scheduled tasks | Workflow | `src/workflows/` |
| Store structured data | Table | `src/tables/` |
| React to events (user created, etc.) | Trigger | `src/triggers/` |
| Give AI access to docs/data | Knowledge Base | `src/knowledge/` |
| Connect external service (Slack, etc.) | Integration | `adk add <name>` |

**If the information in this skill isn't enough**, fetch the corresponding GitHub reference file (links provided in each section) for more detailed specifications.

## Important: ADK is AI-Native

The ADK does **NOT** use traditional chatbot patterns. Don't create intents, entities, or dialog flows.

**Instead of:**
- Defining intents (`greet`, `orderPizza`, `checkStatus`)
- Training entity extraction (`@pizzaSize`, `@toppings`)
- Manually routing to intent handlers

**ADK uses:**
- `execute()` - The AI understands user intent naturally from instructions
- Tools - AI autonomously decides when to call your functions
- `zai.extract()` - Schema-based structured data extraction
- Knowledge bases - RAG for grounding responses in your docs

**Docs:** https://www.botpress.com/docs/adk/
**GitHub:** https://github.com/botpress/skills/tree/master/skills/adk

---

## Prerequisites & Installation

Before using the ADK, ensure the user has:

- **Botpress Account** - Create at https://app.botpress.cloud
- **Node.js v22.0.0+** - Check with `node --version`
- **Package Manager** - bun (recommended), pnpm, yarn, or npm

**Install the ADK CLI:**

macOS & Linux:
```bash
curl -fsSL https://github.com/botpress/adk/releases/latest/download/install.sh | bash
```

Windows (PowerShell):
```powershell
powershell -c "irm https://github.com/botpress/adk/releases/latest/download/install.ps1 | iex"
```

**Verify installation:**
```bash
adk --version
```

If installation fails, check https://github.com/botpress/adk/releases for manual download options.

**Docs:** https://www.botpress.com/docs/adk/quickstart
**GitHub:** https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/cli.md

---

## Quick Start

Once the ADK CLI is installed, create a new bot:

```bash
adk init my-bot         # Create project (choose "Hello World" template for beginners)
cd my-bot
npm install             # Or bun/pnpm/yarn
adk login               # Authenticate with Botpress Cloud
adk add chat            # Add the chat integration for testing
adk dev                 # Start dev server with hot reload
adk chat                # Test in CLI (run in separate terminal)
adk deploy              # Deploy to production when ready
```

The visual console at **http://localhost:3001/** lets you configure integrations and test the bot.

**Docs:** https://www.botpress.com/docs/adk/quickstart
**GitHub:** https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/cli.md

---

## Linking and Deploying Your Bot

**IMPORTANT:** Your bot must be linked to Botpress Cloud and deployed for it to work. The ADK runs locally during development but the bot itself lives in Botpress Cloud.

### The Correct Order: Link → Dev → Deploy

Follow this order to get your bot working:

```bash
# 1. LINK - Connect your project to Botpress Cloud (creates agent.json)
adk link

# 2. DEV - Start the development server (hot reload, testing)
adk dev

# 3. DEPLOY - Push to production when ready
adk deploy
```

**Step-by-step:**

1. **`adk link`** - Links your local project to a bot in Botpress Cloud. This creates `agent.json` with your workspace and bot IDs. Run this first before anything else.

2. **`adk dev`** - Starts the local development server with hot reloading. Opens the dev console at http://localhost:3001 where you can configure integrations and test your bot. Use `adk chat` in a separate terminal to test.

3. **`adk deploy`** - Deploys your bot to production. Run this when you're ready for your bot to be live and accessible through production channels (Slack, WhatsApp, webchat, etc.).

### Troubleshooting Errors

**If you encounter errors when running `adk dev` or `adk deploy`:**

1. **Check the logs** - Look at the terminal output or the logs panel in the dev console at http://localhost:3001
2. **Copy the error message** - Select and copy the full error message from the logs
3. **Ask for help** - Paste the error back to the AI assistant and ask it to help fix the issue

Common error scenarios:
- **Integration configuration errors:** Usually means an integration needs to be configured in the UI at localhost:3001
- **Type errors:** Often caused by incorrect imports or schema mismatches
- **Deployment failures:** May indicate missing environment variables or invalid configuration

**Example workflow for fixing errors:**
```
1. Run `adk dev` or `adk deploy`
2. See error in terminal/logs
3. Copy the error message
4. Tell the AI: "I got this error when running adk dev: [paste error]"
5. The AI will help diagnose and fix the issue
```

**Docs:** https://www.botpress.com/docs/adk/quickstart
**GitHub:** https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/cli.md

---

## Project Structure

**Critical rule:** File location determines behavior. Place components in the correct `src/` subdirectory or they won't be discovered.

```
my-bot/
├── agent.config.ts    # Bot configuration: name, models, state schemas, integrations
├── agent.json         # Workspace/bot IDs (auto-generated by adk link/dev, add to .gitignore)
├── package.json       # Node.js dependencies and scripts (dev, build, deploy)
├── tsconfig.json      # TypeScript configuration
├── .env               # API keys and secrets (never commit!)
├── .gitignore         # Should include: agent.json, .env, node_modules/, .botpress/
├── src/
│   ├── conversations/ # Handle incoming messages → use execute() for AI responses
│   ├── workflows/     # Background processes → use step() for resumable operations
│   ├── actions/       # Reusable functions → call from anywhere with actions.name()
│   ├── tools/         # AI-callable functions → AI decides when to invoke these
│   ├── tables/        # Data storage → auto-synced to cloud, supports semantic search
│   ├── triggers/      # Event handlers → react to user.created, integration events, etc.
│   └── knowledge/     # RAG sources → index docs, websites, or tables for AI context
└── .botpress/         # Auto-generated types (never edit manually)
```

**Key Configuration Files:**

- **agent.config.ts** - Primary configuration defining bot metadata, AI models, state schemas, and integrations (you edit this)
- **agent.json** - Links agent to workspace/bot IDs. Auto-generated by `adk link` or `adk dev`. **Add to .gitignore** - contains environment-specific IDs that differ per developer
- **package.json** - Node.js config with `@botpress/runtime` dependency and scripts for `dev`, `build`, `deploy`
- **tsconfig.json** - TypeScript configuration for the project
- **.env** - Environment variables for API keys and secrets (never commit!)
- **.gitignore** - Should include: `agent.json`, `.env`, `node_modules/`, `.botpress/`

**Docs:** https://www.botpress.com/docs/adk/project-structure
**GitHub:** https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/agent-config.md

---

## Agent Configuration

The `agent.config.ts` file defines your bot's identity, AI models, state schemas, and integrations. Always start here when setting up a new bot.

```typescript
import { defineConfig, z } from "@botpress/runtime";

export default defineConfig({
  name: "my-support-bot",
  description: "AI customer support assistant",

  // AI models for different operations
  defaultModels: {
    autonomous: "openai:gpt-4o",      // Used by execute() for conversations
    zai: "openai:gpt-4o-mini"         // Used by zai operations (cheaper, faster)
  },

  // Global bot state - shared across all conversa

... (truncated)