From fc8b1df782cbdf6945cc0b85e2ff905b90125426 Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Tue, 21 Apr 2026 21:17:51 -0400 Subject: [PATCH 01/29] remove default expand --- docs.json | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs.json b/docs.json index d5f4849a..1a0d69d6 100644 --- a/docs.json +++ b/docs.json @@ -91,7 +91,6 @@ "pages": [ { "group": "Get Started", - "expanded": true, "pages": [ "/adk/get-started/welcome", "/adk/get-started/quickstart" @@ -99,7 +98,6 @@ }, { "group": "Setting up your agent", - "expanded": true, "pages": [ "/adk/setup/configuration", "/adk/setup/environment", @@ -108,7 +106,6 @@ }, { "group": "Handling conversations", - "expanded": true, "pages": [ "/adk/conversations/setup", "/adk/conversations/ai-execution", @@ -121,7 +118,6 @@ }, { "group": "Handling longform logic", - "expanded": true, "pages": [ "/adk/workflows/create", "/adk/workflows/steps", @@ -130,7 +126,6 @@ }, { "group": "Actions and triggers", - "expanded": true, "pages": [ "/adk/external/actions", "/adk/external/triggers" @@ -138,7 +133,6 @@ }, { "group": "Working with data", - "expanded": true, "pages": [ "/adk/data/tables", "/adk/data/knowledge" @@ -146,7 +140,6 @@ }, { "group": "Testing and debugging", - "expanded": true, "pages": [ "/adk/testing/evals", "/adk/testing/agent-steps", @@ -156,7 +149,6 @@ }, { "group": "LLM Utilities", - "expanded": true, "pages": [ "/adk/zai/overview", "/adk/zai/extract", @@ -166,21 +158,18 @@ }, { "group": "AI Native Development", - "expanded": true, "pages": [ "/adk/ai-native/skills" ] }, { "group": "Advanced", - "expanded": true, "pages": [ "/adk/advanced/hitl" ] }, { "group": "CLI", - "expanded": true, "pages": [ "/adk/cli-reference" ] From 22537f70638f9eee41c5d5cbbc0c23f9c15d9ebf Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Wed, 22 Apr 2026 12:01:48 -0400 Subject: [PATCH 02/29] align get started section --- adk/get-started/quickstart.mdx | 94 ------------ .../welcome.mdx => introduction.mdx} | 17 ++- adk/quickstart.mdx | 138 ++++++++++++++++++ docs.json | 9 +- index.mdx | 2 +- 5 files changed, 150 insertions(+), 110 deletions(-) delete mode 100644 adk/get-started/quickstart.mdx rename adk/{get-started/welcome.mdx => introduction.mdx} (67%) create mode 100644 adk/quickstart.mdx diff --git a/adk/get-started/quickstart.mdx b/adk/get-started/quickstart.mdx deleted file mode 100644 index af09ae04..00000000 --- a/adk/get-started/quickstart.mdx +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Quickstart -description: This guide walks you through installing the ADK and creating your first agent project. ---- - -By the end of this guide, you'll have a working AI agent that responds to messages on webchat. It takes about 5 minutes. - - - You'll need [Node.js](https://nodejs.org/) 22.0.0 or higher and a [Botpress account](https://sso.botpress.cloud). - - -## Install the ADK CLI - - - - ```bash - curl -fsSL https://github.com/botpress/adk/releases/latest/download/install.sh | bash - ``` - - - ```powershell - powershell -c "irm https://github.com/botpress/adk/releases/latest/download/install.ps1 | iex" - ``` - - - -Open a new terminal, then verify the installation: - -```bash -adk --version -``` - -Log in to your Botpress account: - -```bash -adk login -``` - -A browser window opens for sign-in. Once complete, the CLI stores your credentials locally. - -## Create your agent - -```bash -adk init my-agent -``` - -The wizard walks you through three steps: - -1. **Select a template.** Pick `hello-world`. This creates a simple agent that responds to webchat messages using an AI model. -2. **Select a package manager.** We recommend [bun](https://bun.sh) for the fastest experience. npm, pnpm, and yarn also work. If you only have one installed, this step is skipped. -3. **Link to Botpress.** Select the workspace you want to deploy to. The CLI creates a bot in that workspace and connects your project to it. - -The CLI then installs dependencies and sets up your project. When it's done: - -```bash -cd my-agent -``` - -## Start the dev server - -```bash -adk dev -``` - -This builds your agent, deploys it to a development bot on Botpress Cloud, and starts the dev console (default port 3001). Press `space` in the terminal to open it in your browser. - -The dev console is your local control panel for building and debugging. You can chat with your agent, browse its components (actions, workflows, triggers), manage data (tables, knowledge bases, files), run evals, inspect traces and logs, and configure integrations. - -Go to the **Chat** page and send a message. Your agent responds. - - - ADK dev console - ADK dev console - - -The dev server watches your files and rebuilds on every change. - -## Deploy to Botpress Cloud - -When you're ready to go live: - -```bash -adk deploy -``` - -This builds your agent for production, runs preflight checks (integration changes, config diffs), syncs your knowledge bases and tables, and uploads everything to Botpress Cloud. The CLI walks you through any changes that need approval before deploying. - -Once deployed, your agent is live in the workspace you linked during `adk init`. - -Next, learn what's in the project you just created and how to configure it. - - - Project structure, models, state, and dependencies. - diff --git a/adk/get-started/welcome.mdx b/adk/introduction.mdx similarity index 67% rename from adk/get-started/welcome.mdx rename to adk/introduction.mdx index 528cc02a..a1f111d4 100644 --- a/adk/get-started/welcome.mdx +++ b/adk/introduction.mdx @@ -1,16 +1,17 @@ --- -title: Botpress ADK -sidebarTitle: Welcome -description: The Botpress Agent Development Kit (ADK) is a developer-first TypeScript framework for building AI agents on the Botpress Platform. +title: Introduction to the ADK +description: TypeScript framework for building AI agents on Botpress. --- +The Agent Development Kit (ADK) is a **CLI tool and development framework for building AI agents on Botpress**. It provides a streamlined development experience with TypeScript support, hot reloading, and type-safe APIs for creating AI applications. + +You write conversations, workflows, tools, and actions as code. Botpress handles hosting, scaling, and channel delivery. + - Botpress ADK - Botpress ADK + Botpress ADK + Botpress ADK -The ADK is a TypeScript framework for building AI agents that run on the Botpress Platform. You write conversations, workflows, tools, and actions as code. The platform handles hosting, scaling, and channel delivery. - ## What you can build - **Customer support agents** that resolve tickets, look up orders, and escalate to humans @@ -46,7 +47,7 @@ Each primitive lives in its own file under `src/`. The ADK discovers them automa ## Start here - + Install the ADK and deploy your first agent in minutes. diff --git a/adk/quickstart.mdx b/adk/quickstart.mdx new file mode 100644 index 00000000..41b1b597 --- /dev/null +++ b/adk/quickstart.mdx @@ -0,0 +1,138 @@ +--- +title: Quickstart +description: This guide walks you through installing the ADK and creating your first agent project. +--- + +By the end of this guide, you'll have a working AI agent that responds to messages on Webchat. It takes about 5 minutes. + + + You will need: + + * A [Botpress account](https://sso.botpress.cloud) + * [Node.js](https://nodejs.org/en) (v22.0.0 or higher) + * A supported package manager — [bun](https://bun.sh), [pnpm](https://pnpm.io), [yarn](https://yarnpkg.com) or [npm](https://www.npmjs.com) + + +## Installation + +Install the ADK CLI globally: + + + ```bash macOS & Linux theme={"theme":{"light":"light-plus","dark":"dark-plus"}} + curl -fsSL https://github.com/botpress/adk/releases/latest/download/install.sh | bash + ``` + + ```powershell Windows (PowerShell) theme={"theme":{"light":"light-plus","dark":"dark-plus"}} + powershell -c "irm https://github.com/botpress/adk/releases/latest/download/install.ps1 | iex" + ``` + + +Then, verify the installation: + +```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}} +adk --version +``` + +Log in to your Botpress account: + +```bash +adk login +``` + +This will open a browser window for authentication. Once complete, the CLI stores your credentials locally. + +## Create your agent + +Initialize a new agent project: + +```bash +adk init my-agent +``` + +The wizard walks you through three steps: + +1. **Select a template**: Pick `hello-world`. This creates a simple agent that responds to webchat messages using an AI model. +2. **Select a package manager**: We recommend [bun](https://bun.sh) for the fastest experience. npm, pnpm, and yarn also work. If you only have one installed, this step is skipped. +3. **Link to Botpress**: Select the workspace you want to deploy to. The CLI creates a bot in that workspace and connects your project to it. + +The CLI then automatically installs dependencies and sets up your project in the `my-agent` directory. + +Navigate into your project: + +```bash +cd my-agent +``` + +## Test your agent + +Now, you’re ready to test your agent. + +### Start the development server + +Start the development server with hot reloading: + +```bash +adk dev +``` + +This builds your agent, deploys it to a development bot on Botpress, and starts the dev console at [`http://localhost:3001/`](http://localhost:3001/). Press space in the terminal to open it in your browser. + +### View in the dev console + +The dev console is your local control panel for building and debugging. Within the dev console, you can: + +- Chat with your agent +- Browse its components (actions, workflows, triggers) +- Manage data (tables, knowledge bases, files) +- Run evals +- Inspect traces and logs +- Configure integrations + +Go to the **Chat** page and send a message to test your agent: + + + ADK dev console + ADK dev console + + +The dev server watches your files and rebuilds on every change. + +### Chat in the terminal + +Alternatively, open a new terminal window and start a conversation with your agent from the command line: + +```bash +adk chat +``` + +```txt +Botpress Chat +Type "exit" or press ESC key to quit +👤 Hey! +🤖 Hello! How can I assist you today? +>> +``` + +## Deploy your agent + +When you're ready to go live: + +```bash +adk deploy +``` + +This builds your agent for production, runs preflight checks (integration changes, config diffs), syncs your knowledge bases and tables, and uploads everything to Botpress. The CLI walks you through any changes that need approval before deploying. + +Once deployed, your agent is live in the workspace you linked during `adk init`. + + + You deployed your first agent using the ADK! + + +## Next steps + +Next, learn what's in the project you just created and how to configure it: + + + Project structure, models, state, and dependencies. + diff --git a/docs.json b/docs.json index 1a0d69d6..0baae3c0 100644 --- a/docs.json +++ b/docs.json @@ -89,13 +89,8 @@ "group": "ADK", "tag": "Beta", "pages": [ - { - "group": "Get Started", - "pages": [ - "/adk/get-started/welcome", - "/adk/get-started/quickstart" - ] - }, + "/adk/introduction", + "/adk/quickstart", { "group": "Setting up your agent", "pages": [ diff --git a/index.mdx b/index.mdx index 7e0e10b4..ccd30726 100644 --- a/index.mdx +++ b/index.mdx @@ -39,7 +39,7 @@ import { IntegrationsCard } from '/home-components/IntegrationsCard.jsx' title="ADK" img='/homepage-assets/adk.jpg' cta="Get started" - href="/adk/get-started/welcome" + href="/adk/introduction" > TypeScript library for building AI agents from code Beta From 95a4146c425c88780471d0f870b0cf6655b406d5 Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Wed, 22 Apr 2026 14:29:19 -0400 Subject: [PATCH 03/29] audit configuration guide --- adk/setup/configuration.mdx | 113 +++++++++++++++++++++++++----------- 1 file changed, 78 insertions(+), 35 deletions(-) diff --git a/adk/setup/configuration.mdx b/adk/setup/configuration.mdx index c88a4ae5..199ca317 100644 --- a/adk/setup/configuration.mdx +++ b/adk/setup/configuration.mdx @@ -1,33 +1,66 @@ --- -title: Agent Configuration +title: Configuration description: Understand your project structure and how to configure your agent. --- ## Project structure -After running `adk init`, your project contains: - -| Path | Purpose | -|------|---------| -| `agent.config.ts` | Agent configuration: models, state, dependencies, secrets | -| `src/conversations/` | Message handlers for user interactions | -| `src/workflows/` | Long-running background processes | -| `src/actions/` | Reusable logic callable from anywhere | -| `src/tools/` | Functions the AI model can call | -| `src/tables/` | Database table schemas | -| `src/knowledge/` | RAG knowledge base sources | -| `src/triggers/` | Event-based handlers | -| `src/evals/` | Automated conversation tests | -| `package.json` | Node.js dependencies | -| `tsconfig.json` | TypeScript settings | +Here's a breakdown of the key files in your project after running `adk init`: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The ADK scans `src/` and discovers primitives automatically. Each file exports a primitive (a `Conversation`, `Workflow`, `Action`, etc.) and the framework registers it at build time. -## agent.config.ts +## `agent.config.ts` -Everything about your agent is configured here using `defineConfig`. This is the hello-world template config with all available fields shown: +Everything about your agent is configured in `agent.config.ts` by calling `defineConfig` and passing in a configuration object. -```typescript +Here's the `hello-world` template default configuration with all available fields shown: + +```typescript expandable import { z, defineConfig } from "@botpress/runtime" export default defineConfig({ @@ -116,14 +149,14 @@ await execute({ ### State -State lets your agent persist data. There are two scopes: +The `state` field lets you define schemas for data that your agent can persist across a certain scope. There are two available scopes: | Scope | Persists across | Use for | |-------|----------------|---------| | `bot` | All conversations and users | Global counters, shared config | | `user` | All conversations for a given user | Preferences, profile data | -Define schemas with Zod. The ADK generates TypeScript types from them, so state access is fully typed: +You can define schemas for state using Zod. The ADK generates TypeScript types from them, so state access is fully typed: ```typescript bot: { @@ -139,11 +172,13 @@ user: { }, ``` -For reading and writing state at runtime, see [Manage states](/adk/conversations/state). + + For more information about reading and writing state at runtime, check out our guide to [managing states](/adk/conversations/state). + ### Tags -Tags are metadata you can attach to bots, users, conversations, messages, and workflows: +The `tags` field lets you define metadata that you can attach to bots, users, conversations, messages, and workflows: ```typescript bot: { @@ -162,7 +197,7 @@ Tags are useful for filtering and organizing data in the Botpress platform. ### Secrets -Secrets store sensitive values like API keys. They are declared here, but values are managed separately per environment and never committed to git: +The `secrets` field lets you store sensitive values, like API keys or tokens. They are declared here, but values are managed separately per environment and never committed to version control: ```typescript secrets: { @@ -171,11 +206,13 @@ secrets: { }, ``` -For the full secrets workflow, see [Environment Setup](/adk/setup/environment). + +For more information about using secrets, check out our guide on [setting up your environment](/adk/setup/environment#secrets). + ### Configuration -Configuration defines static, deploy-time settings. Unlike state, these are read-only at runtime: +The `configuration` field defines static, deploy-time settings. Unlike state, these are read-only at runtime: ```typescript configuration: { @@ -186,7 +223,9 @@ configuration: { }, ``` -For managing configuration values across environments, see [Environment Setup](/adk/setup/environment). + + For managing configuration values across environments, check out our guide to [setting up your environment](/adk/setup/environment#configuration). + ### Dependencies @@ -208,11 +247,13 @@ dependencies: { }, ``` -For finding, configuring, and managing integrations, see [Integrations](/adk/setup/integrations). + +For more information about finding, configuring, and managing integrations, check out our [integrations guide](/adk/setup/integrations). + ### Custom events -Define events your agent can emit and subscribe to: +The `events` field lets you define custom events your agent can emit and subscribe to: ```typescript events: { @@ -226,11 +267,11 @@ events: { }, ``` -Triggers and conversations can listen for custom events. See [Set up triggers](/adk/external/triggers). +You can then listen for these events within triggers and conversations. For more information, check out our guide on [setting up triggers](/adk/external/triggers). ### Evals -Configure how automated tests run: +The `evals` field lets you configure how your agent's automated tests run: ```typescript evals: { @@ -246,12 +287,14 @@ evals: { | `judgePassThreshold` | Pass threshold for LLM judge assertions (1-5) | | `judgeModel` | Model used for LLM judge assertions | -For writing and running evals, see [Write and run evals](/adk/testing/evals). + + For more information, check out our full guide to [writing and running evals](/adk/testing/evals). + ---- +## Next steps -Next, learn how to manage secrets and configuration values across dev and production environments. +Next, learn how to manage secrets and configuration values across development and production environments: - Secrets, configuration values, and dev vs prod environments. + Secrets, configuration values, and development/production environments. From ceb76bc4c31a7b8a2f17009d0c199d1850019e0c Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Wed, 22 Apr 2026 14:31:44 -0400 Subject: [PATCH 04/29] quick fix to quickstart description --- adk/quickstart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adk/quickstart.mdx b/adk/quickstart.mdx index 41b1b597..34f656f5 100644 --- a/adk/quickstart.mdx +++ b/adk/quickstart.mdx @@ -1,6 +1,6 @@ --- title: Quickstart -description: This guide walks you through installing the ADK and creating your first agent project. +description: Install the ADK and create your first agent project. --- By the end of this guide, you'll have a working AI agent that responds to messages on Webchat. It takes about 5 minutes. From ce64b70751ff28ba7669760b942970a39bc5b0f4 Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Wed, 22 Apr 2026 17:01:05 -0400 Subject: [PATCH 05/29] audit environment setup guide --- adk/setup/environment.mdx | 62 +++++++++++++++++++-------------------- 1 file changed, 30 insertions(+), 32 deletions(-) diff --git a/adk/setup/environment.mdx b/adk/setup/environment.mdx index f5800033..698f7eb6 100644 --- a/adk/setup/environment.mdx +++ b/adk/setup/environment.mdx @@ -1,11 +1,15 @@ --- -title: Environment Setup -description: Manage secrets, configuration values, and dev vs prod environments. +title: Environment setup +description: Manage secrets, configuration values, and development/production environments. --- The ADK separates development and production into two environments. Secrets and configuration values are stored per environment, so your dev API keys never touch production. -You can switch between environments in the dev console using the environment selector in the top bar. This controls which environment's secrets, configuration, and data you see and edit. You can also toggle it with `Cmd+Shift+E` (Mac) or `Ctrl+Shift+E` (Windows/Linux). +You can switch between environments in the dev console using the environment toggle in the upper-right corner. This controls which environment's secrets, configuration, and data you view/edit. + + +You can also toggle between environments with Cmd + Shift + E (Mac) or Ctrl + Shift + E (Windows/Linux). + Environment selector in dev console @@ -16,7 +20,7 @@ You can switch between environments in the dev console using the environment sel Your project has three files that manage environment state: -| File | Contains | Committed to git | +| File | Contains | Committed to version control | |------|----------|-----------------| | `agent.json` | Production bot ID, workspace ID, API URL | Yes | | `agent.local.json` | Development bot ID | No (gitignored) | @@ -39,29 +43,27 @@ secrets: { }, ``` -Required secrets (the default) are enforced at deploy time. `adk dev` warns if they're unset but doesn't block. Optional secrets never block. +Required secrets (the default) are enforced at deploy time. `adk dev` warns you if they're unset, but doesn't block the dev server from starting. Optional secrets never block deployment. ### Setting values +You can set values using `adk secret:set` command: + ```bash adk secret:set OPENAI_KEY "sk-..." adk secret:set OPENAI_KEY "sk-prod-..." --prod ``` -Dev and prod values are stored in separate buckets inside `.adk/secrets.json`. Setting a dev value never touches prod, and vice versa. +Development and production values are stored in separate buckets inside `.adk/secrets.json`. Setting a development value never touches production values, and vice versa. -### CLI reference - -| Command | What it does | -|---------|-------------| -| `adk secret` | List all declared secrets and their set/unset status | -| `adk secret:set KEY VALUE` | Set a secret for dev | -| `adk secret:set KEY VALUE --prod` | Set a secret for prod | -| `adk secret:delete KEY` | Delete a secret from dev | -| `adk secret:delete KEY --prod` | Delete a secret from prod | + + Check out the [CLI reference](fix-before-merge) for full documentation of the `adk secret` command. + ### Using secrets at runtime +To use secrets at runtime, just import `secrets` from `@botpress/runtime` and reference them directly: + ```typescript import { secrets } from "@botpress/runtime" @@ -74,11 +76,15 @@ if (secrets.SENTRY_DSN) { } ``` -The `secrets` import is a typed proxy over environment variables. Required secrets are typed as `string`, optional ones as `string | undefined`. It's read-only. Assigning to `secrets.X` throws. +The `secrets` import is a typed proxy over environment variables. Required secrets are typed as `string`, optional ones as `string | undefined`. + + + Secrets are read-only at runtime. Attempting to reassign the value of a secret will throw an error. + ### Managing secrets in the dev console -You can also manage secrets from the dev console under **Settings > Secrets**. The UI lets you add, edit, and delete secrets for both dev and prod environments. Schema changes (adding or removing declarations) write back to `agent.config.ts`. +You can also manage secrets from the dev console under **Settings > Secrets**. The UI lets you add, edit, and delete secrets for both development and production environments. Schema changes (adding or removing declarations) write back to `agent.config.ts`. Secrets management in dev console @@ -94,23 +100,15 @@ Secret keys must be `SCREAMING_SNAKE_CASE`: - No trailing underscore - Cannot start with `SECRET_`, `BP_`, or `BOTPRESS_` (reserved) -| Key | Valid | Why | -|-----|-------|-----| -| `MY_API_KEY` | Yes | | -| `DB_PASSWORD` | Yes | | -| `A1` | Yes | Minimum 2 chars, starts with letter | -| `A` | No | Too short | -| `my_key` | No | Must start with uppercase | -| `SECRET_FOO` | No | Reserved prefix | -| `BP_TOKEN` | No | Reserved prefix | - ### How secrets flow to production -Dev secret saves restart the running bot immediately. Prod secret saves only write the local file. Prod values reach Botpress Cloud on the next `adk deploy`. +**Development secrets**: If you're running your agent with `adk dev` and save changes to your development secrets via the dev console, your agent will immediately restart using the new values. + +**Production secrets**: If you save changes to your production secrets via the dev console, the changes will only write to `agent.config.ts`. The new values will take effect on your production agent the next time you run `adk deploy`. ## Configuration -Configuration defines static, deploy-time settings for your agent. Unlike secrets, configuration values are not sensitive. Unlike state, they are read-only at runtime. +The `configuration` object in `agent.config.ts` defines static, deploy-time settings for your agent. Unlike secrets, configuration values are not sensitive. Unlike state, they are read-only at runtime. ### Declaring a schema @@ -144,7 +142,7 @@ const email = configuration.supportEmail const retries = configuration.maxRetries ``` -Configuration is read-only. Attempting to set a value at runtime throws. +Configuration is read-only. Attempting to set a value at runtime throws an error. ### Dev console @@ -171,10 +169,10 @@ This checks: Preflight checks also run automatically during `adk dev` and `adk deploy`. ---- +## Next steps Next, learn how to connect your agent to channels and external services. - + Find, add, and configure integrations. From 7be95f40dc9271cfd9c132cb5bb247befd903a24 Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Wed, 22 Apr 2026 17:11:58 -0400 Subject: [PATCH 06/29] audit integrations --- adk/setup/integrations.mdx | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/adk/setup/integrations.mdx b/adk/setup/integrations.mdx index de6688ea..c4c3a509 100644 --- a/adk/setup/integrations.mdx +++ b/adk/setup/integrations.mdx @@ -3,7 +3,7 @@ title: Integrations description: Connect your agent to channels and external services. --- -Integrations connect your agent to the outside world. They provide channels (webchat, Slack, WhatsApp) and external services (Gmail, Linear, Stripe). +Integrations connect your agent to the outside world. They provide channels (Webchat, Slack, WhatsApp) and external services (Gmail, Linear, Stripe). ## Browsing and managing integrations @@ -23,7 +23,9 @@ Many integrations require configuration (API keys, tokens, webhook URLs). After Integration configuration in dev console -Integration configuration is stored directly on Botpress Cloud, not in your project files. Your dev bot and prod bot each have their own configuration, so you can use different API keys or settings per environment. This is separate from agent secrets, which your code reads directly. +Integration configuration is stored directly on Botpress' servers, not in your local project files. This differs from your agent's secrets, which your code reads directly. + +Your development bot and production bot each have their own configuration, so you can use different API keys or settings per environment. ## Enabling and disabling @@ -46,7 +48,7 @@ dependencies: { Disabled integrations are still part of your project (types are generated, code can reference them) but they won't be active when your agent runs. -## CLI +## Managing integrations using the CLI You can also manage integrations from the command line: @@ -60,10 +62,16 @@ You can also manage integrations from the command line: | `adk upgrade ` | Update an integration to a newer version | | `adk remove ` | Remove an integration from your project | -Integrations are added disabled by default. Enable and configure them in the dev console. +Newly added integrations are disabled by default. You can enable and configure them in the dev console. + + + For full documentation on managing integrations via the command line, check out the [CLI reference](/adk/cli-reference). + ## Integration versions +Here's the syntax for referencing integration versions: + | Format | Example | Behavior | |--------|---------|----------| | `name@latest` | `webchat@latest` | Resolves to the newest version | @@ -72,10 +80,10 @@ Integrations are added disabled by default. Enable and configure them in the dev Use `@latest` during development. Pin to specific versions for production deployments. ---- +## Next steps With your agent configured and connected to integrations, you're ready to start building. Next, learn how to handle user messages. - + Handle messages across channels. From 828d32a88710b7cbbc8a8232f9a36ba084a05a80 Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Wed, 22 Apr 2026 17:28:31 -0400 Subject: [PATCH 07/29] audit conversations/setup --- adk/conversations/setup.mdx | 59 ++++++++++++++++++++++++++++--------- 1 file changed, 45 insertions(+), 14 deletions(-) diff --git a/adk/conversations/setup.mdx b/adk/conversations/setup.mdx index 38f0c1a9..9bf2f24c 100644 --- a/adk/conversations/setup.mdx +++ b/adk/conversations/setup.mdx @@ -35,18 +35,45 @@ You can test your conversation using the **Chat** page in the dev console. This The `channel` field determines which integration channels this conversation handles: -```typescript -// Match all channels -channel: "*" - -// Match a specific channel -channel: "webchat.channel" - -// Match multiple channels -channel: ["webchat.channel", "chat.channel"] -``` - -When you use `"*"`, the handler runs for any channel but `message` and `event` are typed as `unknown`. Specifying a channel gives you strict types on message payloads, event payloads, and the conversation instance: + + ```ts All channels highlight={2} theme={"theme":{"light":"light-plus","dark":"dark-plus"}} + export default new Conversation({ + channel: "*", + handler: async ({ execute }) => { + await execute({ + instructions: "You are a helpful assistant.", + }); + }, + }); + ``` + + ```ts Specific channel highlight={2} theme={"theme":{"light":"light-plus","dark":"dark-plus"}} + export default new Conversation({ + channel: "webchat.channel", + handler: async ({ execute }) => { + await execute({ + instructions: "You are a helpful assistant.", + }); + }, + }); + ``` + + ```ts Array of channels highlight={2-5} theme={"theme":{"light":"light-plus","dark":"dark-plus"}} + export default new Conversation({ + channel: [ + "chat.channel", + "webchat.channel" + ], + handler: async ({ execute }) => { + await execute({ + instructions: "You are a helpful assistant.", + }); + }, + }); + ``` + + +When you use `"*"`, the handler runs for any channel, but `message` and `event` are typed as `unknown`. Specifying a channel gives you strict types on message payloads, event payloads, and the conversation instance: ```typescript // channel: "*" — message.payload is unknown @@ -165,7 +192,7 @@ Events use the format `"integration:eventName"` for integration events, or just Each conversation can declare its own state schema, separate from the bot and user state in `agent.config.ts`: -```typescript +```typescript highlight={3-6} export default new Conversation({ channel: "webchat.channel", state: z.object({ @@ -182,7 +209,11 @@ export default new Conversation({ }) ``` -Conversation state is automatically persisted between handler calls. For more on state scopes (conversation vs bot vs user), see [Manage states](/adk/conversations/state). +Conversation state is automatically persisted between handler calls. + + +For more information about state scopes (conversation vs. bot vs. user), check out our guide on [managing states](/adk/conversations/state). + --- From 7c115c6977fa5a159e4229699e36ee5e0841c401 Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Thu, 23 Apr 2026 11:31:29 -0400 Subject: [PATCH 08/29] audit ai execution guide --- adk/conversations/ai-execution.mdx | 48 +++++++++++++++++++----------- 1 file changed, 31 insertions(+), 17 deletions(-) diff --git a/adk/conversations/ai-execution.mdx b/adk/conversations/ai-execution.mdx index 9c990173..3841eb29 100644 --- a/adk/conversations/ai-execution.mdx +++ b/adk/conversations/ai-execution.mdx @@ -1,15 +1,21 @@ --- title: Run AI agents in a conversation -description: Use execute() to hand messages to the AI model. +description: Use `execute()` to hand messages to the AI model. --- -`execute()` is the primary way your agent responds to users. It starts an AI loop that iterates until the model reaches a conclusion. On each iteration, the model can read the conversation, call tools, and generate code. The loop ends when the model sends a message to the user (and waits for a reply), triggers an exit, or hits the iteration limit (default 10, configurable). +The `execute()` function is the primary way your agent responds to users. It starts an AI loop that iterates until the model reaches a conclusion. On each iteration, the model can read the conversation, call tools, and generate code. -The `await` resolves once the loop finishes. Under the hood, `execute()` is powered by [llmz](https://github.com/botpress/botpress/tree/master/packages/llmz). +The loop ends when the model sends a message to the user (and waits for a reply), triggers an exit, or hits the iteration limit (which defaults to 10 and is configurable). + +The `await` resolves once the loop finishes. + + +Under the hood, `execute()` is powered by [LLMz](https://github.com/botpress/botpress/tree/master/packages/llmz). + ## Basic usage -```typescript +```typescript highlight={4-6} export default new Conversation({ channel: "webchat.channel", handler: async ({ execute }) => { @@ -24,13 +30,15 @@ The model reads the full conversation transcript, follows your instructions, and ## Instructions -Instructions tell the model how to behave. They can be a static string or a function that returns a string: +Pass instructions into the `instructions` field to tell the model how to behave. They can be a static string or a function that returns a string: -```typescript +```typescript highlight={3, 8-13} +// String await execute({ instructions: "You are a helpful assistant that speaks formally.", }) +// Function that returns a string await execute({ instructions: () => { const hour = new Date().getHours() @@ -45,25 +53,29 @@ Instructions are evaluated fresh on each execution. Use a function when you need ## Knowledge -Attach knowledge bases to give the model access to your documents: +Pass knowledge bases into the `knowledge` field to give the model access to your documents: -```typescript +```typescript highlight={6} import { DocsKB } from "../knowledge/docs" -import { FAQKB } from "../knowledge/faq" +import { FaqKB } from "../knowledge/faq" await execute({ instructions: "Answer questions using the documentation.", - knowledge: [DocsKB, FAQKB], + knowledge: [DocsKB, FaqKB], }) ``` -The model automatically searches the knowledge bases when it needs information. Results include citations that trace back to the source documents. See [Knowledge bases](/adk/data/knowledge) for how to define them. +The model automatically searches the knowledge bases when it needs information. Results include citations that trace back to the source documents. + + + For more information on defining knowledge bases, check out the [Knowledge base documentation](/adk/data/knowledge). + ## Tools -Give the model functions it can call: +Give the model functions it can call by passing them into the `tools` field: -```typescript +```typescript highlight={6} import { getWeather } from "../tools/weather" import { createTicket } from "../tools/ticket" @@ -77,7 +89,7 @@ The model decides when to call a tool based on the conversation. For a full guid ## Exits -Exits let the model end execution with a structured result: +Pass in `exits` to let the model end execution with a structured result: ```typescript import { Autonomous, z } from "@botpress/runtime" @@ -104,7 +116,7 @@ if (result.exit?.name === "handoffToHuman") { ## Model override -Override the default model for a specific execution: +You can override the default model for a specific execution: ```typescript await execute({ @@ -126,6 +138,8 @@ The default model is set in `agent.config.ts` under `defaultModels.autonomous`. ## Temperature and reasoning +To control the model's temperature and reasoning effort, use the `temperature` and `reasoningEffort` props: + ```typescript await execute({ instructions: "You are a helpful assistant.", @@ -150,7 +164,7 @@ await execute({ }) ``` -Defaults to 10, clamped between 1 and 100. +The number of iterations defaults to 10 and is clamped between 1 and 100. ## Mode @@ -164,7 +178,7 @@ await execute({ }) ``` -In worker mode, the model processes without sending messages to the conversation. +In worker mode, the model executes without sending messages to the conversation. ## Hooks From bd96ad6410ec492de44b4197472af38b53db59bc Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Thu, 23 Apr 2026 11:37:44 -0400 Subject: [PATCH 09/29] revert next steps sections --- adk/quickstart.mdx | 2 +- adk/setup/configuration.mdx | 2 +- adk/setup/environment.mdx | 2 +- adk/setup/integrations.mdx | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/adk/quickstart.mdx b/adk/quickstart.mdx index 34f656f5..8fd306d9 100644 --- a/adk/quickstart.mdx +++ b/adk/quickstart.mdx @@ -129,7 +129,7 @@ Once deployed, your agent is live in the workspace you linked during `adk init`. You deployed your first agent using the ADK! -## Next steps +--- Next, learn what's in the project you just created and how to configure it: diff --git a/adk/setup/configuration.mdx b/adk/setup/configuration.mdx index 199ca317..58a3c989 100644 --- a/adk/setup/configuration.mdx +++ b/adk/setup/configuration.mdx @@ -291,7 +291,7 @@ evals: { For more information, check out our full guide to [writing and running evals](/adk/testing/evals). -## Next steps +--- Next, learn how to manage secrets and configuration values across development and production environments: diff --git a/adk/setup/environment.mdx b/adk/setup/environment.mdx index 698f7eb6..98e77e63 100644 --- a/adk/setup/environment.mdx +++ b/adk/setup/environment.mdx @@ -169,7 +169,7 @@ This checks: Preflight checks also run automatically during `adk dev` and `adk deploy`. -## Next steps +--- Next, learn how to connect your agent to channels and external services. diff --git a/adk/setup/integrations.mdx b/adk/setup/integrations.mdx index c4c3a509..9d1f12a3 100644 --- a/adk/setup/integrations.mdx +++ b/adk/setup/integrations.mdx @@ -80,7 +80,7 @@ Here's the syntax for referencing integration versions: Use `@latest` during development. Pin to specific versions for production deployments. -## Next steps +--- With your agent configured and connected to integrations, you're ready to start building. Next, learn how to handle user messages. From 6994579fc4342b12a80b9f39fcf6a23a04280e09 Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Thu, 23 Apr 2026 11:53:37 -0400 Subject: [PATCH 10/29] audit tools page --- adk/conversations/tools.mdx | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/adk/conversations/tools.mdx b/adk/conversations/tools.mdx index 0c80be82..d7af1c99 100644 --- a/adk/conversations/tools.mdx +++ b/adk/conversations/tools.mdx @@ -1,5 +1,5 @@ --- -title: Define Tools +title: Define tools description: Give the AI model functions it can call during execution. --- @@ -39,7 +39,7 @@ The `input` and `output` schemas use Zod. Use `.describe()` on each field so the Pass tools to `execute()` via the `tools` array: -```typescript +```typescript highlight={10} import { Conversation } from "@botpress/runtime" import getWeather from "../tools/weather" import createTicket from "../tools/ticket" @@ -61,7 +61,7 @@ The model decides which tools to call based on the conversation. It can call mul You can define tools directly inside a handler without creating a separate file: -```typescript +```typescript highlight={6-15, 19} import { Autonomous, z, Conversation } from "@botpress/runtime" export default new Conversation({ @@ -86,7 +86,7 @@ export default new Conversation({ }) ``` -This is useful for tools that are only relevant to a single conversation. +This is useful for tools that are only relevant to a single type of conversation. ## Writing good descriptions @@ -115,7 +115,7 @@ Tools can throw signals to influence the AI loop without returning a normal resu ### ThinkSignal -Throws context back into the model's reasoning without producing a tool output. Useful when a tool finds no results and you want the model to try a different approach: +A `ThinkSignal` throws context back into the model's reasoning without producing a tool output. This is useful when a tool finds no results and you want the model to try a different approach: ```typescript import { Autonomous } from "@botpress/runtime" @@ -136,9 +136,11 @@ handler: async ({ query }) => { ## Actions as tools -Actions are reusable functions that can be called from anywhere in your agent (conversations, workflows, other actions, or external API clients). Unlike standalone tools, which only exist inside `execute()`, actions are shared primitives. You can convert any action into a tool: +Actions are reusable functions that can be called from anywhere in your agent—conversations, workflows, other actions, or external API clients. Tools only work inside `execute()`, where the AI model decides when to call them based on the conversation. -```typescript +You can convert any action into a tool by calling its `asTool()` method and passing it into `tools`: + +```typescript highlight={8} import { Conversation, actions } from "@botpress/runtime" export default new Conversation({ @@ -152,13 +154,15 @@ export default new Conversation({ }) ``` -See [Build Actions](/adk/external/actions) for how to define actions. + + Check out our guide on [building actions](/adk/external/actions) for more information. + ## Workflows as tools Workflows are long-running background processes that can span multiple steps and run independently of the conversation. Converting a workflow to a tool lets the model kick one off: -```typescript +```typescript highlight={9} import { Conversation } from "@botpress/runtime" import orderWorkflow from "../workflows/order" @@ -173,13 +177,15 @@ export default new Conversation({ }) ``` -See [Create workflows](/adk/workflows/create) for how to define workflows. + + Check out our guide on [creating workflows](/adk/workflows/create) for more information. + ## Calling actions from tools Tools can call actions for reusable logic: -```typescript +```typescript highlight={8} import { Autonomous, actions, z } from "@botpress/runtime" export default new Autonomous.Tool({ From e690a6573cc0698afb2a10e94ad574082728c133 Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Thu, 23 Apr 2026 15:43:26 -0400 Subject: [PATCH 11/29] audit custom components --- adk/conversations/custom-components.mdx | 36 ++++++++++++++----------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/adk/conversations/custom-components.mdx b/adk/conversations/custom-components.mdx index e3586939..b053dc87 100644 --- a/adk/conversations/custom-components.mdx +++ b/adk/conversations/custom-components.mdx @@ -1,11 +1,11 @@ --- title: Use custom components -description: Build and render custom React UI inside webchat. +description: Build and render custom React UI inside Webchat. --- -Custom components let you render your own React UI inside webchat. Instead of being limited to text, images, and carousels, you can build any visual element and have either your code or the LLM send it to users. +Custom components let you render your own React UI inside [Webchat](/webchat/get-started/introduction). Instead of being limited to text, images, and carousels, you can build any visual element and have either your code or the LLM send it to users. -There are two ways to use them: +There are two ways to use custom components: 1. **Direct send** - your handler explicitly sends the component 2. **LLM-driven** - the LLM decides when to render the component during `execute()` @@ -66,11 +66,12 @@ export const TicketCardComponent = new CustomComponent(component) The component is now discoverable by `adk dev` and `adk deploy`. The component name is derived from the React function name (`TicketCard` in this case). -## Sending components directly + +## Sending components manually Send a custom component like any other message: -```typescript +```typescript highlight={7-18} import { Conversation } from "@botpress/runtime" import { TicketCardComponent } from "../components/TicketCard" @@ -101,10 +102,9 @@ To let the LLM decide when to render your component, add LLM metadata and list i ### Add LLM metadata -The second argument to `CustomComponent` tells the LLM what the component does: +The `description` field tells the LLM what the component does: -```typescript -// src/components/TicketCard.ts +```typescript title="TicketCard.ts" highlight={5-6} import { CustomComponent, z } from "@botpress/runtime" import component from "./TicketCard.bp.tsx" @@ -129,9 +129,11 @@ export const TicketCardComponent = new CustomComponent(component, { | `props` | Yes | Zod schema defining the component's props. Use `.describe()` on each field. | | `exampleValues` | Yes | Array of example prop objects. Converted to JSX examples in the LLM prompt. | -### List it in the conversation +### Provide the component to the LLM -```typescript +To provide the component to your agent's LLM, pass it into the `execute()` function's `components` field: + +```typescript highlight={6} import { Conversation } from "@botpress/runtime" import { TicketCardComponent } from "../components/TicketCard" @@ -149,7 +151,9 @@ export default new Conversation({ The LLM now knows about `` and will render it when appropriate during `execute()`. -If you list a component in `components` that was created without LLM metadata, the Conversation constructor throws immediately. + +If you list a component in `components` that was created without LLM metadata, the `Conversation` constructor throws immediately. + ## Combining both approaches @@ -184,11 +188,11 @@ export default new Conversation({ ## Build pipeline -During `adk dev` and `adk deploy`, custom components go through this pipeline: +During `adk dev` and `adk deploy`, custom components go through the following pipeline: 1. **Discover** - scans `src/` for `.ts` files that export `CustomComponent` instances 2. **Resolve** - finds the `.bp.tsx` import in each wrapper -3. **Bundle** - esbuild bundles the `.bp.tsx` into standalone ESM (`react` and `react-dom` are externalized) +3. **Bundle** - `esbuild` bundles the `.bp.tsx` into standalone ESM (`react` and `react-dom` are externalized) 4. **Upload** - the bundle is uploaded to Botpress as a public file 5. **Wire** - the component URL is injected so `conversation.send()` works @@ -205,7 +209,7 @@ During `adk dev`, the file watcher rebuilds only changed components incrementall ## Limitations -- **Webchat only.** Custom components only render in the Botpress webchat widget. Other channels don't support them. +- **Webchat only.** Custom components only render in Webchat. Other channels don't support them. - **No global stylesheets.** You can import `.css` files in your component, but your project's global styles are not available. - **React 18.** React 19 features are not available. - **No server-side rendering.** Components are client-rendered in the browser. @@ -215,11 +219,11 @@ During `adk dev`, the file watcher rebuilds only changed components incrementall | Problem | Cause | Fix | |---------|-------|-----| | `Component "X" not deployed. Run "adk deploy".` | Component URL not set | Re-run `adk dev` to build and upload | -| Component doesn't appear in webchat | Wrapper doesn't export a `CustomComponent` | Check the `.ts` file imports the `.bp.tsx` and exports `new CustomComponent(...)` | +| Component doesn't appear in Webchat | Wrapper doesn't export a `CustomComponent` | Check the `.ts` file imports the `.bp.tsx` and exports `new CustomComponent(...)` | | LLM never uses the component | Missing metadata or not in `components` array | Add `{ description, props, exampleValues }` and list in `components` | | Styles look wrong | Using CSS classes | Switch to inline styles | | A prop is `undefined` | Reserved prop name (e.g., `status`) | Rename to something specific (e.g., `ticketStatus`) | -| TypeScript errors on `.bp.tsx` | Missing tsconfig settings | Add `"jsx": "react"`, `"allowImportingTsExtensions": true`, and `"noEmit": true` | +| TypeScript errors on `.bp.tsx` | Missing `tsconfig` settings | Add `"jsx": "react"`, `"allowImportingTsExtensions": true`, and `"noEmit": true` | --- From ec8dde028ea0fe4953cd8e4b438883803d64f271 Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Thu, 23 Apr 2026 15:48:44 -0400 Subject: [PATCH 12/29] audit messages --- adk/conversations/messages.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/adk/conversations/messages.mdx b/adk/conversations/messages.mdx index 2f9dbe9b..285c4737 100644 --- a/adk/conversations/messages.mdx +++ b/adk/conversations/messages.mdx @@ -16,7 +16,7 @@ await conversation.send({ ## Message types -The available message types depend on the channel. For webchat, the following types are supported: +The available message types depend on which channel your agent is deployed on. For [Webchat](/webchat/get-started/introduction), the following types are supported: | Type | Payload | Description | |------|---------|-------------| @@ -34,7 +34,7 @@ The available message types depend on the channel. For webchat, the following ty | `bloc` | `{ items }` | A group of mixed message types sent together | | `custom` | `{ url, name, data? }` | Custom rendered component (see [Use custom components](/adk/conversations/custom-components)) | -Other channels (Slack, WhatsApp, Telegram) support different subsets. When you specify a channel on your conversation, TypeScript will only allow the message types that channel supports. +Other channels (Slack, WhatsApp, Telegram) may support different message types. When you specify a channel on your conversation, TypeScript will only allow the message types that channel supports. ## Examples @@ -128,7 +128,9 @@ conversation.tags.priority = "high" conversation.tags.category = "billing" ``` -Tags must be declared in `agent.config.ts` under `conversation.tags`. See [Agent Configuration](/adk/setup/configuration#tags). + +Tags must be declared in `agent.config.ts` under `conversation.tags`. Check out our guide to [configuration your agent](/adk/setup/configuration#tags) for more information. + ## Loading a conversation by ID From 2d81070603dc285744c09100c3451f92de4d7d1c Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Thu, 23 Apr 2026 17:10:14 -0400 Subject: [PATCH 13/29] audit lifecycle and state --- adk/conversations/lifecycle.mdx | 8 ++++---- adk/conversations/state.mdx | 24 ++++++++++++------------ 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/adk/conversations/lifecycle.mdx b/adk/conversations/lifecycle.mdx index 99c156df..93ca4c68 100644 --- a/adk/conversations/lifecycle.mdx +++ b/adk/conversations/lifecycle.mdx @@ -9,7 +9,7 @@ Lifecycle management adds idle nudges and session expiration to your conversatio Add a `lifecycle` prop to your conversation: -```typescript +```typescript highlight={10-13} import { Conversation } from "@botpress/runtime" import { z } from "@botpress/sdk" @@ -77,7 +77,7 @@ A session is a single period of activity within a conversation. One conversation | `lastActivityAt` | `string` | ISO timestamp of the last user message. | | `nudgeCount` | `number` | How many nudges have fired in this session. Resets on new activity and on session renewal. | -Access it via `conversation.session`: +You can access the current session via `conversation.session`: ```typescript const session = props.conversation.session @@ -87,7 +87,7 @@ if (session) { } ``` -The session object is read-only. It returns `undefined` for conversations without lifecycle configured. +The `session` object is read-only. It returns `undefined` for conversations without lifecycle configured. ## What happens when a conversation expires @@ -112,7 +112,7 @@ Lifecycle durations use `ms`-compatible strings: | `'24h'` | 24 hours | | `'2d'` | 2 days | -Durations are validated at construction time. Invalid or non-positive values throw immediately. +Durations are validated at construction time. Invalid or non-positive values throw an error immediately. ## Common patterns diff --git a/adk/conversations/state.mdx b/adk/conversations/state.mdx index 3b1a7b02..5d7747a5 100644 --- a/adk/conversations/state.mdx +++ b/adk/conversations/state.mdx @@ -1,5 +1,5 @@ --- -title: Manage states +title: Manage state description: Store and reuse data across conversations, users, and the entire bot. --- @@ -17,9 +17,9 @@ State lets your agent persist data between handler calls. The ADK provides three ### Bot and user state -Define these in `agent.config.ts`: +Define bot and user state in `agent.config.ts`: -```typescript +```typescript highlight={6-10, 12-18} import { z, defineConfig } from "@botpress/runtime" export default defineConfig({ @@ -45,9 +45,9 @@ Use `.default()` to set initial values and `.describe()` to document what each f ### Conversation state -Defined on each conversation using the `state` prop: +Define conversation state on a `Conversation` using the `state` prop: -```typescript +```typescript highlight={5-8} import { Conversation, z } from "@botpress/runtime" export default new Conversation({ @@ -68,11 +68,11 @@ export default new Conversation({ ## Reading and writing state -State changes are saved automatically. You don't need to call a save method. +State objects are mutable and can be modified directly. Your changes are saved automatically—you don't need to call a save method. -### Bot state +## Bot state -Available anywhere in your agent (conversations, actions, tools, workflows): +You can access bot state anywhere in your agent (conversations, actions, tools, workflows): ```typescript import { bot } from "@botpress/runtime" @@ -83,7 +83,7 @@ bot.state.ticketCounter = counter + 1 ### User state -Available anywhere the current user context exists: +You can access user state anywhere the current user context exists: ```typescript import { user } from "@botpress/runtime" @@ -94,7 +94,7 @@ user.state.visitCount = (user.state.visitCount || 0) + 1 ### Conversation state -Accessed via the `state` parameter in the handler: +You can access conversation state via the `state` parameter in the conversation handler: ```typescript handler: async ({ state, execute }) => { @@ -151,7 +151,7 @@ export default new Conversation({ ## Tags -Tags are string key-value pairs you can attach to bots, users, conversations, messages, and workflows. They are useful for categorization, filtering, and querying. +Tags are string key-value pairs you can attach to bots, users, conversations, messages, and workflows. They're useful for categorization, filtering, and querying. ### Defining tags @@ -190,7 +190,7 @@ bot.tags.environment = "production" user.tags.role = "admin" ``` -Conversation tags are accessed via the conversation instance: +You can access conversation tags via the `conversation` instance: ```typescript handler: async ({ conversation }) => { From 0eb4d41fa0b385dce2694d6b74312aa5ba8d2e2e Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Thu, 23 Apr 2026 17:37:30 -0400 Subject: [PATCH 14/29] audit steps --- adk/workflows/steps.mdx | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/adk/workflows/steps.mdx b/adk/workflows/steps.mdx index f43b068b..628e7bd5 100644 --- a/adk/workflows/steps.mdx +++ b/adk/workflows/steps.mdx @@ -43,7 +43,7 @@ const data = await step("fetch-data", async ({ attempt }) => { }, { maxAttempts: 10 }) ``` -If a step exhausts all retries, it throws. This fails the entire workflow unless you catch it: +If a step exhausts all retries, it throws an error. This fails the entire workflow unless you catch it: ```typescript try { @@ -65,11 +65,11 @@ await step.sleep("wait-5-min", 5 * 60 * 1000) await step.sleepUntil("wait-until-noon", new Date("2025-01-15T12:00:00Z")) ``` -The workflow is suspended during sleep. No compute is used. +The workflow is suspended during sleep, and no further compute is used. ## Progress -Record a checkpoint without running any work. Useful for observability when you want to mark milestones in a long handler: +Use `.progress()` to record a checkpoint without running any work. This is useful for observability when you want to mark milestones in a long handler: ```typescript await step.progress("Started import") @@ -81,17 +81,15 @@ await step.progress("Finished") ## Listen -Pause the workflow and set its status to `"listening"`, waiting to be resumed by an external event: +Use `.listen()` to suspend the workflow and set its status to `"listening"`. The workflow then waits to be resumed by an external event. You can specify this event by passing its name in as an argument: ```typescript await step.listen("wait-for-payment") ``` -The workflow suspends at this point and uses no compute until it is resumed. - ## Fail and abort -Stop execution explicitly: +Use `.fail()` or `.abort()` to stop execution explicitly: ```typescript // Mark as failed with a message @@ -103,7 +101,7 @@ step.abort() ## Child workflows -Start another workflow and wait for it to complete: +You can start another workflow and wait for it to complete: ```typescript import ProcessingWorkflow from "../workflows/processing" @@ -124,7 +122,7 @@ const result = await step.waitForWorkflow("wait-for-child", childWorkflow.id) ## Parallel processing -### map +### `map` Process an array of items in parallel and collect results: @@ -137,7 +135,7 @@ const results = await step.map( ) ``` -### forEach +### `forEach` Process items in parallel without collecting results: @@ -150,7 +148,7 @@ await step.forEach( ) ``` -### batch +### `batch` Process items in sequential batches: From 75f5a1c06d1992319012addd4990685fa5ab6c1c Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Thu, 23 Apr 2026 17:47:04 -0400 Subject: [PATCH 15/29] audit request/notify --- adk/workflows/request-notify.mdx | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/adk/workflows/request-notify.mdx b/adk/workflows/request-notify.mdx index 56cc7ed1..34ca4356 100644 --- a/adk/workflows/request-notify.mdx +++ b/adk/workflows/request-notify.mdx @@ -7,13 +7,13 @@ Workflows run in the background, but sometimes they need input from the user or ## Requests -A request pauses the workflow and asks the conversation for data. The workflow defines what it needs, the conversation handler collects it from the user and sends it back. +A request pauses the workflow and asks the conversation for data. The workflow defines what it needs, the conversation handler collects it from the user and sends it back to the workflow. ### Define requests in the workflow Declare the request schemas in the workflow definition: -```typescript +```typescript highlight={5-14} import { Workflow, z } from "@botpress/runtime" export default new Workflow({ @@ -40,7 +40,7 @@ export default new Workflow({ }) ``` -`step.request()` pauses the workflow and sends a `workflow_request` event to the conversation. The second argument is a human-readable message describing what's needed. +`step.request()` pauses the workflow and sends a `workflow_request` event to the conversation. The first argument is the name of the data being requested, and the second argument is a natural language prompt for that data. ### Handle requests in the conversation @@ -163,12 +163,4 @@ if (props.type === "workflow_callback") { } return } -``` - -## Summary - -| Mechanism | Direction | Pauses workflow? | Handler type | -|-----------|-----------|-----------------|--------------| -| `step.request()` | Workflow asks conversation | Yes | `workflow_request` | -| `step.notify()` | Workflow tells conversation | No | `workflow_notify` | -| Callback | Workflow completes | N/A | `workflow_callback` | +``` \ No newline at end of file From 1fcf758114fa33032005f9f95a79ce6b08a39ad6 Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Fri, 24 Apr 2026 10:54:51 -0400 Subject: [PATCH 16/29] audit actions --- adk/external/actions.mdx | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/adk/external/actions.mdx b/adk/external/actions.mdx index 1fd99e0c..5e343236 100644 --- a/adk/external/actions.mdx +++ b/adk/external/actions.mdx @@ -3,7 +3,7 @@ title: Create actions description: Create reusable functions callable from anywhere in your agent or from external systems. --- -Actions are reusable functions that hold shared business logic. Call them from your own code (conversations, workflows, triggers, other actions) or over HTTP from external systems. +Actions are reusable functions that hold shared business logic. You can call them from your agent's code (via [conversations](#from-a-conversation), [workflows](#from-a-workflow), [triggers](#from-a-trigger), [tools](@from-a-tool), or other actions). You can also [call them over HTTP](#calling-from-external-systems) from external systems. ## Creating an action @@ -50,7 +50,7 @@ Browse and test actions from the dev console: Set `cached: true` to cache an action's output by its input. Subsequent calls with the same input return the cached result instead of re-running the handler: -```typescript +```typescript highlight={3} export default new Action({ name: "fetchExchangeRate", cached: true, @@ -63,11 +63,11 @@ export default new Action({ }) ``` -Useful for actions that are pure, expensive, and called repeatedly with the same inputs. +This is useful for actions that are pure, perform an expensive calculation, and are called repeatedly with the same inputs. ## Calling actions -Import `actions` from `@botpress/runtime` and call any action by name. Input and output are fully typed. +Import `actions` from `@botpress/runtime` and call any action by name. The action's input and output are fully typed. ### From a conversation @@ -135,9 +135,12 @@ export default new Trigger({ ## As a tool -Tools only exist inside `execute()` and are called by the AI model. If you want the AI to use an action too, convert it with `.asTool()`: +While actions are just functions that can be called from anywhere, [tools](/adk/conversations/tools) only exist inside `execute()` and are called by the LLM. If you want the LLM to have access to a certain action: -```typescript +1. Convert it to a tool with `.asTool()` +2. Pass it into the `tools` field: + +```typescript highlight={8} import { Conversation, actions } from "@botpress/runtime" export default new Conversation({ @@ -151,7 +154,7 @@ export default new Conversation({ }) ``` -You can override the description for the tool: +You should always provide a detailed description that helps the LLM decide when to use a tool. When converting an action to a tool, you can override its description by passing a string into the`description` field: ```typescript actions.calculateTotal.asTool({ description: "Calculate the total price with tax for the user's cart" }) @@ -170,7 +173,7 @@ await actions.slack.addReaction({ name: "thumbsup", channel, timestamp }) ## Calling from external systems -Actions are exposed via the Botpress Runtime API. External services can call your agent's actions over HTTP: +Actions are exposed via the Botpress [Runtime API](/api-reference/runtime-api/getting-started)'s [`callAction`](/api-reference/runtime-api/openapi/endpoints/post-v1chatactions) endpoint. External services can call your agent's actions over HTTP: ```bash curl -X POST https://api.botpress.cloud/v1/chat/actions \ @@ -187,5 +190,3 @@ curl -X POST https://api.botpress.cloud/v1/chat/actions \ ``` This makes actions the bridge between your agent and external systems. A backend service, a webhook handler, or another application can trigger your agent's logic without going through a conversation. - -See the [Runtime API reference](/api-reference/runtime-api/openapi/callAction) for full details. From 7f0a5959bafe523fb07de962c0f680916deb79c5 Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Fri, 24 Apr 2026 10:55:36 -0400 Subject: [PATCH 17/29] fix actions description --- adk/external/actions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adk/external/actions.mdx b/adk/external/actions.mdx index 5e343236..3eb0237b 100644 --- a/adk/external/actions.mdx +++ b/adk/external/actions.mdx @@ -1,6 +1,6 @@ --- title: Create actions -description: Create reusable functions callable from anywhere in your agent or from external systems. +description: Create reusable functions that can be called from anywhere in your agent or from external systems. --- Actions are reusable functions that hold shared business logic. You can call them from your agent's code (via [conversations](#from-a-conversation), [workflows](#from-a-workflow), [triggers](#from-a-trigger), [tools](@from-a-tool), or other actions). You can also [call them over HTTP](#calling-from-external-systems) from external systems. From cf17191c5e13afc5b5a330d709857ca7e942a5e9 Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Fri, 24 Apr 2026 11:05:58 -0400 Subject: [PATCH 18/29] audit triggers --- adk/external/triggers.mdx | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/adk/external/triggers.mdx b/adk/external/triggers.mdx index 683e2c41..e1218bf1 100644 --- a/adk/external/triggers.mdx +++ b/adk/external/triggers.mdx @@ -23,9 +23,13 @@ export default new Trigger({ The `events` array lists which events this trigger subscribes to. The handler runs when any of the listed events fire. + Trigger names must be at least 3 characters and contain only alphanumeric characters and underscores. + -Browse your triggers from the dev console: +## Viewing triggers in the dev console + +You can browse your triggers from the dev console at **Components > Triggers**: Triggers page in dev console @@ -49,7 +53,7 @@ To make API calls from a trigger, pull the client from the runtime context: `con A trigger can subscribe to multiple events and handle each differently: -```typescript +```typescript highlight={4-8} export default new Trigger({ name: "onLinearIssue", description: "Handle Linear issue events", @@ -74,8 +78,7 @@ export default new Trigger({ Triggers can subscribe to custom events you define in `agent.config.ts`: -```typescript -// agent.config.ts +```typescript title="agent.config.ts" export default defineConfig({ events: { orderPlaced: { @@ -89,8 +92,7 @@ export default defineConfig({ }) ``` -```typescript -// src/triggers/on-order.ts +```typescript title="src/triggers/on-order.ts" import { Trigger } from "@botpress/runtime" export default new Trigger({ @@ -107,7 +109,7 @@ export default new Trigger({ Triggers can call actions for reusable logic: -```typescript +```typescript highlight={8-10} import { Trigger, actions } from "@botpress/runtime" export default new Trigger({ From f631f13463b93d6d22583e4bd8e22f7c9b19fcd5 Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Fri, 24 Apr 2026 11:57:34 -0400 Subject: [PATCH 19/29] audit tables --- adk/data/tables.mdx | 97 +++++++++++++++++++++++++++++++-------------- 1 file changed, 67 insertions(+), 30 deletions(-) diff --git a/adk/data/tables.mdx b/adk/data/tables.mdx index a74dfeeb..cf0bd816 100644 --- a/adk/data/tables.mdx +++ b/adk/data/tables.mdx @@ -3,7 +3,7 @@ title: Tables description: Define and query structured data storage. --- -Tables provide typed, structured storage for your agent. You define a schema using `z` from `@botpress/runtime`, and the ADK syncs it with Botpress Cloud on deploy. Tables are accessible from conversations, workflows, actions, tools, and triggers. +Tables provide typed, structured storage for your agent. You define a schema using `z` from `@botpress/runtime`, and the ADK syncs it with Botpress on deploy. Tables are accessible from conversations, workflows, actions, tools, and triggers. ## Creating a table @@ -26,9 +26,7 @@ export default new Table({ }) ``` -`description` is optional but useful when the table gets surfaced to the LLM (via Zai or knowledge). `keyColumn` is optional too; it sets the default key used by `upsertRows` so you don't have to pass it on every call. - -The dev console under **Tables** is the primary way to manage table data. You can see the sync state between your code and Botpress Cloud, add/update/delete rows, filter and sort, export to CSV, and copy data between dev and prod environments. +The `description` field is optional but useful when the table gets surfaced to the LLM (via Zai or knowledge). `keyColumn` is optional too; it sets the default key used when calling [`.upsertRows()`](#upsert-rows) so you don't have to pass it on every call. Tables page in dev console @@ -37,15 +35,17 @@ The dev console under **Tables** is the primary way to manage table data. You ca ### Naming rules -- Must start with a letter, underscore, or `$` -- 35 characters or less -- Only letters, numbers, and underscores +Table names: + +- Must with a letter, underscore, or `$` +- Must be 35 characters or less +- Must contain only letters, numbers, and underscores - Must end with `Table` - Cannot be a UUID ### Searchable columns -Mark columns as searchable to enable semantic search: +You can mark columns as searchable to enable semantic search: ```typescript export default new Table({ @@ -61,9 +61,9 @@ export default new Table({ ### Computed columns -A computed column is derived from other columns. Set `computed: true`, declare the columns it depends on, and return its value from `value`: +A computed column is derived from other columns. Set `computed: true`, pass the columns it depends on into `dependencies`, and return its value from `value`: -```typescript +```typescript highlight={7,9-10} export default new Table({ name: "OrderTable", columns: { @@ -79,7 +79,7 @@ export default new Table({ }) ``` -Computed columns recalculate whenever their dependencies change. When you write to the table, pass `waitComputed: true` to block until the recalculation finishes: +Computed columns recalculate whenever their dependencies change. When you write to the table, you can pass `waitComputed: true` to block any further modifications to the table until the recalculation finishes: ```typescript await OrderTable.createRows({ @@ -88,9 +88,19 @@ await OrderTable.createRows({ }) ``` +## Managing table data + +You can manage your table data in the dev console under **Data > Tables**. Here, you can: + +- View the sync state between your code and Botpress' servers +- Add/update/delete rows +- Filter and sort +- Export to CSV +- Copy data between development and production environments + ## CRUD operations -Import your table and use the typed instance methods. +To perform operations on your table within your agent's code, import the table and use the typed instance methods. ### Create rows @@ -129,7 +139,7 @@ await OrderTable.updateRows({ ### Upsert rows -Insert or update based on a key column. If you set `keyColumn` on the table, you can omit it here: +Insert or update based on a key column: ```typescript const { inserted, updated } = await OrderTable.upsertRows({ @@ -138,21 +148,31 @@ const { inserted, updated } = await OrderTable.upsertRows({ }) ``` -If `keyColumn` is omitted on both the table and the call, it defaults to `id`. +If you [set `keyColumn` on the table](#creating-a-table), you can omit it here. + + +If `keyColumn` is omitted on both the table defintion and the `upsertRows` call, it defaults to `id`. + ### Delete rows -```typescript + +```typescript Delete rows by name await OrderTable.deleteRows({ status: "cancelled" }) +``` +```typescript Delete rows by ID await OrderTable.deleteRowIds([1, 2, 3]) +``` +```typescript Delete all rows await OrderTable.deleteAllRows() ``` + ## Filtering -Use operators for advanced queries: +When calling `findRows()`, you can pass in filters for specific rows. These can use [MongoDB-style operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates/) for advanced queries: ```typescript const { rows } = await OrderTable.findRows({ @@ -181,7 +201,7 @@ const { rows } = await OrderTable.findRows({ ### Logical operators -Combine filters with `$and`, `$or`, and `$not`: +You can combine filters with `$and`, `$or`, and `$not`: ```typescript const { rows } = await OrderTable.findRows({ @@ -196,7 +216,7 @@ const { rows } = await OrderTable.findRows({ ## Semantic search -Search across `searchable` columns using natural language: +You can search across [`searchable` columns](#searchable-columns) using natural language: ```typescript const { rows } = await TicketTable.findRows({ @@ -217,23 +237,40 @@ const { rows } = await TicketTable.findRows({ ## Aggregation -Group and aggregate data: +Aggregation groups rows by one or more columns and computes summary statistics for other columns. This transforms your table data into summary reports. + +Pass a `group` object to `findRows()` where each key is a column name and the value is either a single operation or an array of operations: ```typescript const { rows } = await OrderTable.findRows({ group: { - status: "key", - total: ["sum", "avg", "count"], + status: "key", // Group by status + total: ["sum", "avg"], // Sum and average the total column + id: "count", // Count rows in each group }, }) ``` -| Operation | Applies to | Description | -|-----------|-----------|-------------| -| `key` | All types | Group by this value | -| `count` | All types | Count of rows | -| `sum` | Numbers | Sum of values | -| `avg` | Numbers | Average of values | -| `max` | Numbers, strings, dates | Maximum value | -| `min` | Numbers, strings, dates | Minimum value | -| `unique` | All types | Array of unique values | +The returned rows have different fields based on your group configuration. The field names combine the column name (in `camelCase`) with the operation: + +```typescript +// For the group config above, each row in the result contains: +{ + statusKey: "pending", // The grouping value + totalSum: 1500.00, // Sum of totals in this group + totalAvg: 125.00, // Average of totals in this group + idCount: 12, // Number of rows in this group +} +``` + +Operations vary by column type: + +| Operation | Available for | Returns | Description | +|-----------|---------------|---------|-------------| +| `key` | All types | Same as column | Groups rows by this value | +| `count` | All types | `number` | Number of rows in the group | +| `sum` | Numbers | `number` | Sum of values | +| `avg` | Numbers | `number` | Average of values | +| `max` | Numbers, strings, dates | Same as column | Maximum value | +| `min` | Numbers, strings, dates | Same as column | Minimum value | +| `unique` | All types | Array | Array of unique values | From 87d3796f1ba53c69df25d6f4a2f16914e9cb0e5a Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Fri, 24 Apr 2026 12:08:53 -0400 Subject: [PATCH 20/29] fix --- docs.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 0baae3c0..78a9fdb9 100644 --- a/docs.json +++ b/docs.json @@ -152,7 +152,7 @@ ] }, { - "group": "AI Native Development", + "group": "AI-native Development", "pages": [ "/adk/ai-native/skills" ] From bc1cca10132a49f8c8b91750b71678712f4853d4 Mon Sep 17 00:00:00 2001 From: Adrian Kahali Date: Fri, 24 Apr 2026 12:54:52 -0400 Subject: [PATCH 21/29] fix vale --- .../vocabularies/botpress-vocab/accept.txt | 8 ++- adk/ai-native/skills.mdx | 12 ++--- adk/cli-reference.mdx | 50 +++++++++---------- adk/data/knowledge.mdx | 2 +- adk/testing/evals.mdx | 2 +- adk/testing/scripts.mdx | 4 +- adk/zai/classify.mdx | 4 +- adk/zai/overview.mdx | 2 +- 8 files changed, 45 insertions(+), 39 deletions(-) diff --git a/.vale/styles/config/vocabularies/botpress-vocab/accept.txt b/.vale/styles/config/vocabularies/botpress-vocab/accept.txt index 4cc21a34..05e12790 100644 --- a/.vale/styles/config/vocabularies/botpress-vocab/accept.txt +++ b/.vale/styles/config/vocabularies/botpress-vocab/accept.txt @@ -55,4 +55,10 @@ Airtable Persat Mintlify Sharepoint -Chatwoot \ No newline at end of file +Chatwoot +[Ee]vals? +[Ee]val +ADK +gitignored +stdout +helpdesk \ No newline at end of file diff --git a/adk/ai-native/skills.mdx b/adk/ai-native/skills.mdx index 5379036f..1d5af5f8 100644 --- a/adk/ai-native/skills.mdx +++ b/adk/ai-native/skills.mdx @@ -32,12 +32,12 @@ Or install as a Claude Code plugin: | Skill | What it teaches | Use when | |-------|----------------|----------| -| **adk** | Core ADK framework: actions, tools, workflows, conversations, tables, knowledge, triggers, Zai, configuration | Building any feature with the ADK | -| **adk-debugger** | Trace reading, log analysis, common failure diagnosis, the debug loop | Bot isn't responding, tools failing, workflows stuck, LLM issues | -| **adk-evals** | Eval file format, all assertion types, CLI usage, per-primitive testing patterns | Writing and running automated tests | -| **adk-frontend** | Authentication, type generation, client setup, calling bot actions from React/Next.js | Building a frontend that connects to your bot | -| **adk-integrations** | Discovery, adding, configuring, and using integrations end-to-end | Connecting Slack, WhatsApp, Linear, or any integration | -| **adk-docs** | Documentation standards, creation, review, and maintenance | Writing or updating docs for your bot | +| **`adk`** | Core ADK framework: actions, tools, workflows, conversations, tables, knowledge, triggers, Zai, configuration | Building any feature with the ADK | +| **`adk-debugger`** | Trace reading, log analysis, common failure diagnosis, the debug loop | Bot isn't responding, tools failing, workflows stuck, LLM issues | +| **`adk-evals`** | Eval file format, all assertion types, CLI usage, per-primitive testing patterns | Writing and running automated tests | +| **`adk-frontend`** | Authentication, type generation, client setup, calling bot actions from React/Next.js | Building a frontend that connects to your bot | +| **`adk-integrations`** | Discovery, adding, configuring, and using integrations end-to-end | Connecting Slack, WhatsApp, Linear, or any integration | +| **`adk-docs`** | Documentation standards, creation, review, and maintenance | Writing or updating docs for your bot | ## Slash commands diff --git a/adk/cli-reference.mdx b/adk/cli-reference.mdx index a9987052..66f8a8a0 100644 --- a/adk/cli-reference.mdx +++ b/adk/cli-reference.mdx @@ -14,7 +14,7 @@ These flags work with every command: | `--help`, `-h` | Show help information | | `--version`, `-V` | Show version number | | `--no-cache` | Disable caching for integration lookups | -| `--profile ` | Credentials profile to use (overrides the `ADK_PROFILE` env var and the current profile) | +| `--profile ` | Credentials profile to use (overrides the `ADK_PROFILE` environment variable and the current profile) | Most commands also accept `--format json` for machine-readable output. The following commands don't: `dev`, `login`, `profiles list`, `profiles set`, `upgrade`, `remove`, `self-upgrade`, `telemetry`, `theme`, `mcp`, `mcp:init`, `run`, `assets pull`. @@ -32,7 +32,7 @@ These commands manage an agent project from scaffold to deploy: | `adk status` | Show project status, integrations, and server state | | `adk link` | Link local agent to a workspace and bot | -### adk init +### `adk init` Scaffold a new agent project. Pass a name, or omit it to be prompted: @@ -49,7 +49,7 @@ adk init --list-templates | `--skip-link` | Skip the linking step | | `--list-templates` | List available templates and exit | -### adk dev +### `adk dev` Start the dev server with hot reload: @@ -67,7 +67,7 @@ adk dev --port 3000 --port-console 3001 | `-v, --verbose` | Show additional details | | | `--non-interactive` | Emit structured NDJSON events to stdout | | -### adk deploy +### `adk deploy` Deploy the built agent to Botpress Cloud: @@ -81,7 +81,7 @@ adk deploy -y | `-e, --env ` | Deployment environment | `production` | | `-y, --yes` | Auto-approve preflight changes | | -### adk link +### `adk link` Link the local agent to a workspace and bot. Writes to `agent.json`, or to `agent.local.json` with `--local`: @@ -112,7 +112,7 @@ These commands add, inspect, and manage the integrations your agent depends on: | `adk list` | List installed integrations | | `adk info ` | Show detailed integration info | -### adk add +### `adk add` Add an integration or interface to your agent. Accepts a name, `workspace/name`, or a specific version: @@ -129,7 +129,7 @@ adk add webchat --alias custom-webchat |------|-------------| | `--alias ` | Custom alias for the resource | -### adk search +### `adk search` Search the Botpress Hub for integrations: @@ -142,7 +142,7 @@ adk search slack --limit 5 |------|-------------|---------| | `--limit ` | Max results to return | `20` | -### adk list +### `adk list` List integrations in your project, or all available ones on the Hub: @@ -156,7 +156,7 @@ adk list --available | `--available` | List all available integrations (not just installed) | | | `--limit ` | Max results | `50` | -### adk info +### `adk info` Show details for a specific integration. Filter by a single facet or show the full spec: @@ -199,7 +199,7 @@ These commands let you send messages to your agent and run eval suites: | `adk evals [name]` | Run eval suites | | `adk evals runs [runId]` | List or show eval run history | -### adk chat +### `adk chat` Open an interactive chat, or send a single message with `--single`. Requires `adk dev` to be running: @@ -215,7 +215,7 @@ adk chat --single "Follow up" --conversation-id | `--conversation-id ` | Continue a conversation | | | `--timeout ` | Max wait duration | `60s` | -### adk evals +### `adk evals` Run eval suites. With no arguments, runs all evals; pass a name to run just one: @@ -235,7 +235,7 @@ adk evals -v | `-v, --verbose` | Show full details for all evals | | | `--server ` | Dev server URL | `http://localhost:3001` | -### adk evals runs +### `adk evals runs` List past eval runs, or show the details of a specific one: @@ -261,7 +261,7 @@ These commands discover and run workflows against the local dev server: | `adk workflows inspect ` | Inspect a workflow schema and metadata | | `adk workflows run [payload]` | Run a workflow | -### adk workflows run +### `adk workflows run` Run a workflow with a JSON payload. Add `--wait` to block until it finishes: @@ -285,7 +285,7 @@ These commands help you inspect what your agent is doing: | `adk traces [tokens...]` | Query trace data | | `adk run