@botpress/adk 1.17.0 → 1.18.0-beta.1

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)

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"]
+}