Botpress ADK Guidelines

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, assets, integrations, plugins, evals, or Zai.

What is the ADK?

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:

• Actions & Tools (reusable functions and AI-callable tools)
• Workflows (long-running, resumable processes)
• Conversations (message handling)
• Tables (data storage with semantic search)
• Files (file storage with semantic search)
• Knowledge Bases (RAG implementation)
• Triggers (event-driven automation)
• Assets (static files with permanent URLs)
• Integrations (external service connections managed via CLI and dependency snapshots)
• Plugins (reusable agent extensions with interface dependencies)
• Zai (production-ready LLM utility library for common AI operations)

Project Structure (Convention-Based)

Most primitives must be placed in src/ directory (assets use the assets/ directory at the project root):

/                      # Project root
├── assets/            # Static files → synced to Botpress Cloud with permanent URLs
├── 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)
├── .adk/
│   └── dependencies/
│       ├── dev.json             # Generated dependency snapshot (dev)
│       ├── prod.json            # Generated dependency snapshot (prod)
│       └── migration.json       # One-way legacy migration marker
├── .agent0/
│   └── capabilities/            # Project-local Agent(0) capability bundle
└── agent.config.ts    # Bot configuration

Note: Manage integrations and plugins via the adk integrations / adk plugins CLI or the Dev Console. Botpress Cloud is the source of truth; .adk/dependencies/ contains generated local snapshots for fast/offline reads and should not be edited manually. See integrations.md and plugins.md.

Critical: Files outside src/ are not discovered. Location = behavior.

Session Start

The first time you help with an ADK project in a session, silently check the project's health:

1. Run adk check --format json and adk status --format json. (adk check validates primitives but does not typecheck — also run tsc --noEmit to catch type errors before treating work as done.)
2. If there are errors or warnings (unconfigured integrations, missing models, validation issues), proactively mention them before answering the user's question: "Before we start — I noticed [issue]. Want me to help fix that?"
3. Only do this once per session. Don't re-run on every question.

Available Commands

If the user asks "what can you help with?", "what commands are available?", or invokes /adk-explain without arguments, present:

• Build: /adk-init (scaffold project), /adk-build (interview & build a primitive), /adk-integration (add services), /adk-frontend (build UI)
• Test & Debug: /adk-validate (check a primitive's schema/types/config), /adk-test (invoke a primitive once), /adk-eval (write assertion tests), /adk-debug (fix issues)
• Ship: /adk-ship (pre-flight checks + deploy)
• Document: /adk-document (create, review, update, sync, search)
• Understand: /adk-explain (explain bot architecture and components), /adk-dev-console (navigate the Dev Console)

Then ask: "What are you working on?"

When to Use This Skill

Activate this skill when users ask ADK-related questions like:

• "How do I create an Action/Tool/Workflow/Conversation?"
• "What is the difference between X and Y?"
• "Show me an example of..."
• "How do I configure...?"
• "What's the CLI command for...?"
• "How do I use the Context API?"
• "How do I call integration actions?"
• "How do I use Zai for [extract/check/label/etc]?"
• "What are the best practices for...?"
• "How do I avoid common mistakes?"
• "How do I handle ticket assignment/escalation?"
• "Explain my config"
• "What does my bot do?"
• "What models am I using?"
• "What integrations do I have?"
• "What state does my bot track?"

Plugin Installation Prompt

If you are running inside Claude Code and the /adk-* commands (like /adk-debug, /adk-eval, /adk-init) are not available as slash commands, suggest that the user install the Botpress ADK plugin to get the full set of skills and commands:

/plugin marketplace add botpress/skills
/plugin install adk@botpress-skills

Only suggest this once per session. If the user declines, do not ask again.

How to Answer ADK Questions

ADK questions fall into two categories: CLI queries and documentation lookups.

Option 1: Direct CLI Commands (FAST - Use First!)

For integration discovery and CLI queries, use the Bash tool to run commands directly:

Integration Discovery:

# Search for integrations
adk integrations search <query>

# Find integrations that implement an interface
adk integrations search --interface <interface-name>

# Get detailed integration info (actions, channels, events)
adk integrations info <integration-name>

# Check installed integrations (must be in ADK project)
adk integrations list

Project Info:

# Check CLI version
adk --version

# Show project status
adk

# Get help
adk --help

Prefer non-interactive paths when driving ADK workflows:

# Login without browser prompts
adk login --token "$BOTPRESS_TOKEN"

# Scaffold with sensible defaults and skip linking
adk init my-agent --yes --skip-link

# Link directly when IDs are known
adk link --workspace ws_123 --bot bot_456

# More automation-friendly dev mode (NDJSON events, no TUI)
adk dev --non-interactive

# Review/apply project compatibility updates after ADK upgrades
adk project upgrade --dry-run
adk project upgrade

# Auto-approve non-destructive deploy-plan changes
adk deploy --yes

Use these defaults when relevant:

• Prefer adk login --token "$BOTPRESS_TOKEN" or adk login --token <token> over interactive login.
• Treat bare BOTPRESS_TOKEN as a no-TTY convenience, not a guaranteed interactive-terminal shortcut.
• Prefer adk init <name> --yes --skip-link for AI-driven scaffolding, but only after login is already completed.
• Treat adk link --workspace ... --bot ... as scriptable, but not guaranteed safe in every no-TTY environment.
• Treat adk dev --non-interactive as CI-friendly, not fully prompt-free.
• Treat adk deploy --yes as auto-approving non-destructive deploy-plan changes; config validation and destructive storage changes can still block automation.
• If project commands report a runtime/package mismatch, run adk project upgrade --dry-run first, then adk project upgrade to apply compatibility patches.

When to use CLI commands:

• "What integrations are available?"
• "Search for Slack integration"
• "Show me details about the Linear integration"
• "What actions does the Slack integration have?"
• "What version of ADK am I using?"
• "How do I add an integration?"

Response pattern:

1. Use Bash tool to run the appropriate adk command
2. Parse and present the output to the user
3. Optionally suggest next steps (e.g., "Run adk integrations add [email protected] to install")

Option 2: Documentation Questions (For Conceptual Questions)

For documentation, patterns, and how-to questions, search and reference the documentation files directly:

When to use documentation:

• "How do I create a workflow?"
• "What's the difference between Actions and Tools?"
• "Show me an example of using Zai"
• "What are best practices for state management?"
• "How do I fix this error?"
• "What's the pattern for X?"

How to answer documentation questions:

1. Find relevant files - Use Glob to discover documentation:

`` pattern: **/references/*.md ``

1. Search for keywords - Use Grep to find relevant content:

`` pattern: <keyword from user question> path: <path to references directory from step 1> outputmode: fileswith_matches ``

1. Read the files - Use Read to load relevant documentation

1. Provide answer with:

- Concise explanation - Code examples from the references - File references with line numbers (e.g., "From references/actions.md:215") - Common pitfalls if relevant - Related topics for further reading

Option 3: Config Explanation (CLI + File Reading)

For questions about what a bot does, how it's configured, or what it's capable of, combine CLI and file reading:

When to use:

• "What does my bot do?"
• "Explain my config"
• "What models am I using?"
• "What integrations do I have?"
• "What state does my bot track?"

Response pattern:

1. Run adk status --format json to get the structured project overview
2. Read agent.config.ts for full configuration details
3. Follow the explanation patterns in references/explain-config.md
4. Produce a structured explanation covering metadata, models, integrations, state, and primitives
5. Flag any issues (unconfigured integrations, missing models, hardcoded secrets)

Available Documentation

Documentation should be located in ./references/ directory relative to this skill. When answering questions, search for these topics:

Core Concepts

• actions.md - Actions with strong typing and validation
• tools.md - AI-callable tools and Autonomous namespace
• autonomous-execution.md - Advanced execute() API: Objects, Exits, hooks, configuration
• workflows.md - Workflows and step-based execution
• workflow-steps.md - Complete Workflow Step API reference (step.request, step.map, step.notify, etc.)
• conversations.md - Conversation handlers, message routing, and receiving chat:custom events
• conversation-lifecycle.md - Nudge/expiration lifecycle management for conversations
• triggers.md - Integration & bot-lifecycle event subscriptions (app-pushed custom events → conversations.md)
• messages.md - Sending messages and events
• custom-components.md - Custom webchat components (.bp.tsx files, metadata, usage in conversations)

Zai (AI Operations)

• zai-agent-reference.md - Quick reference: all operations, everyday problems Zai solves, edge cases & gotchas
• zai-complete-guide.md - Full developer guide: architecture, active learning, chunking, performance tuning

Data & Content

• tables.md - Data storage with semantic search
• files.md - File storage and management
• knowledge-bases.md - RAG implementation
• assets.md - Static files with permanent URLs and sync lifecycle

Configuration & Integration

• agent-config.md - Bot configuration and state management
• explain-config.md - How to interpret and explain an agent's configuration to developers
• model-configuration.md - AI model configuration reference
• context-api.md - Runtime context access
• integration-actions.md - Using integration actions
• tags.md - Entity tags for bot, user, conversation, and workflow
• cli.md - Complete CLI command reference
• mcp-server.md - MCP server for AI assistants
• desk.md - Desk integration for ticket/support workflows
• integrations.md - Integration management overview (points to adk-integrations skill)
• interfaces.md - Built-in interface abstraction layer over integrations (typing indicators, LLM, listable)
• plugins.md - Plugin consumption: discovery, installation, configuration, and usage

Patterns & Best Practices

• advanced-patterns.md - Guardrails, admin auth, logging/observability, extension composition
• patterns-mistakes.md - Common mistakes, correct patterns, and context access reference

Frontend Integration

Note: Frontend integration docs are in the separate adk-frontend skill. Install it with npx skills add botpress/skills --skill adk-frontend. The adk-frontend skill covers @botpress/client, calling actions, type generation, and authentication. You need it if you are touching any frontend code.

Evals

Note: Detailed eval docs are in the separate adk-evals skill. Install it with npx skills add botpress/skills --skill adk-evals. The adk-evals skill covers writing evals, assertion types, testing workflows, and CLI usage. You usually always need it, for testing and evaluations.

Runtime Access Patterns

Quick reference for accessing ADK runtime services:

Imports

// Always import from @botpress/runtime
import {
  Action,
  Autonomous,
  Workflow,
  Conversation,
  z,
  actions,
  adk,
  user,
  bot,
  conversation,
  configuration,
  context,
} from '@botpress/runtime'

State Management

// 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

Calling Actions

// 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()]

Context API

// 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

File Naming

• Actions/Tools/Workflows: myAction.ts, searchDocs.ts (camelCase)
• Tables: Users.ts, Orders.ts (PascalCase)
• Conversations/Triggers: chat.ts, slack.ts (lowercase)

Critical ADK Patterns (Always Reference in Answers)

When answering questions, always verify these patterns against the documentation:

Package Management

# 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

Imports

// ✅ 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

Export Patterns

// ✅ 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()]

Actions

// ✅ 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 };
}

Tools

// ✅ CORRECT - Tools CAN destructure directly
export const myTool = new Autonomous.Tool({
  handler: async ({ query, maxResults }) => {
    // ✅ Direct destructuring OK
    return search(query, maxResults)
  },
})

Conversations

// ✅ CORRECT - Use conversation.send() method
await conversation.send({
  type: "text",
  payload: { text: "Hello!" }
});

// ❌ WRONG - Never use client.createMessage() directly
await client.createMessage({ ... });  // ❌ Wrong

Conversation Handler Types

// Handler receives typed context based on the event type:
// type: "message" | "event" | "workflow_request" | "workflow_callback"
async handler({ type, message, event, request, completion, conversation, execute }) {
  if (type === "workflow_request") {
    // event: WorkflowDataRequestEventType, request: WorkflowRequest
    await request.workflow.provide("email", { email: "..." });
  }
  if (type === "workflow_callback") {
    // event: WorkflowCallbackEventType, completion: WorkflowCallback
    console.log(completion.status); // "completed" | "failed" | "canceled" | "timed_out"
  }
}

// ⚠️ isWorkflowDataRequest() and isWorkflowCallback() are deprecated
// Use type === "workflow_request" / "workflow_callback" instead

Examples of Questions This Skill Answers

Beginner Questions

• "What is an Action?"
• "How do I create my first workflow?"
• "What's the difference between Actions and Tools?"

Implementation Questions

• "How do I access the Botpress client?"
• "How do I use citations in RAG?"
• "What's the syntax for searchable table columns?"
• "How do I call a Slack integration action?"
• "How do I use Zai to extract structured data?"
• "How do I validate content with Zai?"

Advanced Pattern Questions

• "How do I add guardrails to prevent hallucinations?"
• "How do I implement admin authentication?"
• "How do I add logging and observability?"
• "How do I compose multiple extensions?"
• "How do I manage context in async tool handlers?"

Troubleshooting Questions

• "Why am I getting 'Cannot destructure property' error?"
• "How do I fix import errors?"
• "What's wrong with my workflow state access?"

Best Practices Questions

• "What are common mistakes to avoid?"
• "How should I structure my project?"
• "What's the recommended pattern for X?"

Response Format

Match your response depth to the question depth. Not every question needs a full walkthrough.

Conceptual Questions ("what is X?", "what's the difference between X and Y?")

One sentence definition + one short code example. That's it.

Knowledge bases add RAG to your bot — place markdown or PDF files in `src/knowledge/` and they become queryable with semantic search.

import { Autonomous } from '@botpress/runtime'
export default new Autonomous.Tool({
  handler: async ({ query }) => adk.knowledgeBase.search({ query }),
})

How-To Questions ("how do I create X?", "how do I use X?")

Brief explanation + working code example + one critical pitfall only if it's a common trap.

Implementation Questions ("implement X in my project", "add X to my bot")

Read the user's existing files first (src/actions/, src/tools/, src/tables/, agent.config.ts). Generate code that uses their actual names, patterns, and conventions. Only mention pitfalls they're likely to hit given their specific code.

Architecture Questions ("explain my bot", "how does X work in my project?")

Full structured response: read adk status --format json, agent.config.ts, and relevant source files. Map the data flow and identify the bot's archetype (RAG assistant, support agent, automation, etc.).

Troubleshooting Questions ("X is broken", "why is X failing?")

Don't answer with documentation. Run adk check --format json and adk logs error --format json, show evidence, and point to the root cause. Follow the debug loop from the adk-debugger skill.

Default Rule

If the answer fits in one sentence and a code snippet, don't add headers, pitfall sections, or related topics. More structure ≠ more helpful.