adk

A guide to build AI bots with Botpress's Agent Development Kit (ADK)

الانتقال إلى التثبيت

المستودع: duclm1x1/Dive-Ai
آخر نشاط في المصدر: ١٠ فبراير ٢٠٢٦ في ١٧:٥٠
لغة SKILL.md المكتشفة: الإنجليزية
النجوم: ٤
التفرعات: ٢

خيارات التثبيت

يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.

التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.

يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.

npx skills add https://github.com/duclm1x1/Dive-Ai --skill adk

يبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.

تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.

مراجعة ملفات المصدر

اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.

SKILL.md

تعليمات المصدر · معاينة للقراءة فقط

العودة إلى البحث العودة إلى التثبيت

dive-memory-v3

Persistent memory system for AI agents following Model Context Protocol (MCP). Use for storing long-term memories across sessions, semantic search of past knowledge, building knowledge graphs, auto-injecting context, deduplicating memories, syncing to cloud storage. Essential for agents that need to remember decisions, solutions, preferences, and learned patterns over time.

2026-02-10

dive-memory-v3

2026-02-10

api-design-principles

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.

2026-02-10

عرض الكل من هذا المستودع

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

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

Method	Purpose
`step(name, fn)`	Basic execution with caching
`step.sleep(name, ms)`	Pause for milliseconds
`step.sleepUntil(name, date)`	Pause until specific date
`step.listen()`	Wait for external events
`step.progress(msg)`	Update progress message
`step.request(name, prompt)`	Request user input (blocking)
`step.executeWorkflow()`	Start and await another workflow
`step.waitForWorkflow(id)`	Wait for existing workflow
`step.map(items, fn)`	Process array with concurrency
`step.forEach(items, fn)`	Execute on items without results
`step.batch(items, fn)`	Process in groups
`step.fail(reason)`	Mark workflow as failed
`step.abort()`	Stop immediately without failure

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

State Level	Scope	Use For
`bot.state`	Global, all users	Feature flags, counters, maintenance mode
`user.state`	Per user, all their conversations	User preferences, profile, tier
`conversation.state`	Per conversation	Context, message count, active workflow
`workflow.state`	Per workflow instance	Progress tracking, intermediate results

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

Error	Cause	Solution
"Cannot destructure property" in Actions	Destructuring input directly in handler params	Use `async handler({ input, client })` then `const { field } = input` inside
Table creation fails	Invalid table name or `id` defined	Remove `id` column, ensure name ends with "Table"
Integration action not found	Integration not installed or configured	Run `adk list`, add with `adk add`, configure in UI at localhost:3001
Knowledge base not updating	KB not synced	Run `adk kb sync --dev` or `adk kb sync --force`
Workflow not resuming	Dynamic step names	Use stable, unique step names (no `step(\`item-${i}`)`)
Types out of date	Generated types stale	Run `adk dev` or `adk build` to regenerate
Can't message user from workflow	Missing conversationId	Pass `conversationId` when starting workflow, use `client.createMessage()`
"user is not defined"	Accessing conversation context outside conversation	Use `context.get("user", { optional: true })`
State changes not persisting	Creating new objects instead of modifying	Modify state directly: `state.user.name = "Alice"`
Tool not being used by AI	Poor description	Improve tool description, add detailed `.describe()` to inputs

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

Topic	URL
Introduction	https://www.botpress.com/docs/adk/introduction
Quickstart	https://www.botpress.com/docs/adk/quickstart
Project Structure	https://www.botpress.com/docs/adk/project-structure
Actions	https://www.botpress.com/docs/adk/concepts/actions
Tools	https://www.botpress.com/docs/adk/concepts/tools
Conversations	https://www.botpress.com/docs/adk/concepts/conversations
Workflows Overview	https://www.botpress.com/docs/adk/concepts/workflows/overview
Workflow Steps	https://www.botpress.com/docs/adk/concepts/workflows/steps
Tables	https://www.botpress.com/docs/adk/concepts/tables
Triggers	https://www.botpress.com/docs/adk/concepts/triggers
Knowledge Bases	https://www.botpress.com/docs/adk/concepts/knowledge
Managing Integrations	https://www.botpress.com/docs/adk/managing-integrations
Zai Overview	https://www.botpress.com/docs/adk/zai/overview
Zai Reference	https://www.botpress.com/docs/adk/zai/reference
CLI Reference	https://www.botpress.com/docs/adk/cli-reference

Topic	Reference File
Actions	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/actions.md
Tools	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/tools.md
Workflows	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/workflows.md
Conversations	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/conversations.md
Tables	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/tables.md
Triggers	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/triggers.md
Knowledge Bases	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/knowledge-bases.md
Messages	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/messages.md
Agent Config	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/agent-config.md
CLI	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/cli.md
Integration Actions	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/integration-actions.md
Model Configuration	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/model-configuration.md
Context API	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/context-api.md
Tags	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/tags.md
Files	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/files.md
Zai Complete Guide	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/zai-complete-guide.md
Zai Agent Reference	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/zai-agent-reference.md
MCP Server	https://raw.githubusercontent.com/botpress/skills/master/skills/adk/references/mcp-server.md

Context	Method	Why
In Conversations	`conversation.send()`	Has conversation context
In Workflows/Actions	`client.createMessage()`	Needs explicit `conversationId`

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

adk

معلومات المصدر

خيارات التثبيت

مراجعة ملفات المصدر

المزيد من هذا المستودع

Botpress ADK Development Guide

When to Use

Quick Reference

المزيد من هذا المستودع

Botpress ADK Development Guide

When to Use

Quick Reference

How to Use This Skill

Important: ADK is AI-Native

Prerequisites & Installation

Quick Start

Linking and Deploying Your Bot

The Correct Order: Link → Dev → Deploy

Troubleshooting Errors

Project Structure

Agent Configuration

Core Concepts

1. Actions - Reusable Business Logic

2. Tools - AI-Callable Functions

3. Conversations - Message Handlers

4. Workflows - Background & Multi-Step Processes

5. Tables - Data Storage

6. Knowledge Bases - RAG for AI Context

7. Triggers - Event-Driven Automation

Sending Messages

Zai - LLM Utility Operations

Integrations

State Management

Context API

CLI Quick Reference

Autonomous Execution with execute()

Troubleshooting

Common Patterns & Best Practices

1. Always Pass conversationId for Workflows

2. Use Environment Variables for Secrets

3. Keep Step Names Stable in Workflows

4. Error Handling in Actions/Tools

5. ThinkSignal for Tool Edge Cases

6. Multi-Channel Handling

Complete Reference Documentation

Official Botpress ADK Documentation

GitHub Repository References (AI-Optimized)

Common Scenarios - What to Build

Summary

Autonomous Execution with `execute()`