viralcode/openwhale/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:

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:

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"

Verify installation:

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:

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:

# 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.

1. `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.

1. `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.

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 conversations and users
  bot: {
    state: z.object({
      maintenanceMode: z.boolean().default(false),
      totalConversations: z.number().default(0)
    })
  },
  // Per-user state - persists across all conversations for each user
  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()
    }
  },
  // Per-conversation state
  conversation: {
    state: z.object({
      context: z.string().optional()
    }),
    tags: {
      category: z.enum(["support", "sales", "general"]),
      priority: z.enum(["low", "medium", "high"]).optional()
    }
  },
  // Integrations your bot uses (ADK 1.9+ format)
  dependencies: {
    integrations: {
      chat: { version: "chat@0.7.3", enabled: true },
      slack: { version: "slack@2.5.5", enabled: true }
    }
  }
});

Available models:

• 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

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

Core Concepts

1. Actions - Reusable Business Logic

When to create an Action:

• You need reusable logic that will be called from multiple places (workflows, conversations, triggers)
• You're wrapping an external API or database operation
• You want testable, composable business logic
• You need to call integration APIs (Slack, Linear, etc.) with custom logic

When NOT to use an Action (use a Tool instead):

• You want the AI to decide when to call it autonomously
• The function should be available during execute()

Actions are not directly callable by the AI - convert them to tools with .asTool() if the AI needs to use them.

Location: src/actions/*.ts

import { Action, z } from "@botpress/runtime";