Adk

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, 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)
• Zai (production-ready LLM utility library for common AI operations)

Project Structure (Convention-Based)

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.json was removed in ADK 1.9+. All configuration including integrations now lives in agent.config.ts.

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

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?"

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

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
adk dev --logs --no-open

# Auto-approve preflight changes only
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 --logs --no-open as CI-friendly, not fully prompt-free.
• Treat adk deploy --yes as auto-approving preflight only; config validation can still block automation.

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 add slack@3.0.0 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
   

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

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

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

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
• workflows.md - Workflows and step-based execution
• conversations.md - Conversation handlers and message routing
• triggers.md - Event-driven automation
• messages.md - Sending messages and events

Data & Content

• tables.md - Data storage with semantic search
• files.md - File storage and management
• knowledge-bases.md - RAG implementation
• zai-complete-guide.md - Complete ZAI developer guide
• zai-agent-reference.md - Quick ZAI reference

Configuration & Integration

• agent-config.md - Bot configuration and state management
• 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)

Patterns & Best Practices

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

Integration Management

Note: Full integration lifecycle docs (discovery, adding, configuring, and using integrations) are in the separate adk-integrations skill. Install it with npx skills add botpress/skills --skill adk-integrations. The adk-integrations skill covers adk search, adk add, adk info, configuration types, and common integrations. You need it if you are touching integrations.

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

When answering ADK questions, follow this structure:

1. Start with a concise explanation - Answer the core question directly
2. Provide working code examples - Use examples from references or create based on patterns
3. Include file references - Cite documentation (e.g., "From actions.md:215")
4. Highlight common pitfalls - Reference the troubleshooting section if relevant
5. Security & best practices - Mention security considerations when applicable
6. Link to related topics - Suggest further reading or related concepts

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.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.