@botpress/adk 1.16.7 → 1.18.0-beta.1

package/dist/templates/hello-world/agent.config.ts

@@ -0,0 +1,48 @@
+import { z, defineConfig } from '@botpress/runtime'
+
+export default defineConfig({
+  name: '{{projectName}}',
+  description: 'An AI agent built with Botpress ADK',
+
+  defaultModels: {
+    autonomous: 'cerebras:gpt-oss-120b',
+    zai: 'cerebras:gpt-oss-120b',
+  },
+
+  // Per-bot persistent state — add fields here to store data across conversations.
+  bot: {
+    state: z.object({}),
+  },
+
+  // Per-user persistent state — add fields here to remember things about each user.
+  user: {
+    state: z.object({}),
+  },
+
+  // Static bot-level config — import { configuration } from '@botpress/runtime' to read it anywhere.
+  // Great for feature flags, API endpoints, and other deploy-time settings.
+  // configuration: {
+  //   schema: z.object({
+  //     apiEndpoint: z.string().default("https://api.example.com"),
+  //     featureFlags: z.object({
+  //       enableBeta: z.boolean().default(false),
+  //     }).default({}),
+  //   }),
+  // },
+
+  // Custom events your agent can emit and subscribe to via triggers.
+  // events: {
+  //   myEvent: {
+  //     schema: z.object({ userId: z.string(), message: z.string() }),
+  //     description: 'Emitted when something noteworthy happens',
+  //   },
+  // },
+
+  // 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/hello-world/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "{{projectName}}",
+  "version": "1.0.0",
+  "description": "A Botpress Agent built with the ADK",
+  "type": "module",
+  "scripts": {
+    "dev": "adk dev",
+    "build": "adk build",
+    "deploy": "adk deploy"
+  },
+  "dependencies": {
+    "@botpress/runtime": "^{{runtimeVersion}}"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/dist/templates/hello-world/src/actions/index.ts

@@ -0,0 +1,19 @@
+// import { Action, z } from '@botpress/runtime'
+//
+// /**
+//  * A strongly-typed callable function — use `new Action(...)` (it's a class constructor).
+//  * Handler always receives `{ input, client }` as props, not the input fields directly.
+//  * Can be converted to an AI tool via `.asTool()` and passed to `execute()`.
+//  */
+// export default new Action({
+//   name: 'myAction',
+//   input: z.object({
+//     message: z.string().describe('The message to process'),
+//   }),
+//   output: z.object({
+//     result: z.string().describe('The processed result'),
+//   }),
+//   handler: async ({ input }) => {
+//     return { result: `Processed: ${input.message}` }
+//   },
+// })

package/dist/templates/hello-world/src/conversations/index.ts

@@ -0,0 +1,10 @@
+import { Conversation } from '@botpress/runtime'
+
+export default new Conversation({
+  channel: '*',
+  handler: async ({ execute }) => {
+    await execute({
+      instructions: `You are a helpful AI assistant built with Botpress ADK. You can assist users with their questions and tasks.`,
+    })
+  },
+})

package/dist/templates/hello-world/src/knowledge/index.ts

@@ -0,0 +1,17 @@
+// import { Knowledge, DataSource } from '@botpress/runtime'
+//
+// /**
+//  * A RAG-powered knowledge base for semantic search and AI-grounded responses.
+//  * Data sources: Directory (local .md/.pdf), Website (sitemap/URLs), or Table.
+//  * Pass to `execute({ knowledge: [MyKB] })` to make the AI use it when answering.
+//  */
+// const mySource = DataSource.Directory.fromPath('src/knowledge', {
+//   id: 'my-docs',
+//   filter: (filePath) => filePath.endsWith('.md') || filePath.endsWith('.pdf'),
+// })
+//
+// export const MyKB = new Knowledge({
+//   name: 'my-knowledge',
+//   description: 'My knowledge base',
+//   sources: [mySource],
+// })

package/dist/templates/hello-world/src/tables/index.ts

@@ -0,0 +1,19 @@
+// import { Table, z } from '@botpress/runtime'
+//
+// /**
+//  * Structured data storage with CRUD and optional semantic search.
+//  * Table names must end with "Table" (e.g. UsersTable, OrdersTable).
+//  * Mark string columns as `{ searchable: true, schema: z.string() }` to enable search.
+//  * @reserved id, createdAt, updatedAt — auto-managed by the system, do not define them.
+//  */
+// export const MyTable = new Table({
+//   name: 'myTable',
+//   description: 'Stores my data',
+//   columns: {
+//     title: {
+//       searchable: true,
+//       schema: z.string().describe('Title of the entry'),
+//     },
+//     status: z.string().describe('Current status of the entry'),
+//   },
+// })

package/dist/templates/hello-world/src/triggers/index.ts

@@ -0,0 +1,20 @@
+// import { Trigger } from '@botpress/runtime'
+//
+// /**
+//  * An event subscription that fires automatically when the specified events occur.
+//  * Bot events:    'register', 'message.created', 'conversation.started', 'conversation.ended',
+//  *                'user.created', 'workflow.started', 'workflow.completed', 'workflow.failed'
+//  * Webchat:       'webchat:conversationStarted', 'webchat:trigger'
+//  * Slack:         'slack:reactionAdded', 'slack:memberJoinedChannel'
+//  * Linear:        'linear:issueCreated', 'linear:issueUpdated'
+//  * GitHub:        'github:issueOpened', 'github:pullRequestMerged'
+//  * Run `adk info <integration>` to see all events for an integration.
+//  */
+// export default new Trigger({
+//   name: 'onRegister',
+//   description: 'Runs on bot startup to initialize state',
+//   events: ['register'],
+//   handler: async () => {
+//     console.log('Bot started!')
+//   },
+// })

package/dist/templates/hello-world/src/workflows/index.ts

@@ -0,0 +1,23 @@
+// import { Workflow, z } from '@botpress/runtime'
+//
+// /**
+//  * A multi-step, resumable process that persists state across executions.
+//  * Each `step()` call is checkpointed — safe to retry on failure.
+//  * Use `step.sleep()`, `step.request()`, or `step.listen()` to pause execution.
+//  * Start from a trigger or conversation via `MyWorkflow.start({ input })`.
+//  */
+// export const MyWorkflow = new Workflow({
+//   name: 'myWorkflow',
+//   input: z.object({
+//     data: z.string().describe('Input data to process'),
+//   }),
+//   output: z.object({
+//     result: z.string().describe('The processed result'),
+//   }),
+//   handler: async ({ input, step }) => {
+//     const result = await step('process', async () => {
+//       return `Processed: ${input.data}`
+//     })
+//     return { result }
+//   },
+// })

package/dist/templates/hello-world/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/knowledge-assistant/README.md

@@ -0,0 +1,66 @@
+# {{projectName}}
+
+A RAG-powered knowledge assistant built with Botpress ADK. This agent answers questions using your documents, with source citations for every response.
+
+## How It Works
+
+1. **Knowledge Base**: Documents in `src/knowledge/` are indexed for semantic search
+2. **Conversations**: When a user asks a question, the AI searches the knowledge base for relevant passages
+3. **Citations**: Responses include references to the source documents used
+
+## Getting Started
+
+1. Install dependencies:
+
+   ```bash
+   {{packageManager}} install
+   ```
+
+2. Add your documents to `src/knowledge/` (markdown, PDF, or text files)
+
+3. Start development server:
+
+   ```bash
+   adk dev
+   ```
+
+4. Deploy your agent:
+   ```bash
+   adk deploy
+   ```
+
+## Adding Documents
+
+Place your documents in `src/knowledge/`. Supported formats:
+
+- Markdown (`.md`)
+- PDF (`.pdf`)
+- Text (`.txt`)
+
+The knowledge base automatically indexes all supported files. After adding new documents, run `adk kb sync` or restart `adk dev` to re-index.
+
+## Project Structure
+
+- `src/knowledge/docs.ts` - Knowledge base definition
+- `src/knowledge/*.md` - Your source documents
+- `src/conversations/index.ts` - Conversation handler with RAG execution
+- `src/actions/` - Add custom actions (e.g. programmatic KB search for API access)
+- `src/tables/` - Data storage (extend as needed)
+- `src/triggers/` - Event subscriptions (extend as needed)
+- `src/workflows/` - Long-running processes (extend as needed)
+
+## How Citations Work
+
+The conversation handler passes the knowledge base to `execute()`. The AI automatically searches relevant documents when answering questions and cites its sources. This is handled by the Botpress runtime -- no manual citation logic is required.
+
+## Customization
+
+- **Model**: Change `defaultModels` in `agent.config.ts` to use a different LLM
+- **Instructions**: Edit the `instructions` in `src/conversations/index.ts` to change the agent's personality
+- **Knowledge sources**: Add website crawling or table-based sources in `src/knowledge/docs.ts`
+- **Tools**: Convert the search action to a tool with `.asTool()` for more control
+
+## Learn More
+
+- [ADK Documentation](https://botpress.com/docs/adk)
+- [Botpress Platform](https://botpress.com)

package/dist/templates/knowledge-assistant/agent.config.ts

@@ -0,0 +1,26 @@
+import { z, defineConfig } from '@botpress/runtime'
+
+export default defineConfig({
+  name: '{{projectName}}',
+  description: 'A RAG-powered knowledge assistant that answers questions using your documents',
+
+  defaultModels: {
+    autonomous: 'openai:gpt-4.1-mini-2025-04-14',
+    zai: 'openai:gpt-4.1-2025-04-14',
+  },
+
+  // Per-bot persistent state
+  bot: {
+    state: z.object({}),
+  },
+
+  // Per-user persistent state
+  user: {
+    state: z.object({}),
+  },
+
+  // Integrations extend your agent with actions, channels, and events.
+  dependencies: {
+    integrations: {},
+  },
+})

package/dist/templates/knowledge-assistant/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "{{projectName}}",
+  "version": "1.0.0",
+  "description": "A RAG-powered knowledge assistant built with Botpress ADK",
+  "type": "module",
+  "scripts": {
+    "dev": "adk dev",
+    "build": "adk build",
+    "deploy": "adk deploy"
+  },
+  "dependencies": {
+    "@botpress/runtime": "^{{runtimeVersion}}"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/dist/templates/knowledge-assistant/src/actions/index.ts

@@ -0,0 +1,19 @@
+// import { Action, z } from '@botpress/runtime'
+//
+// /**
+//  * A strongly-typed callable function — use `new Action(...)` (it's a class constructor).
+//  * Handler always receives `{ input, client }` as props, not the input fields directly.
+//  * Can be converted to an AI tool via `.asTool()` and passed to `execute()`.
+//  */
+// export default new Action({
+//   name: 'myAction',
+//   input: z.object({
+//     message: z.string().describe('The message to process'),
+//   }),
+//   output: z.object({
+//     result: z.string().describe('The processed result'),
+//   }),
+//   handler: async ({ input }) => {
+//     return { result: `Processed: ${input.message}` }
+//   },
+// })

package/dist/templates/knowledge-assistant/src/actions/search-docs.ts

@@ -0,0 +1,50 @@
+import { Action, z, context } from '@botpress/runtime'
+import { DocsKB } from '../knowledge/docs'
+
+/**
+ * Search the knowledge base programmatically.
+ *
+ * This action provides API-level access to the documentation search,
+ * useful for integrations, workflows, or external systems that need
+ * to query the knowledge base outside of a conversation.
+ */
+export const searchDocs = new Action({
+  name: 'searchDocs',
+  description: 'Search the documentation knowledge base',
+
+  input: z.object({
+    query: z.string().describe('The search query'),
+    limit: z.number().min(1).max(20).default(5).describe('Maximum number of results to return'),
+  }),
+
+  output: z.object({
+    results: z.array(
+      z.object({
+        content: z.string().describe('The matched passage content'),
+        source: z.string().describe('The source file path'),
+        score: z.number().describe('Relevance score'),
+      })
+    ),
+  }),
+
+  async handler({ input }) {
+    const client = context.get('client')
+
+    const { passages } = await client.searchFiles({
+      query: input.query,
+      tags: {
+        source: 'knowledge-base',
+        kbName: [DocsKB.name],
+      },
+      limit: input.limit,
+    })
+
+    return {
+      results: passages.map((p) => ({
+        content: p.content,
+        source: p.file.key,
+        score: p.score,
+      })),
+    }
+  },
+})

package/dist/templates/knowledge-assistant/src/conversations/index.ts

@@ -0,0 +1,33 @@
+import { Conversation } from '@botpress/runtime'
+import { DocsKB } from '../knowledge/docs'
+
+/**
+ * Main conversation handler for the knowledge assistant.
+ *
+ * Uses execute() with the DocsKB knowledge base. The AI automatically
+ * gets a search tool for the KB — no custom action needed.
+ *
+ * Handles all channels (chat, webchat, etc.) via the wildcard channel.
+ */
+export default new Conversation({
+  channel: '*',
+
+  async handler({ execute }) {
+    await execute({
+      instructions: `You are a company knowledge assistant. You answer employee questions using the company documentation.
+
+Lead with example questions, to assist the user in asking good questions. For example:
+- "What is the company's remote work policy?"
+- "How do I request time off?"
+- "What are the steps to set up my email on a new device?"
+Rules:
+- Search the knowledge base for every question. Do not guess or use general knowledge.
+- If the answer is in the docs, quote the relevant policy or section.
+- If the docs don't cover it, say "I don't have information about that in our docs" and suggest who to ask (HR, manager, IT, etc).
+- Be direct. Lead with the answer, then provide context.
+- Use short paragraphs. Bullet points for lists.`,
+
+      knowledge: [DocsKB],
+    })
+  },
+})

package/dist/templates/knowledge-assistant/src/knowledge/docs.ts

@@ -0,0 +1,23 @@
+import { Knowledge, DataSource } from '@botpress/runtime'
+
+/**
+ * Knowledge base that indexes all markdown files in the src/knowledge/ directory.
+ *
+ * Add your documents (markdown, PDF, text) to this folder and they will be
+ * automatically indexed for semantic search. The AI uses this knowledge base
+ * to answer questions with accurate, source-cited responses.
+ *
+ * Sync your knowledge base:
+ *   adk kb sync      (manual sync)
+ *   adk dev          (auto-syncs on startup and file changes)
+ */
+const docsSource = DataSource.Directory.fromPath('src/knowledge', {
+  id: 'docs',
+  filter: (filePath) => filePath.endsWith('.md') || filePath.endsWith('.pdf') || filePath.endsWith('.txt'),
+})
+
+export const DocsKB = new Knowledge({
+  name: 'docsKB',
+  description: 'Documentation and reference materials for answering user questions',
+  sources: [docsSource],
+})

package/dist/templates/knowledge-assistant/src/knowledge/getting-started.md

@@ -0,0 +1,49 @@
+# Company Handbook
+
+Welcome to Acme Corp! This document covers our policies, benefits, and day-to-day operations.
+
+> **Note:** This is sample content. Replace it with your actual company docs, product documentation, or any knowledge you want your assistant to answer questions about.
+
+## Working Hours
+
+Our standard working hours are 9 AM to 5 PM in your local timezone. We offer flexible scheduling — as long as you're available for core hours (11 AM to 3 PM) and attend your team's standups, you can adjust your start and end times.
+
+## Time Off Policy
+
+- **PTO:** 20 days per year, accruing monthly
+- **Sick leave:** Unlimited, no questions asked for the first 3 days. Beyond that, a doctor's note is appreciated but not required.
+- **Holidays:** We follow the US federal holiday calendar. If you're outside the US, you can swap US holidays for your local ones.
+- **Parental leave:** 16 weeks paid for all parents, regardless of gender.
+
+## Expense Policy
+
+- **Software and tools:** Pre-approved up to $100/month. Anything over needs manager approval.
+- **Books and courses:** Fully covered, no cap. Submit receipts through Expensify.
+- **Travel:** Book economy for flights under 5 hours, business class for longer. Hotels up to $250/night.
+- **Meals:** $30/day when traveling. Team dinners covered fully with VP approval.
+
+## Engineering Practices
+
+### Code Review
+
+Every PR needs at least one approval before merging. For changes touching auth, payments, or data deletion, two approvals are required. Reviewers should respond within 24 hours.
+
+### Incident Response
+
+1. **Severity 1 (service down):** Page the on-call engineer via PagerDuty. All hands until resolved.
+2. **Severity 2 (degraded):** Notify #incidents in Slack. On-call investigates, escalates if not resolved in 1 hour.
+3. **Severity 3 (minor bug):** File a ticket, fix in next sprint.
+
+Post-incident reviews happen within 48 hours. No blame, just learnings.
+
+### Deployment
+
+We deploy to production twice daily (11 AM and 4 PM UTC). Feature flags are required for anything user-facing. Rollbacks are one-click via the deploy dashboard.
+
+## Benefits
+
+- **Health insurance:** 100% covered for employees, 80% for dependents
+- **401k:** 4% match, vests immediately
+- **Home office:** $1,500 one-time setup budget for new hires
+- **Wellness:** $100/month for gym, therapy, or wellness apps
+- **Learning:** Conference budget of $2,000/year plus 3 days off to attend

package/dist/templates/knowledge-assistant/src/tables/index.ts

@@ -0,0 +1,21 @@
+// import { Table, z } from '@botpress/runtime'
+//
+// /**
+//  * Example: Track search queries and feedback to improve the knowledge base over time.
+//  *
+//  * Table names must end with "Table" (e.g. QueriesTable, FeedbackTable).
+//  * Mark string columns as `{ searchable: true, schema: z.string() }` to enable semantic search.
+//  * @reserved id, createdAt, updatedAt — auto-managed by the system, do not define them.
+//  */
+// export const QueriesTable = new Table({
+//   name: 'queriesTable',
+//   description: 'Tracks user search queries and their feedback',
+//   columns: {
+//     query: {
+//       searchable: true,
+//       schema: z.string().describe('The user search query'),
+//     },
+//     resultCount: z.number().describe('Number of results returned'),
+//     helpful: z.boolean().optional().describe('Whether the user found the answer helpful'),
+//   },
+// })

package/dist/templates/knowledge-assistant/src/triggers/index.ts

@@ -0,0 +1,17 @@
+// import { Trigger } from '@botpress/runtime'
+//
+// /**
+//  * Example: Track when users start conversations to monitor KB assistant usage.
+//  *
+//  * Bot events:    'register', 'message.created', 'conversation.started', 'conversation.ended',
+//  *                'user.created', 'workflow.started', 'workflow.completed', 'workflow.failed'
+//  * Run `adk info <integration>` to see all events for an integration.
+//  */
+// export default new Trigger({
+//   name: 'onConversationStarted',
+//   description: 'Logs when a new knowledge assistant conversation begins',
+//   events: ['conversation.started'],
+//   handler: async ({ event }) => {
+//     console.log(`New conversation started: ${event.payload.conversationId}`)
+//   },
+// })

package/dist/templates/knowledge-assistant/src/workflows/index.ts

@@ -0,0 +1,28 @@
+// import { Workflow, z } from '@botpress/runtime'
+// import { DocsKB } from '../knowledge/docs'
+//
+// /**
+//  * Example: A research workflow that searches the knowledge base and produces a summary.
+//  *
+//  * Each `step()` call is checkpointed — safe to retry on failure.
+//  * Start from a trigger or conversation via `ResearchWorkflow.start({ input })`.
+//  */
+// export const ResearchWorkflow = new Workflow({
+//   name: 'research',
+//   input: z.object({
+//     topic: z.string().describe('The topic to research'),
+//   }),
+//   output: z.object({
+//     summary: z.string().describe('A summary of findings from the knowledge base'),
+//   }),
+//   handler: async ({ input, step, execute }) => {
+//     const summary = await step('research', async () => {
+//       const result = await execute({
+//         instructions: `Research the following topic using the knowledge base and provide a concise summary: ${input.topic}`,
+//         knowledge: [DocsKB],
+//       })
+//       return result
+//     })
+//     return { summary }
+//   },
+// })

package/dist/templates/knowledge-assistant/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/slack-triage/README.md

@@ -0,0 +1,74 @@
+# {{projectName}}
+
+A Slack triage bot built with the Botpress ADK. It monitors channels for help requests, classifies them using AI, and routes them to the right person or channel based on configurable routing rules.
+
+## How It Works
+
+1. **Trigger**: A new message arrives in a monitored Slack channel
+2. **Classify**: The `classify-request` action uses Zai to categorize the request (bug, feature_request, question, ops_issue)
+3. **Route**: The `triage-flow` workflow looks up routing rules from the `RoutingRulesTable` and posts a summary to the appropriate channel or person
+4. **Respond**: The Slack DM conversation handler answers follow-up questions about triage status
+
+## Getting Started
+
+1. Install dependencies:
+
+   ```bash
+   {{packageManager}} install
+   ```
+
+2. Configure Slack:
+   - Create a Slack app at https://api.slack.com/apps
+   - Add the bot to your workspace
+   - Run `adk dev` and configure the Slack integration in the Botpress dashboard
+
+3. Seed routing rules:
+   After your first `adk dev`, add rows to the `RoutingRulesTable` 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     |
+   ```
+
+4. Start development server:
+
+   ```bash
+   adk dev
+   ```
+
+5. Deploy your agent:
+   ```bash
+   adk deploy
+   ```
+
+## Project Structure
+
+- `src/actions/classify-request.ts` - AI-powered request classification
+- `src/workflows/triage-flow.ts` - Multi-step triage workflow (classify, lookup, route)
+- `src/conversations/slack-dm.ts` - Handles Slack channel messages with AI
+- `src/tables/routing-rules.ts` - Configurable routing rules
+- `src/triggers/new-message.ts` - Fires on new Slack messages
+- `src/knowledge/team-directory.md` - Team directory for AI context
+
+## Customization
+
+### Adding Categories
+
+Edit `src/actions/classify-request.ts` to add new categories to the `category` enum and update the Zai label definitions.
+
+### Changing Routing Logic
+
+Edit `src/workflows/triage-flow.ts` to customize how requests are routed. You can add steps for priority escalation, duplicate detection, or SLA tracking.
+
+### Adding Channels
+
+Create new conversation handlers in `src/conversations/` for other Slack channels or platforms (e.g., `slack-channel.ts` for public channel responses).
+
+## Learn More
+
+- [ADK Documentation](https://botpress.com/docs/adk)
+- [Botpress Platform](https://botpress.com)