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

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

adk --version

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

# 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

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

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)

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 }
    }
  }
});

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

export const fetchUser = new Action({
  name: "fetchUser",
  description: "Retrieves user details from the database",

  // Define input/output with Zod schemas for type safety
  input: z.object({ userId: z.string() }),
  output: z.object({ name: z.string(), email: z.string() }),

  // IMPORTANT: Handler receives { input, client } - destructure input INSIDE the handler
  async handler({ input, client }) {
    const { user } = await client.getUser({ id: input.userId });
    return { name: user.name, email: user.tags.email };
  }
});

import { actions } from "@botpress/runtime";
const userData = await actions.fetchUser({ userId: "123" });

// To make an action callable by the AI, convert it to a tool:
tools: [actions.fetchUser.asTool()]

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

export const searchProducts = new Autonomous.Tool({
  name: "searchProducts",
  // This description is critical - it tells the AI when to use this tool
  description: "Search the product catalog. Use when user asks about products, availability, pricing, or wants to browse items.",

  input: z.object({
    query: z.string().describe("Search keywords"),
    category: z.string().optional().describe("Filter by category")
  }),
  output: z.object({
    products: z.array(z.object({ id: z.string(), name: z.string(), price: z.number() }))
  }),

  // Unlike actions, tools CAN destructure input directly in the handler
  handler: async ({ query, category }) => {
    // Your search logic here
    return { products: [] };
  }
});

import { Autonomous } from "@botpress/runtime";

// Inside handler - AI will see this message and can respond appropriately
throw new Autonomous.ThinkSignal(
  "No results found",
  "No products found matching that query. Ask user to try different search terms."
);

export const myTool = new Autonomous.Tool({
  name: "myTool",
  description: "Tool description",
  input: z.object({...}),
  output: z.object({...}),
  aliases: ["searchDocs", "findDocs"],  // Alternative names
  handler: async (input, ctx) => {
    console.log(`Call ID: ${ctx.callId}`);  // Unique call identifier
    // ...
  },
  retry: async ({ attempt, error }) => {
    if (attempt < 3 && error?.code === 'RATE_LIMIT') {
      await new Promise(r => setTimeout(r, 1000 * attempt));
      return true;  // Retry
    }
    return false;  // Don't retry
  }
});

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

export const Chat = new Conversation({
  // Which channels this handler responds to
  channel: "chat.channel",  // Or "*" for all, or ["slack.dm", "webchat.channel"]

  // Per-conversation state (optional)
  state: z.object({
    messageCount: z.number().default(0)
  }),

  async handler({ message, state, conversation, execute, user }) {
    state.messageCount += 1;

    // Handle commands
    if (message?.payload?.text?.startsWith("/help")) {
      await conversation.send({
        type: "text",
        payload: { text: "Available commands: /help, /status" }
      });
      return;
    }

    // Let the AI handle the response with your tools and knowledge
    await execute({
      // Instructions guide the AI's behavior and personality
      instructions: `You are a helpful customer support agent for Acme Corp.
        User's name: ${user.state.name || "there"}
        User's tier: ${user.state.tier}
        Be friendly, concise, and always offer to help further.`,

      // Tools the AI can use during this conversation
      tools: [searchProducts, actions.createTicket.asTool()],

      // Knowledge bases for RAG - AI will search these to ground responses
      knowledge: [DocsKnowledgeBase],

      model: "openai:gpt-4o",
      temperature: 0.7,
      iterations: 10  // Max tool call iterations
    });
  }
});

await execute({
  instructions: string | async function,  // Required
  tools: Tool[],                          // AI-callable tools
  knowledge: Knowledge[],                 // Knowledge bases for RAG
  exits: Exit[],                          // Structured exit handlers
  model: string,                          // AI model to use
  temperature: number,                    // 0-1, default 0.7
  iterations: number,                     // Max tool calls, default 10
  hooks: {
    onBeforeTool: async ({ tool, input }) => { ... },
    onAfterTool: async ({ tool, output }) => { ... },
    onTrace: async (trace) => { ... }
  }
});

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

export const ProcessOrderWorkflow = new Workflow({
  name: "processOrder",
  description: "Processes customer orders",
  timeout: "6h",                    // Max duration
  schedule: "0 9 * * *",            // Optional: run daily at 9am (cron syntax)

  input: z.object({
    orderId: z.string(),
    conversationId: z.string()      // Include this to message the user back!
  }),

  state: z.object({
    currentStep: z.number().default(0),
    processedItems: z.array(z.string()).default([])
  }),

  output: z.object({
    success: z.boolean(),
    itemsProcessed: z.number()
  }),

  async handler({ input, state, step, client, execute }) {
    // State is passed as parameter, auto-tracked
    state.currentStep = 1;

    // IMPORTANT: Each step needs a unique, stable name (no dynamic names!)
    const orderData = await step("fetch-order", async () => {
      return await fetchOrderData(input.orderId);
    });

    // Steps can have retry logic
    await step("process-payment", async () => {
      return await processPayment(orderData);
    }, { maxAttempts: 3 });

    // To message the user from a workflow, use client.createMessage (NOT conversation.send)
    await step("notify-user", async () => {
      await client.createMessage({
        conversationId: input.conversationId,
        type: "text",
        payload: { text: "Your order has been processed!" }
      });
    });

    return {
      success: true,
      itemsProcessed: state.processedItems.length
    };
  }
});

// Start a workflow from a conversation or trigger
await ProcessOrderWorkflow.start({
  orderId: "123",
  conversationId: conversation.id  // Always pass this if you need to message back
});

// Get or create with deduplication
const instance = await ProcessOrderWorkflow.getOrCreate({
  key: `order-${orderId}`,  // Prevents duplicate workflows
  input: { orderId, conversationId }
});

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

export const OrdersTable = new Table({
  name: "OrdersTable",  // Must end with "Table"
  description: "Stores order information",
  columns: {
    // NO id column - it's automatic!
    orderId: z.string(),
    userId: z.string(),
    status: z.enum(["pending", "completed", "cancelled"]),
    total: z.number(),
    createdAt: z.date(),
    // Enable semantic search on a column:
    notes: {
      schema: z.string(),
      searchable: true
    }
  }
});

// Create - id is auto-assigned
await OrdersTable.createRows({
  rows: [{ orderId: "ord-123", userId: "user-456", status: "pending", total: 99.99, createdAt: new Date() }]
});

// Read with filters
const { rows } = await OrdersTable.findRows({
  filter: { userId: "user-456", status: "pending" },
  orderBy: "createdAt",
  orderDirection: "desc",
  limit: 10
});

// Get single row by id
const row = await OrdersTable.getRow({ id: 123 });

// Semantic search (on searchable columns)
const { rows } = await OrdersTable.findRows({
  search: "delivery issue",
  limit: 5
});

// Update - must include the id
await OrdersTable.updateRows({
  rows: [{ id: 1, status: "completed" }]
});

// Upsert - insert or update based on key column
await OrdersTable.upsertRows({
  rows: [{ orderId: "ord-123", status: "shipped" }],
  keyColumn: "orderId"
});

// Delete by filter
await OrdersTable.deleteRows({ status: "cancelled" });

// Delete by IDs
await OrdersTable.deleteRowIds([123, 456]);

columns: {
  basePrice: z.number(),
  taxRate: z.number(),
  fullPrice: {
    computed: true,
    schema: z.number(),
    dependencies: ["basePrice", "taxRate"],
    value: async (row) => row.basePrice * (1 + row.taxRate)
  }
}

import { Knowledge, DataSource } from "@botpress/runtime";

// Website source - index via sitemap
const websiteSource = DataSource.Website.fromSitemap(
  "https://docs.example.com/sitemap.xml",
  {
    id: "website-docs",
    maxPages: 500,
    maxDepth: 10,
    filter: (ctx) => ctx.url.includes("/docs/")  // Only index /docs/ pages
  }
);

// Local files (development only - won't work in production)
const localSource = DataSource.Directory.fromPath("src/knowledge/docs", {
  id: "local-docs",
  filter: (path) => path.endsWith(".md")
});

// Table-based knowledge
const tableSource = DataSource.Table.fromTable(FAQTable, {
  id: "faq-table",
  transform: ({ row }) => `Question: ${row.question}\nAnswer: ${row.answer}`,
  filter: ({ row }) => row.published === true
});

export const DocsKB = new Knowledge({
  name: "docsKB",
  description: "Product documentation and help articles",
  sources: [websiteSource, localSource, tableSource]
});

// Use in conversations - AI will search this knowledge base
await execute({
  instructions: "Answer based on the documentation",
  knowledge: [DocsKB]
});

// Manually refresh knowledge base
await DocsKB.refresh();                  // Smart refresh (only changed content)
await DocsKB.refresh({ force: true });   // Force full re-index
await DocsKB.refreshSource("website-docs", { force: true });  // Refresh specific source

import { Trigger } from "@botpress/runtime";

export default new Trigger({
  name: "onNewUser",
  description: "Start onboarding when user created",
  events: ["user.created"],  // Can listen to multiple events

  handler: async ({ event, client, actions }) => {
    const { userId, email } = event.payload;

    // Start an onboarding workflow
    await OnboardingWorkflow.start({
      userId,
      email
    });
  }
});

// Integration events use format: integration:eventName
export const LinearTrigger = new Trigger({
  name: "onLinearIssue",
  description: "Handle Linear issue events",
  events: ["linear:issueCreated", "linear:issueUpdated"],

  handler: async ({ event, actions }) => {
    if (event.type === "linear:issueCreated") {
      await actions.slack.sendMessage({
        channel: "#notifications",
        text: `New issue: ${event.payload.title}`
      });
    }
  }
});

await conversation.send({ type: "text", payload: { text: "Hello!" } });
await conversation.send({ type: "image", payload: { imageUrl: "https://..." } });
await conversation.send({
  type: "choice",
  payload: {
    text: "Pick one:",
    choices: [
      { title: "Option A", value: "a" },
      { title: "Option B", value: "b" }
    ]
  }
});

await client.createMessage({
  conversationId: input.conversationId,  // Must have this!
  type: "text",
  payload: { text: "Workflow complete!" }
});

// Text
{ type: "text", payload: { text: "Hello!" } }

// Markdown
{ type: "markdown", payload: { text: "# Heading\n**Bold**" } }

// Image
{ type: "image", payload: { imageUrl: "https://..." } }

// Audio
{ type: "audio", payload: { audioUrl: "https://..." } }

// Video
{ type: "video", payload: { videoUrl: "https://..." } }

// File
{ type: "file", payload: { fileUrl: "https://...", title: "Document.pdf" } }

// Location
{ type: "location", payload: { latitude: 40.7128, longitude: -74.0060, address: "New York, NY" } }

// Card
{ type: "card", payload: {
  title: "Product Name",
  subtitle: "Description",
  imageUrl: "https://...",
  actions: [
    { action: "url", label: "View", value: "https://..." },
    { action: "postback", label: "Buy", value: "buy_123" }
  ]
}}

// Carousel
{ type: "carousel", payload: {
  items: [
    { title: "Item 1", subtitle: "...", imageUrl: "...", actions: [...] },
    { title: "Item 2", subtitle: "...", imageUrl: "...", actions: [...] }
  ]
}}

// Choice (Quick Replies)
{ type: "choice", payload: {
  text: "Select an option:",
  choices: [
    { title: "Option 1", value: "opt1" },
    { title: "Option 2", value: "opt2" }
  ]
}}

// Dropdown
{ type: "dropdown", payload: {
  text: "Select country:",
  options: [
    { label: "United States", value: "us" },
    { label: "Canada", value: "ca" }
  ]
}}

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

// Extract structured data from text
const contact = await adk.zai.extract(
  "Contact John at john@example.com, phone 555-0100",
  z.object({
    name: z.string(),
    email: z.string(),
    phone: z.string()
  })
);
// Returns: { name: "John", email: "john@example.com", phone: "555-0100" }

// Check if text matches a condition (returns boolean)
const isSpam = await adk.zai.check(messageText, "is spam or promotional");

// Label text with multiple criteria
const labels = await adk.zai.label(customerEmail, {
  spam: "is spam",
  urgent: "needs immediate response",
  complaint: "expresses dissatisfaction"
});
// Returns: { spam: false, urgent: true, complaint: true }

// Summarize content
const summary = await adk.zai.summarize(longDocument, {
  length: 200,
  bulletPoints: true
});

// Answer questions from documents (with citations)
const result = await adk.zai.answer(docs, "What is the refund policy?");
if (result.type === "answer") {
  console.log(result.answer);
  console.log(result.citations);
}
// Response types: "answer", "ambiguous", "out_of_topic", "invalid_question", "missing_knowledge"

// Rate items on 1-5 scale
const scores = await adk.zai.rate(products, "quality score");

// Sort by criteria
const sorted = await adk.zai.sort(tickets, "by urgency, most urgent first");

// Group items semantically
const groups = await adk.zai.group(emails, {
  instructions: "categorize by topic"
});

// Rewrite text
const professional = await adk.zai.rewrite("hey wassup", "make it professional and friendly");

// Filter arrays
const activeUsers = await adk.zai.filter(users, "have been active this month");

// Generate text
const blogPost = await adk.zai.text("Write about AI in healthcare", {
  length: 1000,
  temperature: 0.7
});

// Patch code files
const patched = await adk.zai.patch(files, "add JSDoc comments to all functions");

// Create configured instance
const preciseZai = adk.zai.with({
  modelId: "best",        // "best" | "fast" | custom model ID
  temperature: 0.1
});

// Enable active learning
const learningZai = adk.zai.learn("sentiment-analysis");

// Convert any integration action to an AI-callable tool
tools: [actions.slack.sendMessage.asTool()]

adk search slack           # Find integrations
adk add slack@latest       # Add to project
adk add slack --alias my-slack  # Add with custom alias
adk info slack --events    # See available events
adk list                   # List installed integrations
adk upgrade slack          # Update to latest
adk remove slack           # Remove integration

import { actions } from "@botpress/runtime";

// Slack
await actions.slack.sendMessage({ channel: "#general", text: "Hello!" });
await actions.slack.addReaction({ channel: "C123", timestamp: "123", name: "thumbsup" });

// Linear
await actions.linear.issueCreate({ teamId: "123", title: "Bug report", description: "Details" });
const { items } = await actions.linear.issueList({
  first: 10,
  filter: { state: { name: { eq: "In Progress" } } }
});

// GitHub
await actions.github.createIssue({ owner: "org", repo: "repo", title: "Issue" });

// Browser (web scraping)
const results = await actions.browser.webSearch({ query: "Botpress docs", maxResults: 5 });

// Make integration actions available to AI as tools
await execute({ tools: [actions.slack.sendMessage.asTool()] });

import { bot, user, conversation } from "@botpress/runtime";

// Bot state - global, shared across all users
bot.state.maintenanceMode = true;
bot.state.totalConversations += 1;

// User state - per user, persists across conversations
user.state.name = "Alice";
user.state.tier = "pro";
user.state.preferredLanguage = "es";

// In handlers, state is passed as a parameter
async handler({ state }) {
  state.messageCount += 1;  // Auto-persisted
}

// Tags - simple string key-value pairs for categorization
user.tags.source = "website";
user.tags.region = "north-america";
conversation.tags.category = "support";
conversation.tags.priority = "high";

import { context } from "@botpress/runtime";

// Always available
const client = context.get("client");           // Botpress API client
const citations = context.get("citations");     // Citation manager
const cognitive = context.get("cognitive");     // LLM client
const logger = context.get("logger");           // Structured logger
const botId = context.get("botId");            // Current bot ID
const configuration = context.get("configuration");  // Bot config

// Conditionally available (use { optional: true })
const user = context.get("user", { optional: true });
const conversation = context.get("conversation", { optional: true });
const message = context.get("message", { optional: true });
const workflow = context.get("workflow", { optional: true });
const chat = context.get("chat", { optional: true });  // Conversation transcript

if (user) {
  console.log(`User: ${user.id}`);
}

# Project Lifecycle
adk init <name>              # Create new project
adk login                    # Authenticate with Botpress
adk dev                      # Start dev server (hot reload)
adk dev --port 3000          # Custom port
adk chat                     # Test in CLI
adk build                    # Build for production
adk deploy                   # Deploy to Botpress Cloud
adk deploy --env production  # Deploy to specific environment

# Integration Management
adk add <integration>        # Add integration
adk add slack@2.5.5          # Add specific version
adk add slack --alias my-slack  # Add with alias
adk remove <integration>     # Remove integration
adk search <query>           # Search integrations
adk list                     # List installed integrations
adk list --available         # List all available
adk info <name>              # Integration details
adk info <name> --events     # Show available events
adk upgrade <name>           # Update integration
adk upgrade                  # Interactive upgrade all

# Knowledge & Assets
adk kb sync --dev            # Sync knowledge bases
adk kb sync --prod --force   # Force re-sync production
adk assets sync              # Sync static files

# Advanced
adk run <script.ts>          # Run TypeScript script
adk mcp                      # Start MCP server
adk link --workspace ws_123 --bot bot_456  # Link to existing bot

# Utilities
adk self-upgrade             # Update CLI
adk telemetry --disable      # Disable telemetry
adk --help                   # Full CLI help
adk <command> --help         # Help for specific command

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

// Define custom tool
const searchTool = new Autonomous.Tool({
  name: "search",
  description: "Search documentation",
  input: z.object({ query: z.string() }),
  output: z.string(),
  handler: async ({ query }) => {
    // Search implementation
    return "results...";
  }
});

// Define exit (structured response)
const AnswerExit = new Autonomous.Exit({
  name: "Answer",
  description: "Provide final answer to the user",
  schema: z.object({
    answer: z.string(),
    confidence: z.number(),
    sources: z.array(z.string())
  })
});

// Execute AI with tools, knowledge, and exits
const result = await execute({
  instructions: "Help the user with their request. Be helpful and concise.",

  // Add tools
  tools: [
    searchTool,
    actions.linear.issueCreate.asTool()
  ],

  // Add knowledge bases
  knowledge: [DocsKnowledgeBase, FAQKnowledgeBase],

  // Define exits for structured outputs
  exits: [AnswerExit],

  // Model configuration
  model: "openai:gpt-4o",
  temperature: 0.7,
  iterations: 10,  // Max tool call iterations

  // Hooks for monitoring
  hooks: {
    onBeforeTool: async ({ tool, input }) => {
      console.log(`Calling ${tool.name}`, input);
      return { input: { ...input, enhanced: true } };  // Modify input
    },
    onAfterTool: async ({ tool, output }) => {
      console.log(`Result:`, output);
    }
  }
});

// Handle structured exit
if (result.is(AnswerExit)) {
  console.log(result.output.answer);
  console.log(result.output.sources);
}

// In conversation - starting a workflow that needs to message back
await MyWorkflow.start({
  conversationId: conversation.id,  // Always include this!
  data: "..."
});

// In workflow - messaging back to user
await client.createMessage({
  conversationId: input.conversationId,
  type: "text",
  payload: { text: "Processing complete!" }
});

// In .env (never commit!)
API_KEY=sk-...
SLACK_TOKEN=xoxb-...

// In code
config: { apiKey: process.env.API_KEY }

// GOOD - Single step for batch
await step("process-all-items", async () => {
  for (const item of items) {
    await processItem(item);
  }
});

// BAD - Dynamic names break resume
for (let i = 0; i < items.length; i++) {
  await step(`process-${i}`, async () => { ... });  // Don't do this!
}

export default new Action({
  handler: async ({ input }) => {
    try {
      // Action logic
      return { success: true };
    } catch (error) {
      console.error("Action failed:", error);
      throw new Error(`Failed to process: ${error.message}`);
    }
  }
});

handler: async ({ query }) => {
  const results = await search(query);

  if (!results.length) {
    throw new Autonomous.ThinkSignal(
      "No results",
      "No results found. Ask the user to try different search terms."
    );
  }

  return results;
}

export default new Conversation({
  channels: ["slack.channel", "webchat.channel"],
  handler: async ({ conversation }) => {
    const channel = conversation.channel;

    if (channel === "slack.channel") {
      // Slack-specific handling (threading, mentions, etc.)
    } else if (channel === "webchat.channel") {
      // Webchat-specific handling
    }
  }
});