@botpress/adk 1.16.7 → 1.18.0-beta.1

package/dist/templates/blank/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/blank/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/blank/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/crm-enrichment/README.md

@@ -0,0 +1,85 @@
+# {{projectName}}
+
+A backend CRM enrichment agent built with the Botpress ADK. This agent runs scheduled workflows to classify, score, and enrich contacts in a table using AI -- no chat interface required.
+
+## How It Works
+
+1. **Contacts table** (`src/tables/contacts.ts`) stores raw and enriched contact data.
+2. **Enrich action** (`src/actions/enrich-contact.ts`) uses Zai to classify a single contact's use case, industry, and lead score.
+3. **Enrichment pipeline** (`src/workflows/enrichment-pipeline.ts`) fetches unenriched contacts, enriches each one, and writes results back.
+4. **Daily trigger** (`src/triggers/daily-enrichment.ts`) kicks off the pipeline on a schedule and on initial bot registration.
+
+## Getting Started
+
+1. Install dependencies:
+
+   ```bash
+   {{packageManager}} install
+   ```
+
+2. Start development server:
+
+   ```bash
+   adk dev
+   ```
+
+3. Add some contacts to the `ContactsTable` (via `adk run` script or the dev UI), then watch the enrichment pipeline process them.
+
+4. Deploy your agent:
+   ```bash
+   adk deploy
+   ```
+
+## Customizing the Enrichment Logic
+
+The core AI classification lives in `src/actions/enrich-contact.ts`. You can customize:
+
+- **Use case categories** -- edit the `useCase` enum in the Zai extract schema to match your business.
+- **Industry list** -- expand or narrow the `industry` enum.
+- **Scoring criteria** -- change the `score` enum and the `instructions` string to reflect your ideal customer profile.
+- **Additional fields** -- add more columns to the table and more fields to the extract schema.
+
+## Scheduling
+
+The workflow runs on a cron schedule defined in `src/workflows/enrichment-pipeline.ts`:
+
+```typescript
+schedule: '0 9 * * *' // Every day at 9:00 AM UTC
+```
+
+Common alternatives:
+
+- `"0 */6 * * *"` -- every 6 hours
+- `"0 9 * * 1-5"` -- weekday mornings only
+- `"*/30 * * * *"` -- every 30 minutes
+
+The trigger in `src/triggers/daily-enrichment.ts` also fires on `register` (bot startup) so the pipeline runs once immediately during development.
+
+## Adding Integrations
+
+This template starts with no integrations. To extend it:
+
+```bash
+# Send enrichment reports to Slack
+adk add slack@latest
+
+# Sync contacts from a CRM
+adk add salesforce@latest
+
+# Send email summaries
+adk add sendgrid@latest
+```
+
+## Project Structure
+
+- `src/tables/` -- ContactsTable schema
+- `src/actions/` -- AI enrichment action
+- `src/workflows/` -- Enrichment pipeline workflow
+- `src/triggers/` -- Scheduled trigger
+- `src/conversations/` -- Unused (backend agent)
+- `src/knowledge/` -- Unused (no RAG needed)
+
+## Learn More
+
+- [ADK Documentation](https://botpress.com/docs/adk)
+- [Botpress Platform](https://botpress.com)

package/dist/templates/crm-enrichment/agent.config.ts

@@ -0,0 +1,33 @@
+import { z, defineConfig } from '@botpress/runtime'
+
+export default defineConfig({
+  name: '{{projectName}}',
+  description:
+    'A backend agent that enriches CRM contacts with AI-driven classification, scoring, and industry detection',
+
+  defaultModels: {
+    autonomous: 'openai:gpt-4.1-mini-2025-04-14',
+    zai: 'openai:gpt-4.1-2025-04-14',
+  },
+
+  // Bot-level persistent state — tracks enrichment run metadata across executions.
+  bot: {
+    state: z.object({
+      lastEnrichmentRunAt: z.string().optional().describe('ISO timestamp of the last completed enrichment run'),
+      totalContactsEnriched: z.number().default(0).describe('Cumulative count of contacts enriched across all runs'),
+    }),
+  },
+
+  // Per-user state is unused in this backend-only agent.
+  user: {
+    state: z.object({}),
+  },
+
+  // No integration dependencies — this is a pure backend workflow agent.
+  // If you want to send enrichment reports to Slack or email, add integrations here:
+  //   adk add slack@latest
+  //   adk add sendgrid@latest
+  dependencies: {
+    integrations: {},
+  },
+})

package/dist/templates/crm-enrichment/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "{{projectName}}",
+  "version": "1.0.0",
+  "description": "A CRM enrichment agent built with the ADK — scheduled workflows that classify and score contacts using AI",
+  "type": "module",
+  "scripts": {
+    "dev": "adk dev",
+    "build": "adk build",
+    "deploy": "adk deploy"
+  },
+  "dependencies": {
+    "@botpress/runtime": "^{{runtimeVersion}}"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/dist/templates/crm-enrichment/src/actions/enrich-contact.ts

@@ -0,0 +1,81 @@
+import { Action, z, adk } from '@botpress/runtime'
+
+/**
+ * Enriches a single contact using AI classification.
+ *
+ * Given a contact's name, email, and company, this action uses Zai to extract:
+ *   - industry: what sector the company operates in
+ *   - useCase: what they would most likely use the product for
+ *   - score: a lead quality rating (high / medium / low)
+ *
+ * Customization points:
+ *   - Change the enum values to match your business categories.
+ *   - Edit the `instructions` to reflect your ideal customer profile.
+ *   - Add more extracted fields (e.g. companySize, region, buyerPersona).
+ */
+export const enrichContact = new Action({
+  name: 'enrichContact',
+  description: 'Classify a CRM contact using AI to determine industry, use case, and lead score',
+
+  input: z.object({
+    name: z.string().describe('Full name of the contact'),
+    email: z.string().describe('Contact email address'),
+    company: z.string().describe('Company or organization name'),
+  }),
+
+  output: z.object({
+    industry: z.string().describe('Classified industry'),
+    useCase: z.string().describe('Classified use case'),
+    score: z.enum(['high', 'medium', 'low']).describe('Lead quality score'),
+  }),
+
+  async handler({ input }) {
+    // Build a text summary for the AI to classify.
+    const contactSummary = [`Name: ${input.name}`, `Email: ${input.email}`, `Company: ${input.company}`].join('\n')
+
+    // Use Zai extract to pull structured classification from the contact info.
+    // The AI infers industry, use case, and score from the name, email domain, and company.
+    const enriched = await adk.zai.extract(
+      contactSummary,
+      z.object({
+        industry: z
+          .enum([
+            'Technology',
+            'Healthcare',
+            'Finance',
+            'Retail',
+            'Education',
+            'Manufacturing',
+            'Media',
+            'Government',
+            'Other',
+          ])
+          .describe('The primary industry the company operates in'),
+
+        useCase: z
+          .enum([
+            'Customer Support',
+            'Sales Automation',
+            'Internal Helpdesk',
+            'Lead Generation',
+            'Knowledge Management',
+            'Other',
+          ])
+          .describe('The most likely use case for a conversational AI product'),
+
+        score: z.enum(['high', 'medium', 'low']).describe('Lead quality score based on company fit and likely intent'),
+      }),
+      {
+        instructions: [
+          'Classify this CRM contact based on their name, email domain, and company.',
+          'For industry: infer from the company name and email domain.',
+          'For useCase: estimate the most likely reason they would adopt a conversational AI platform.',
+          "For score: rate as 'high' if the company is mid-market or enterprise in a strong vertical,",
+          "'medium' for smaller companies or less obvious fit, 'low' for generic or unclear profiles.",
+        ].join(' '),
+      }
+    )
+
+    return enriched
+  },
+})

package/dist/templates/crm-enrichment/src/conversations/index.ts

@@ -0,0 +1,14 @@
+// This template is a backend-only agent — no conversation handler is needed.
+// If you want to add a chat interface (e.g. to let users query enriched contacts),
+// uncomment below and install a channel integration: adk add webchat@latest
+//
+// import { Conversation } from '@botpress/runtime'
+//
+// export default new Conversation({
+//   channel: '*',
+//   handler: async ({ execute }) => {
+//     await execute({
+//       instructions: 'You are a CRM assistant. Help users look up enriched contacts.',
+//     })
+//   },
+// })

package/dist/templates/crm-enrichment/src/knowledge/index.ts

@@ -0,0 +1,17 @@
+// This template does not use a knowledge base.
+// If you want to ground the enrichment logic with domain-specific documents
+// (e.g. an ICP definition, industry taxonomy, or company database), you can
+// add a knowledge base here and reference it in the enrichment action.
+//
+// import { Knowledge, DataSource } from '@botpress/runtime'
+//
+// const icpDocs = DataSource.Directory.fromPath('src/knowledge', {
+//   id: 'icp-docs',
+//   filter: (filePath) => filePath.endsWith('.md') || filePath.endsWith('.pdf'),
+// })
+//
+// export const IcpKnowledge = new Knowledge({
+//   name: 'icp-knowledge',
+//   description: 'Ideal Customer Profile definitions and industry taxonomy',
+//   sources: [icpDocs],
+// })

package/dist/templates/crm-enrichment/src/tables/contacts.ts

@@ -0,0 +1,43 @@
+import { Table, z } from '@botpress/runtime'
+
+/**
+ * ContactsTable stores CRM contacts along with their AI-enriched metadata.
+ *
+ * Columns like `name` and `company` are searchable so you can use semantic search
+ * to find contacts by fuzzy name/company queries.
+ *
+ * The enrichment fields (`useCase`, `industry`, `score`, `enrichedAt`) start empty
+ * and are populated by the enrichment pipeline workflow.
+ *
+ * To customize: add columns for phone, title, source, deal stage, etc.
+ */
+export const ContactsTable = new Table({
+  name: 'ContactsTable',
+  description: 'CRM contacts with AI-enriched classification data',
+
+  columns: {
+    // -- Core contact fields --
+
+    name: {
+      searchable: true,
+      schema: z.string().describe('Full name of the contact'),
+    },
+
+    email: z.string().describe('Contact email address'),
+
+    company: {
+      searchable: true,
+      schema: z.string().describe('Company or organization name'),
+    },
+
+    // -- AI-enriched fields (populated by the enrichment pipeline) --
+
+    industry: z.string().optional().describe('AI-classified industry (e.g. Technology, Healthcare, Finance)'),
+
+    useCase: z.string().optional().describe('AI-classified use case (e.g. Customer Support, Sales Automation)'),
+
+    score: z.string().optional().describe('AI-assigned lead score: high, medium, or low'),
+
+    enrichedAt: z.string().optional().describe('ISO timestamp of when this contact was last enriched'),
+  },
+})

package/dist/templates/crm-enrichment/src/triggers/daily-enrichment.ts

@@ -0,0 +1,30 @@
+import { Trigger } from '@botpress/runtime'
+import { EnrichmentPipeline } from '../workflows/enrichment-pipeline'
+
+/**
+ * Fires on bot registration (startup) to kick off an initial enrichment run.
+ *
+ * The enrichment pipeline also has its own cron schedule ("0 9 * * *"),
+ * which handles recurring daily runs automatically. This trigger ensures the
+ * pipeline runs once immediately when the bot first starts -- useful during
+ * development and after fresh deployments.
+ *
+ * To add more trigger events:
+ *   - "user.created" -- enrich new contacts as they arrive
+ *   - Custom events from integrations (e.g. "salesforce:contactCreated")
+ */
+export default new Trigger({
+  name: 'dailyEnrichment',
+  description: 'Starts the enrichment pipeline on bot registration for an initial run',
+  events: ['register'],
+
+  handler: async () => {
+    console.log('Bot registered. Starting initial enrichment pipeline run...')
+
+    const instance = await EnrichmentPipeline.start({
+      batchSize: 50,
+    })
+
+    console.log(`Enrichment pipeline started: ${instance.id}`)
+  },
+})

package/dist/templates/crm-enrichment/src/workflows/enrichment-pipeline.ts

@@ -0,0 +1,171 @@
+import { bot, Workflow, z, actions } from '@botpress/runtime'
+import { ContactsTable } from '../tables/contacts'
+
+/**
+ * Enrichment pipeline workflow.
+ *
+ * This scheduled workflow:
+ *   1. Fetches contacts that have not been enriched yet.
+ *   2. Enriches each contact via the enrichContact action (AI classification).
+ *   3. Writes the enrichment results back to the ContactsTable.
+ *   4. Updates bot state with run metadata and logs a summary.
+ *
+ * The workflow uses steps for each phase so progress is checkpointed. If it
+ * crashes mid-run, it resumes from the last completed step on restart.
+ *
+ * Schedule: daily at 9:00 AM UTC (edit the cron expression below).
+ * Timeout: 2 hours to handle large contact lists.
+ */
+export const EnrichmentPipeline = new Workflow({
+  name: 'enrichmentPipeline',
+  description: 'Fetches unenriched CRM contacts, classifies them with AI, and writes results back',
+
+  // Runs every day at 9:00 AM UTC.
+  // Change to "*/30 * * * *" for every 30 minutes during development.
+  schedule: '0 9 * * *',
+
+  // Allow up to 2 hours for large batches.
+  timeout: '2h',
+
+  input: z.object({
+    batchSize: z.number().default(50).describe('Max number of contacts to enrich per run'),
+  }),
+
+  state: z.object({
+    contactsFetched: z.number().default(0),
+    contactsEnriched: z.number().default(0),
+    errors: z.array(z.string()).default([]),
+  }),
+
+  output: z.object({
+    enriched: z.number().describe('Number of contacts enriched this run'),
+    errors: z.number().describe('Number of contacts that failed enrichment'),
+    summary: z.string().describe('Human-readable run summary'),
+  }),
+
+  async handler({ input, state, step }) {
+    // ---------------------------------------------------------------
+    // Step 1: Fetch unenriched contacts
+    // ---------------------------------------------------------------
+    const unenrichedContacts = await step('fetch-unenriched-contacts', async () => {
+      const { rows } = await ContactsTable.findRows({
+        filter: { enrichedAt: null as unknown as string },
+        limit: input.batchSize,
+      })
+
+      return rows
+    })
+
+    state.contactsFetched = unenrichedContacts.length
+
+    if (unenrichedContacts.length === 0) {
+      console.log('No unenriched contacts found. Skipping run.')
+      return {
+        enriched: 0,
+        errors: 0,
+        summary: 'No unenriched contacts to process.',
+      }
+    }
+
+    console.log(`Found ${unenrichedContacts.length} unenriched contacts. Starting enrichment...`)
+
+    // ---------------------------------------------------------------
+    // Step 2: Enrich each contact via the action
+    // ---------------------------------------------------------------
+    const enrichmentResults = await step('enrich-contacts', async () => {
+      const results: Array<{
+        id: number
+        industry: string
+        useCase: string
+        score: string
+        success: boolean
+        error?: string
+      }> = []
+
+      for (const contact of unenrichedContacts) {
+        try {
+          const enriched = await actions.enrichContact({
+            name: contact.name,
+            email: contact.email,
+            company: contact.company,
+          })
+
+          results.push({
+            id: contact.id,
+            industry: enriched.industry,
+            useCase: enriched.useCase,
+            score: enriched.score,
+            success: true,
+          })
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error)
+          console.error(`Failed to enrich contact ${contact.id} (${contact.name}): ${message}`)
+          results.push({
+            id: contact.id,
+            industry: '',
+            useCase: '',
+            score: '',
+            success: false,
+            error: message,
+          })
+        }
+      }
+
+      return results
+    })
+
+    // ---------------------------------------------------------------
+    // Step 3: Write enrichment results back to the table
+    // ---------------------------------------------------------------
+    await step('update-contacts', async () => {
+      const now = new Date().toISOString()
+      const successfulResults = enrichmentResults.filter((r) => r.success)
+
+      if (successfulResults.length === 0) {
+        console.log('No successful enrichments to write back.')
+        return
+      }
+
+      await ContactsTable.updateRows({
+        rows: successfulResults.map((r) => ({
+          id: r.id,
+          industry: r.industry,
+          useCase: r.useCase,
+          score: r.score,
+          enrichedAt: now,
+        })),
+      })
+
+      console.log(`Updated ${successfulResults.length} contacts in the table.`)
+    })
+
+    // ---------------------------------------------------------------
+    // Step 4: Update bot state and log summary
+    // ---------------------------------------------------------------
+    const successCount = enrichmentResults.filter((r) => r.success).length
+    const errorCount = enrichmentResults.filter((r) => !r.success).length
+
+    state.contactsEnriched = successCount
+    state.errors = enrichmentResults.filter((r) => !r.success).map((r) => `Contact ${r.id}: ${r.error}`)
+
+    // Persist metadata in global bot state for cross-run tracking.
+    bot.state.lastEnrichmentRunAt = new Date().toISOString()
+    bot.state.totalContactsEnriched = (bot.state.totalContactsEnriched ?? 0) + successCount
+
+    const summary = [
+      `Enrichment run complete.`,
+      `Processed: ${unenrichedContacts.length}`,
+      `Enriched: ${successCount}`,
+      `Errors: ${errorCount}`,
+      `Total enriched (all-time): ${bot.state.totalContactsEnriched}`,
+    ].join(' | ')
+
+    console.log(summary)
+
+    return {
+      enriched: successCount,
+      errors: errorCount,
+      summary,
+    }
+  },
+})

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

@@ -0,0 +1,46 @@
+# {{projectName}}
+
+A Botpress Agent built with the ADK, pre-configured with chat and webchat integrations.
+
+## Getting Started
+
+1. Install dependencies:
+
+   ```bash
+   {{packageManager}} install
+   ```
+
+2. Start development server:
+
+   ```bash
+   adk dev
+   ```
+
+3. Chat with your agent locally:
+
+   ```bash
+   adk chat
+   ```
+
+4. Deploy your agent:
+   ```bash
+   adk deploy
+   ```
+
+## Project Structure
+
+- `src/actions/` - Define callable functions
+- `src/workflows/` - Define long-running processes
+- `src/conversations/` - Define conversation handlers
+- `src/tables/` - Define data storage schemas
+- `src/triggers/` - Define event subscriptions
+- `src/knowledge/` - Add knowledge base files
+
+## Integrations
+
+This agent comes with **chat** and **webchat** integrations enabled, so you can start talking to it right away with `adk chat`.
+
+## Learn More
+
+- [ADK Documentation](https://botpress.com/docs/adk)
+- [Botpress Platform](https://botpress.com)