@botpress/adk 1.16.7 → 1.18.0-beta.1

package/dist/templates/slack-triage/agent.config.ts

@@ -0,0 +1,35 @@
+import { z, defineConfig } from '@botpress/runtime'
+
+export default defineConfig({
+  name: '{{projectName}}',
+  description: 'Slack triage bot - monitors channels, classifies help requests, and routes them to the right person',
+
+  defaultModels: {
+    autonomous: 'openai:gpt-4.1-mini-2025-04-14', // Model used by execute() in conversations/workflows
+    zai: 'openai:gpt-4.1-2025-04-14', // Model used by Zai (extract, check, label, etc.)
+  },
+
+  // Per-bot persistent state - tracks triage statistics across all conversations.
+  bot: {
+    state: z.object({
+      totalTriaged: z.number().default(0).describe('Total requests triaged'),
+      lastTriagedAt: z.string().optional().describe('ISO timestamp of last triage'),
+    }),
+  },
+
+  // Per-user persistent state - remembers routing preferences per user.
+  user: {
+    state: z.object({
+      preferredCategory: z.string().optional().describe('Category this user most often submits'),
+      requestCount: z.number().default(0).describe('Number of requests from this user'),
+    }),
+  },
+
+  // Integrations extend your agent with actions, channels, and events.
+  // Browse available integrations:  adk search <name>  |  adk list --available
+  // Install one:                    adk add <integration>  (e.g. adk add browser)
+  // See actions/events/channels:    adk info <integration>
+  dependencies: {
+    integrations: {},
+  },
+})

package/dist/templates/slack-triage/evals/triage-basic.eval.ts

@@ -0,0 +1,55 @@
+/**
+ * Eval: triage-basic
+ *
+ * Verifies that the triage bot correctly classifies common request types.
+ *
+ * Evals use the Eval class from @botpress/adk. Each eval defines a simulated
+ * conversation with assertions on the bot's responses and tool usage.
+ *
+ * Run evals with: adk eval
+ * Run a specific eval: adk eval --name triage-basic
+ */
+import { Eval } from '@botpress/adk'
+
+export default new Eval({
+  name: 'triage-basic',
+  description: 'Verify the bot classifies bug reports, feature requests, and questions correctly',
+  tags: ['triage', 'classification'],
+  type: 'regression',
+
+  conversation: [
+    {
+      user: 'The login page is showing a 500 error whenever I try to sign in with Google SSO',
+      assert: {
+        response: [
+          {
+            llm_judge:
+              'Response acknowledges this is a bug or error report and indicates it will be triaged or routed to the appropriate team',
+          },
+        ],
+      },
+    },
+    {
+      user: 'It would be great if we could export dashboard data to CSV',
+      assert: {
+        response: [
+          {
+            llm_judge:
+              'Response recognizes this as a feature request and indicates it will be forwarded to the product team or logged appropriately',
+          },
+        ],
+      },
+    },
+    {
+      user: 'How do I reset my password?',
+      assert: {
+        response: [
+          {
+            llm_judge:
+              'Response treats this as a general question and either answers it directly or indicates it will be routed to support',
+          },
+        ],
+      },
+    },
+  ],
+})

package/dist/templates/slack-triage/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "{{projectName}}",
+  "version": "1.0.0",
+  "description": "A Slack triage bot built with the ADK - classifies help requests and routes them",
+  "type": "module",
+  "scripts": {
+    "dev": "adk dev",
+    "build": "adk build",
+    "deploy": "adk deploy"
+  },
+  "dependencies": {
+    "@botpress/runtime": "^{{runtimeVersion}}"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/dist/templates/slack-triage/src/actions/classify-request.ts

@@ -0,0 +1,65 @@
+import { Action, z, adk } from '@botpress/runtime'
+
+/**
+ * Classifies an incoming help request into a category using Zai.
+ *
+ * Supported categories:
+ *   - bug:             Something is broken or not working as expected
+ *   - feature_request: A request for new functionality
+ *   - question:        A general question or "how do I..." inquiry
+ *   - ops_issue:       Infrastructure, deployment, or operational problem
+ *
+ * Customize: Add new categories by extending the enum and the label definitions below.
+ */
+export const classifyRequest = new Action({
+  name: 'classifyRequest',
+  description: 'Classify a help request into a category using AI',
+
+  input: z.object({
+    message: z.string().describe('The raw help request message text'),
+  }),
+
+  output: z.object({
+    category: z.enum(['bug', 'feature_request', 'question', 'ops_issue']).describe('The classified category'),
+    confidence: z.string().describe('How confident the classification is: high, medium, or low'),
+    summary: z.string().describe('A one-sentence summary of the request'),
+  }),
+
+  handler: async ({ input }) => {
+    // Use Zai label() with .result() to get confidence scores per category.
+    // Each label is evaluated independently with a 5-tier confidence scale.
+    const { output: labels } = await adk.zai
+      .label(input.message, {
+        bug: 'reports a bug, error, crash, or something not working as expected',
+        feature_request: 'requests a new feature, enhancement, or improvement to existing functionality',
+        question: 'asks a general question, seeks guidance, or wants to know how to do something',
+        ops_issue: 'reports an infrastructure, deployment, uptime, or operational problem',
+      })
+      .result()
+
+    // Pick the category with the highest confidence that matched (value: true).
+    type Category = 'bug' | 'feature_request' | 'question' | 'ops_issue'
+    const categories: Category[] = ['bug', 'feature_request', 'question', 'ops_issue']
+
+    const best = categories
+      .filter((c) => labels[c].value)
+      .sort((a, b) => labels[b].confidence - labels[a].confidence)[0]
+
+    const category: Category = best ?? 'question'
+    const confidence = best ? (labels[best].confidence >= 0.8 ? 'high' : 'medium') : 'low'
+
+    // Use Zai extract() to generate a concise summary of the request.
+    const extracted = await adk.zai.extract(
+      input.message,
+      z.object({
+        summary: z.string().describe('A single concise sentence summarizing the help request'),
+      })
+    )
+
+    return {
+      category,
+      confidence,
+      summary: extracted.summary,
+    }
+  },
+})

package/dist/templates/slack-triage/src/conversations/slack-dm.ts

@@ -0,0 +1,72 @@
+import { Conversation, Autonomous, z } from '@botpress/runtime'
+import { classifyRequest } from '../actions/classify-request'
+
+/**
+ * Exit that the AI uses once it has classified and responded to the request.
+ * The execute() call ends when the AI selects this exit.
+ */
+const TriageComplete = new Autonomous.Exit({
+  name: 'triage_complete',
+  description: 'Classification is done and the user has been notified. Exit the conversation.',
+  schema: z.object({
+    category: z.string().describe('The category the request was classified as'),
+  }),
+})
+
+/**
+ * Handles incoming Slack DM messages.
+ *
+ * Flow: classify the request -> respond to the user -> exit.
+ * The AI uses the classifyRequest tool, then selects the TriageComplete exit
+ * to end the conversation cleanly.
+ *
+ * Customize:
+ *   - Change the channel to "slack.channel" for public channel messages
+ *   - Add more exits for different outcomes (e.g. needs_more_info, escalated)
+ *   - Remove the exit to keep the conversation open for follow-ups
+ */
+export const SlackDM = new Conversation({
+  channel: 'slack.dm',
+
+  async handler({ execute }) {
+    // Classify and respond in one shot. The AI will:
+    // 1. Use classifyRequest to categorize the message
+    // 2. Tell the user the result
+    // 3. Select the TriageComplete exit to end
+    const result = await execute({
+      instructions: `You are a triage assistant. The user just sent a help request.
+
+Your job:
+1. Use the classifyRequest tool to classify their message
+2. Tell them what category it was classified as and who it's being routed to
+3. Be concise. One short paragraph max. Use Slack markdown.
+4. Then select the triage_complete exit with the category.
+
+Do NOT ask follow-up questions. Classify, confirm, exit.`,
+      tools: [classifyRequest.asTool()],
+      exits: [TriageComplete],
+    })
+
+    if (result.is(TriageComplete)) {
+      console.log(`Triaged as: ${result.output.category}`)
+    }
+
+    // --- After triage, the conversation is done. ---
+    // Examples of what you could do next instead:
+    //
+    // // Start the full triage workflow
+    // import { TriageFlow } from '../workflows/triage-flow'
+    // await TriageFlow.start({ message: message.payload.text })
+    //
+    // // Chain another execute() for follow-up questions
+    // await execute({
+    //   instructions: 'Ask the user if they want to override the priority.',
+    // })
+    //
+    // // Open-ended support chat (no exit = keeps going until idle)
+    // await execute({
+    //   instructions: 'You are a helpful support agent.',
+    //   tools: [classifyRequest.asTool()],
+    // })
+  },
+})

package/dist/templates/slack-triage/src/knowledge/team-directory.md

@@ -0,0 +1,33 @@
+# Team Directory
+
+Replace this with your actual team info for context-aware routing.
+
+## Engineering
+
+- **@oncall-eng** - Bugs, crashes, production incidents
+- **@backend-team** - APIs, services, database issues
+- **@frontend-team** - UI bugs, browser issues
+
+## Product
+
+- **@product-team** - Feature requests, roadmap
+- **@design-team** - UX issues, visual bugs
+
+## Operations
+
+- **@devops** - Infrastructure, deploys, CI/CD
+- **@security-team** - Vulnerabilities, access, compliance
+
+## Support
+
+- **@support-team** - Questions, onboarding, docs
+- **@hr-team** - People ops, policies
+
+## Escalation
+
+| Priority | Response Time | Escalation            |
+| -------- | ------------- | --------------------- |
+| Critical | 15 min        | @oncall-eng + @devops |
+| High     | 1 hour        | Category assignee     |
+| Medium   | 4 hours       | Category assignee     |
+| Low      | 1 biz day     | Category assignee     |

package/dist/templates/slack-triage/src/tables/routing-rules.ts

@@ -0,0 +1,38 @@
+import { Table, z } from '@botpress/runtime'
+
+/**
+ * Stores routing rules that map request categories to assignees and channels.
+ *
+ * Each row defines where a specific category of request should be routed:
+ *   - category:     The request classification (e.g. "bug", "feature_request")
+ *   - assignee:     Who handles it (e.g. "@oncall-eng", "@product-team")
+ *   - slackChannel: Slack channel to post the triage summary (e.g. "#bugs")
+ *   - priority:     Default priority for this category
+ *
+ * The `category` column is searchable so the triage workflow can look up
+ * the correct rule quickly.
+ *
+ * Seed this table after first deploy via the Botpress dashboard or a script:
+ *   | category        | assignee       | slackChannel      | priority |
+ *   |-----------------|----------------|-------------------|----------|
+ *   | bug             | @oncall-eng    | #bugs             | high     |
+ *   | feature_request | @product-team  | #feature_requests | medium   |
+ *   | question        | @support-team  | #help-desk        | low      |
+ *   | ops_issue       | @devops        | #ops-alerts       | high     |
+ *
+ * Note: Do NOT define an `id` column -- it is automatically managed by the system.
+ */
+export const RoutingRulesTable = new Table({
+  name: 'RoutingRulesTable',
+  description: 'Maps request categories to assignees and Slack channels for triage routing',
+
+  columns: {
+    category: {
+      searchable: true,
+      schema: z.string().describe('Request category: bug, feature_request, question, or ops_issue'),
+    },
+    assignee: z.string().describe('Person or team to assign this category to (e.g. @oncall-eng)'),
+    slackChannel: z.string().describe('Slack channel to post triage summaries for this category (e.g. #bugs)'),
+    priority: z.string().describe('Default priority level: low, medium, high, or critical'),
+  },
+})

package/dist/templates/slack-triage/src/triggers/new-message.ts

@@ -0,0 +1,44 @@
+import { Trigger } from '@botpress/runtime'
+import { TriageFlow } from '../workflows/triage-flow'
+
+/**
+ * Fires when a new message arrives in a monitored Slack channel.
+ *
+ * This trigger listens for the "message.created" event and starts the
+ * triage workflow for each incoming message. The workflow then classifies
+ * the request and routes it to the appropriate person/channel.
+ *
+ * Customize:
+ *   - Add filters to ignore bot messages or specific channels
+ *   - Switch to "slack:reactionAdded" to triage only when someone reacts with a specific emoji
+ *   - Add "slack:memberJoinedChannel" to welcome new members
+ */
+export const onNewMessage = new Trigger({
+  name: 'onNewMessage',
+  description: 'Starts the triage workflow when a new message arrives in a monitored Slack channel',
+  events: ['message.created'],
+
+  handler: async ({ event }) => {
+    const payload = event.payload
+
+    // Skip empty messages
+    if (!payload?.text) {
+      return
+    }
+
+    // Optional: skip bot messages to avoid triage loops.
+    // Uncomment and adjust the condition for your workspace:
+    // if (payload.userId === bot.id) {
+    //   return;
+    // }
+
+    // Start the triage workflow with the message content
+    const instance = await TriageFlow.start({
+      message: payload.text,
+      senderName: payload.userId ?? 'Unknown',
+      sourceChannel: payload.conversationId ?? undefined,
+    })
+
+    console.log(`Triage workflow started: ${instance.id} for message from ${payload.userId}`)
+  },
+})

package/dist/templates/slack-triage/src/workflows/triage-flow.ts

@@ -0,0 +1,104 @@
+import { Workflow, z, actions, bot } from '@botpress/runtime'
+import { RoutingRulesTable } from '../tables/routing-rules'
+
+/**
+ * Triage workflow: classifies a help request, looks up routing rules,
+ * and posts a summary to the appropriate Slack channel.
+ *
+ * Steps:
+ *   1. classify  - Run the classifyRequest action to categorize the message
+ *   2. lookup    - Find the routing rule for this category from the table
+ *   3. notify    - Post a triage summary to the target Slack channel
+ *
+ * Customize: Add steps for priority escalation, duplicate detection,
+ * SLA tracking, or assignment rotation.
+ */
+export const TriageFlow = new Workflow({
+  name: 'triageFlow',
+  description: 'Classify a help request and route it to the right person',
+
+  input: z.object({
+    message: z.string().describe('The raw help request text'),
+    senderName: z.string().optional().describe('Display name of the person who sent the request'),
+    sourceChannel: z.string().optional().describe('Slack channel where the request originated'),
+  }),
+
+  output: z.object({
+    category: z.string().describe('The classified category'),
+    assignee: z.string().describe('Who the request was routed to'),
+    summary: z.string().describe('Summary of the request'),
+    routed: z.boolean().describe('Whether the request was successfully routed'),
+  }),
+
+  handler: async ({ input, step }) => {
+    // Step 1: Classify the request using the AI action
+    const classification = await step('classify', async () => {
+      return await actions.classifyRequest({ message: input.message })
+    })
+
+    // Step 2: Look up the routing rule for this category
+    const routingRule = await step('lookup', async () => {
+      const { rows } = await RoutingRulesTable.findRows({
+        filter: { category: classification.category },
+        limit: 1,
+      })
+
+      if (rows.length === 0) {
+        // No routing rule found -- return a sensible default
+        return {
+          assignee: 'unassigned',
+          slackChannel: '#general',
+          priority: 'medium',
+        }
+      }
+
+      return {
+        assignee: rows[0].assignee,
+        slackChannel: rows[0].slackChannel,
+        priority: rows[0].priority,
+      }
+    })
+
+    // Step 3: Post a triage summary to the target Slack channel
+    await step('notify', async () => {
+      const sender = input.senderName ?? 'Someone'
+      const source = input.sourceChannel ? ` in <#${input.sourceChannel}>` : ''
+
+      const triageMessage = [
+        `*New ${classification.category} request*`,
+        `> ${classification.summary}`,
+        '',
+        `*From:* ${sender}${source}`,
+        `*Priority:* ${routingRule.priority}`,
+        `*Assigned to:* ${routingRule.assignee}`,
+        `*Confidence:* ${classification.confidence}`,
+      ].join('\n')
+
+      // Post to the routing channel via Slack integration action.
+      // This requires the Slack integration to be configured with appropriate permissions.
+      try {
+        await actions.slack.addReaction({
+          name: 'eyes',
+          channel: input.sourceChannel ?? '',
+          timestamp: '',
+        })
+      } catch {
+        // Reaction may fail if we do not have the message timestamp -- that is okay
+      }
+
+      console.log(`Triaged: ${classification.category} -> ${routingRule.slackChannel} (${routingRule.assignee})`)
+      console.log(triageMessage)
+    })
+
+    // Update bot-level triage counter
+    bot.state.totalTriaged += 1
+    bot.state.lastTriagedAt = new Date().toISOString()
+
+    return {
+      category: classification.category,
+      assignee: routingRule.assignee,
+      summary: classification.summary,
+      routed: routingRule.assignee !== 'unassigned',
+    }
+  },
+})

package/dist/templates/slack-triage/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleDetection": "force",
+    "resolveJsonModule": true,
+    "paths": {
+      "@botpress/runtime/_types/*": ["./.adk/*-types"]
+    }
+  },
+  "include": ["src/**/*", ".adk/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/dist/templates/template.config.json

@@ -0,0 +1,47 @@
+{
+  "templates": [
+    {
+      "name": "blank",
+      "description": "Empty project with just the folder structure",
+      "category": "starter",
+      "integrations": [],
+      "primitives": [],
+      "complexity": "beginner"
+    },
+    {
+      "name": "hello-world",
+      "description": "A working chatbot with chat and webchat integrations",
+      "category": "starter",
+      "integrations": ["chat", "webchat"],
+      "primitives": ["conversations"],
+      "complexity": "beginner",
+      "postInit": ["adk add chat@latest", "adk add webchat@latest"]
+    },
+    {
+      "name": "slack-triage",
+      "description": "Slack bot that monitors a channel, classifies requests, and routes to the right person",
+      "category": "triage",
+      "integrations": ["slack"],
+      "primitives": ["actions", "workflows", "conversations", "tables", "triggers", "knowledge"],
+      "complexity": "intermediate",
+      "postInit": ["adk add slack@latest"]
+    },
+    {
+      "name": "knowledge-assistant",
+      "description": "RAG-powered Q&A agent with knowledge base and source citations",
+      "category": "knowledge",
+      "integrations": ["chat", "webchat"],
+      "primitives": ["conversations", "knowledge", "actions"],
+      "complexity": "beginner",
+      "postInit": ["adk add chat@latest", "adk add webchat@latest"]
+    },
+    {
+      "name": "crm-enrichment",
+      "description": "Scheduled workflow that enriches CRM contacts with AI-driven classification",
+      "category": "enrichment",
+      "integrations": [],
+      "primitives": ["workflows", "tables", "actions", "triggers"],
+      "complexity": "intermediate"
+    }
+  ]
+}

package/dist/utils/json-ordering.d.ts

@@ -1,19 +1,20 @@
 /**
  * Utility for ensuring consistent key ordering in JSON files
  */
-export declare const agentInfoKeyOrder: readonly ["botId", "workspaceId", "apiUrl", "devId"];
+export declare const agentInfoKeyOrder: readonly ["botId", "workspaceId", "apiUrl"];
+export declare const agentLocalInfoKeyOrder: readonly ["botId", "workspaceId", "apiUrl", "devId"];
 export declare const dependenciesKeyOrder: readonly ["integrations"];
 export declare const integrationKeyOrder: readonly ["version", "enabled", "configurationType", "config"];
 /**
  * Orders object keys according to a specified order, with unspecified keys at the end alphabetically
  */
-export declare function orderKeys<T extends Record<string, any>>(obj: T, keyOrder?: readonly (keyof T)[]): T;
+export declare function orderKeys<T extends Record<string, unknown>>(obj: T, keyOrder?: readonly (keyof T)[]): T;
 /**
  * Recursively orders keys in nested objects for integrations
  */
-export declare function orderIntegrationKeys(integrations: Record<string, any>): Record<string, any>;
+export declare function orderIntegrationKeys(integrations: Record<string, unknown>): Record<string, unknown>;
 /**
  * Stringifies JSON with consistent key ordering and formatting
  */
-export declare function stringifyWithOrder<T extends Record<string, any>>(obj: T, keyOrder?: readonly (keyof T)[], space?: number | string): string;
+export declare function stringifyWithOrder<T extends Record<string, unknown>>(obj: T, keyOrder?: readonly (keyof T)[], space?: number | string): string;
 //# sourceMappingURL=json-ordering.d.ts.map

package/dist/utils/json-ordering.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-ordering.d.ts","sourceRoot":"","sources":["../../src/utils/json-ordering.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,eAAO,MAAM,iBAAiB,sDAAuD,CAAA;AACrF,eAAO,MAAM,oBAAoB,2BAA4B,CAAA;AAC7D,eAAO,MAAM,mBAAmB,gEAAiE,CAAA;AAEjG;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,CAgCnG;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAY3F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9D,GAAG,EAAE,CAAC,EACN,QAAQ,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAC/B,KAAK,GAAE,MAAM,GAAG,MAAU,GACzB,MAAM,CAYR"}
+{"version":3,"file":"json-ordering.d.ts","sourceRoot":"","sources":["../../src/utils/json-ordering.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,eAAO,MAAM,iBAAiB,6CAA8C,CAAA;AAC5E,eAAO,MAAM,sBAAsB,sDAAuD,CAAA;AAC1F,eAAO,MAAM,oBAAoB,2BAA4B,CAAA;AAC7D,eAAO,MAAM,mBAAmB,gEAAiE,CAAA;AAEjG;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,CAgCvG;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYnG;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,GAAG,EAAE,CAAC,EACN,QAAQ,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAC/B,KAAK,GAAE,MAAM,GAAG,MAAU,GACzB,MAAM,CAcR"}