diff --git a/adk/assets/control-panel-quickstart-dark.png b/adk/assets/control-panel-quickstart-dark.png deleted file mode 100644 index 292a5967..00000000 Binary files a/adk/assets/control-panel-quickstart-dark.png and /dev/null differ diff --git a/adk/assets/control-panel-quickstart.png b/adk/assets/control-panel-quickstart.png deleted file mode 100644 index f4569d23..00000000 Binary files a/adk/assets/control-panel-quickstart.png and /dev/null differ diff --git a/adk/assets/quickstart-dark.png b/adk/assets/quickstart-dark.png new file mode 100644 index 00000000..a4a3ea05 Binary files /dev/null and b/adk/assets/quickstart-dark.png differ diff --git a/adk/assets/quickstart.png b/adk/assets/quickstart.png new file mode 100644 index 00000000..97584ea7 Binary files /dev/null and b/adk/assets/quickstart.png differ diff --git a/adk/assets/welcome-dark.png b/adk/assets/welcome-dark.png new file mode 100644 index 00000000..eca93562 Binary files /dev/null and b/adk/assets/welcome-dark.png differ diff --git a/adk/assets/welcome.png b/adk/assets/welcome.png new file mode 100644 index 00000000..e5fe372e Binary files /dev/null and b/adk/assets/welcome.png differ diff --git a/adk/concepts/configuration.mdx b/adk/concepts/configuration.mdx index 99191601..760ecd75 100644 --- a/adk/concepts/configuration.mdx +++ b/adk/concepts/configuration.mdx @@ -192,7 +192,7 @@ adk config:get supportEmail --prod ``` - Agent configuration (`adk config`) is separate from integration configuration. Integration settings like API keys are managed in the Control Panel during `adk dev`. See [Managing Integrations](/adk/managing-integrations) for details. + Agent configuration (`adk config`) is separate from integration configuration. Integration settings like API keys are managed in the dev console during `adk dev`. See [Managing Integrations](/adk/managing-integrations) for details. ## Default models @@ -246,4 +246,4 @@ dependencies: { }, ``` -Integration settings (API keys, tokens, etc.) are configured in the Control Panel during `adk dev`, not in `agent.config.ts`. +Integration settings (API keys, tokens, etc.) are configured in the dev console during `adk dev`, not in `agent.config.ts`. diff --git a/adk/get-started/quickstart-coding-assistant.mdx b/adk/get-started/quickstart-coding-assistant.mdx new file mode 100644 index 00000000..dd1dfd2d --- /dev/null +++ b/adk/get-started/quickstart-coding-assistant.mdx @@ -0,0 +1,62 @@ +--- +title: Quickstart with coding assistant +description: Let's get the same hello-world agent set up, with your AI coding assistant doing the work. +--- + + + You'll need [Node.js](https://nodejs.org/) 22.0.0 or higher, a [Botpress account](https://sso.botpress.cloud), and an AI coding assistant like Claude Code, Cursor, or Codex. + + + + + Run the install command for your operating system: + + + + ```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" + ``` + + + + Then verify: + + ```bash + adk --version + ``` + + + + ```bash + adk login + ``` + + Follow the prompts to sign in through your browser. + + + + Open your coding assistant in an empty folder and paste this prompt: + + ```txt + Let's get set up with a quick hello-world agent built with the ADK. Scaffold the project, start the dev server, and deploy it to Botpress Cloud when it's working. + ``` + + The assistant runs `adk init`, `adk dev`, and `adk deploy` for you. Review each change it proposes, and you'll have a live agent when it's done. + + + +## Next steps + + + + See what an ADK project looks like. + + + Define how your agent talks to users across channels. + + diff --git a/adk/get-started/quickstart.mdx b/adk/get-started/quickstart.mdx new file mode 100644 index 00000000..33a17524 --- /dev/null +++ b/adk/get-started/quickstart.mdx @@ -0,0 +1,90 @@ +--- +title: Quickstart +description: Let's get set up with a quick hello-world agent built with the ADK. +--- + + + You'll need [Node.js](https://nodejs.org/) 22.0.0 or higher and a [Botpress account](https://sso.botpress.cloud) to log in with. + + + + + Run the install command for your operating system: + + + + ```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 and verify the installation: + + ```bash + adk --version + ``` + + + + Authenticate with your Botpress account: + + ```bash + adk login + ``` + + Follow the prompts to sign in through your browser. The CLI saves your credentials for every command that follows. + + + + Scaffold a new project: + + ```bash + adk init my-agent + cd my-agent + ``` + + Pick the `hello-world` template when prompted. The wizard also asks for a package manager and a Botpress workspace to link the project to. + + + + Start the dev server: + + ```bash + adk dev + ``` + + Open the dev console at [http://localhost:3001](http://localhost:3001) and head to the **Chat** page to talk to your agent. + + + ADK dev console + ADK dev console + + + + + Ship your agent: + + ```bash + adk deploy + ``` + + This builds a production bundle and uploads it to the workspace you linked during `adk init`. Chat with your live agent from your Botpress Cloud workspace. + + + +## Next steps + + + + See what an ADK project looks like. + + + Pair the ADK with Claude Code, Cursor, or Codex using ADK skills. + + diff --git a/adk/get-started/welcome.mdx b/adk/get-started/welcome.mdx new file mode 100644 index 00000000..38f8cc37 --- /dev/null +++ b/adk/get-started/welcome.mdx @@ -0,0 +1,21 @@ +--- +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. +--- + + + Botpress ADK + Botpress ADK + + +## Start here + + + + Build and deploy your first agent in minutes. + + + Latest features, improvements, and breaking changes. + + diff --git a/adk/introduction.mdx b/adk/introduction.mdx deleted file mode 100644 index 3e771410..00000000 --- a/adk/introduction.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Introduction to the ADK -sidebarTitle: Introduction ---- - - - - ```ts Basic agent - import { Conversation } from "@botpress/runtime"; - - export default new Conversation({ - channel: "*", - handler: async ({ execute }) => { - await execute({ - instructions: "You are a helpful assistant.", - }); - }, - }); - ``` - - ```ts Agent with knowledge - import { Conversation } from "@botpress/runtime"; - import { WebsiteKB } from "../knowledge/docs"; - - export default new Conversation({ - channel: "*", - handler: async ({ execute }) => { - await execute({ - instructions: "You are a helpful assistant.", - knowledge: [WebsiteKB] - }); - }, - }); - ``` - - - -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 conversational AI applications. - -## Get started - - - - Build your first agent in minutes - - - Learn how an ADK project is organized - - - -## What is the ADK? - -The ADK is a framework that allows developers to build Botpress agents from code. It provides: - -- **Project scaffolding**: Quickly initialize new agent projects with templates -- **Type-safe development**: Automatic TypeScript type generation for integrations, interfaces, and more -- **Development workflow**: Hot reloading development server with live updates -- **Build and deploy**: Compile and deploy agents to Botpress Cloud -- **Integration management**: Add, update, and manage integrations from the Botpress Hub - -## When to use the ADK - -The ADK is ideal for: - -- Developers who prefer code-based workflows -- Teams using version control and CI/CD pipelines -- Projects requiring custom logic and integrations -- Developers who need TypeScript type safety - - -For most users, we recommend Botpress Studio. The ADK is best suited for developers who need more control or integration with development workflows. - diff --git a/adk/project-structure.mdx b/adk/project-structure.mdx deleted file mode 100644 index 7b6d57f2..00000000 --- a/adk/project-structure.mdx +++ /dev/null @@ -1,373 +0,0 @@ ---- -title: Project structure ---- - -ADK projects follow a consistent structure that organizes your agent's code, configuration, and dependencies. - -## Directory structure - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -## Configuration files - -### `agent.config.ts` - -The main agent configuration file. Defines your agent's name, description, default models, state schemas, tags, configuration schema, and integration dependencies. - -```typescript expandable -import { z, defineConfig } from "@botpress/runtime"; - -export default defineConfig({ - name: "my-agent", - description: "An AI agent built with Botpress ADK", - - defaultModels: { - autonomous: "cerebras:gpt-oss-120b", - zai: "cerebras:gpt-oss-120b", - }, - - bot: { - state: z.object({ - // Bot-level state accessible via `bot.state` - }), - tags: { - // Bot-level tags - }, - }, - - user: { - state: z.object({ - // User-level state accessible via `user.state` - }), - tags: { - // User-level tags - }, - }, - - conversation: { - tags: { - // Conversation-level tags - }, - }, - - message: { - tags: { - // Message-level tags - }, - }, - - workflow: { - tags: { - // Workflow-level tags - }, - }, - - configuration: { - schema: z.object({ - // Configuration schema for your agent - // Accessible via `configuration` export - }), - }, - - dependencies: { - integrations: { - webchat: { - version: "webchat@latest", - enabled: true, - }, - chat: { - version: "chat@latest", - enabled: true, - }, - }, - }, -}); -``` - -### `agent.json` - -Links the agent to a bot in your Workspace: - -```json -{ - "botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", - "workspaceId": "wkspace_xxxxxxxxxxxxxxxxxxxxxxxxxx", - "apiUrl": "https://api.botpress.cloud" -} -``` - -### `agent.local.json` - -Stores your local development bot ID. This file is gitignored and complements `agent.json`: - -```json -{ - "devId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -} -``` - -### `package.json` - -Standard Node.js package configuration. Includes scripts for `dev`, `build`, and `deploy` commands. - -```json -{ - "name": "my-agent", - "version": "1.0.0", - "description": "A Botpress Agent built with the ADK", - "type": "module", - "packageManager": "bun@latest", - "scripts": { - "dev": "adk dev", - "build": "adk build", - "deploy": "adk deploy" - }, - "dependencies": { - "@botpress/runtime": "^x.x.x" - }, - "devDependencies": { - "typescript": "^x.x.x" - } -} - -``` - -## Source directories - -### `src/conversations/` - -Conversation handlers that respond to messages from users. Each file exports a `Conversation` instance that handles messages for specific channels. - - -```ts All channels -import { Conversation } from "@botpress/runtime"; - -export default new Conversation({ - channel: "*", - handler: async ({ execute }) => { - await execute({ - instructions: "You are a helpful assistant.", - }); - }, -}); -``` - -```ts Specific channel -import { Conversation } from "@botpress/runtime"; - -export default new Conversation({ - channel: "webchat.channel", - handler: async ({ execute }) => { - await execute({ - instructions: "You are a helpful assistant.", - }); - }, -}); -``` - -```ts Array of channels -import { Conversation } from "@botpress/runtime"; - -export default new Conversation({ - channel: [ - "chat.channel", - "webchat.channel" - ], - handler: async ({ execute }) => { - await execute({ - instructions: "You are a helpful assistant.", - }); - }, -}); -``` - - -### `src/workflows/` - -Long-running processes that execute background tasks or handle complex multi-step operations. Each file exports a `Workflow` instance that defines the logic to execute when the Workflow is called. - -```typescript -import { Workflow } from "@botpress/runtime"; - -export default new Workflow({ - name: "my-workflow", - handler: async () => { - // Workflow logic - }, -}); -``` - -### `src/actions/` - -Callable functions that can be invoked by workflows, conversations, or other actions. - -```typescript -import { Action, z } from "@botpress/runtime"; - -export default new Action({ - name: "yourAction", - input: z.object({}), - output: z.object({}), - async handler({ input }) { - // Your logic here - return { message: "This is your action's output." }; - }, -}); -``` - -### `src/tables/` - -Table schemas that define data storage structures. Tables are automatically synced with Botpress Cloud. - -```typescript -import { Table, z } from "@botpress/runtime"; - -export default new Table({ - name: "PricingTable", - columns: { - itemName: z.string(), - price: z.string(), - }, -}); -``` - -### `src/triggers/` - -Event subscriptions that respond to external events or scheduled triggers. - -```typescript -import { Trigger } from "@botpress/runtime"; - -export default new Trigger({ - name: "conversationStarted", - events: [ - "webchat:conversationStarted", - ], - handler: async ({ event }) => { - // Trigger logic - }, -}); -``` - -### `src/knowledge/` - -Knowledge base sources that provide context to your agent's AI models. - -```typescript -import { DataSource, Knowledge } from "@botpress/runtime"; - -const WebsiteSource = DataSource.Website.fromSitemap( - "https://www.botpress.com/docs/sitemap.xml", - { - filter: ({ url }) => !url.includes("llms-full.txt"), - } -); - -export const WebsiteKB = new Knowledge({ - name: "Botpress", - description: "Knowledge base containing Botpress documentation.", - sources: [WebsiteSource], -}); -``` - -## Global state and configuration - -The ADK provides exports for accessing global state and configuration throughout your agent. - -### Bot state - -Access and modify bot-level state that persists across all conversations: - -```typescript -import { bot } from "@botpress/runtime"; - -// Read bot state -const currentValue = bot.state.someField; - -// Update bot state -bot.state.someField = "new value"; -``` - -### User state - -Access and modify user-level state that persists for each user: - -```typescript -import { user } from "@botpress/runtime"; - -// Read user state -const preferences = user.state.preferences; - -// Update user state -user.state.visitCount = (user.state.visitCount || 0) + 1; -``` - -### Configuration - -Access your agent's configuration values (defined in `agent.config.ts`): - -```typescript -import { configuration } from "@botpress/runtime"; - -// Access configuration values -const apiKey = configuration.apiKey; -const maxRetries = configuration.maxRetries; -``` - - - State schemas are defined in `agent.config.ts` under `bot.state` and `user.state`. The configuration schema is defined under `configuration.schema`. - - -## Generated files - -When you run `adk dev` or `adk build`, the ADK generates files in the `.adk/` directory: - -- `.adk/*.d.ts` — Type definitions for actions, conversations, workflows, tables, triggers, and more -- `.adk/client.ts` — Generated client wrapper -- `.adk/integrations/` — Integration type definitions -- `.adk/bot/` — Generated Botpress bot project and compiled output - - -Don't edit files in the `.adk/` directory manually. They are automatically generated and will be overwritten. - - -## Next steps - - - - Learn about conversation handlers - - - Create long-running processes - - diff --git a/adk/quickstart.mdx b/adk/quickstart.mdx deleted file mode 100644 index 4293fb43..00000000 --- a/adk/quickstart.mdx +++ /dev/null @@ -1,175 +0,0 @@ ---- -title: Quickstart ---- - -This guide walks you through installing the ADK and creating your first agent project. - - - 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 -curl -fsSL https://github.com/botpress/adk/releases/latest/download/install.sh | bash -``` - -```powershell Windows (PowerShell) -powershell -c "irm https://github.com/botpress/adk/releases/latest/download/install.ps1 | iex" -``` - - - -Verify the installation: - -```bash -adk --version -``` - -## Create your first agent - -Initialize a new agent project: - -```bash -adk init my-agent -``` - -```txt - ▄▀█ █▀▄ █▄▀ Botpress ADK - █▀█ █▄▀ █░█ Initialize New Agent - - Step 1 of 2 - - -Select a template: - -› blank - Empty project with just the folder structure - - hello-world - A working chatbot with chat and webchat integrations -``` - -Select the `hello-world` template. Next, choose your preferred package manager: - -```txt - ▄▀█ █▀▄ █▄▀ Botpress ADK - █▀█ █▄▀ █░█ Initialize New Agent - - Step 2 of 2 - - -Select a package manager: - -● Bun - Install with bun -○ pnpm - Install with pnpm -○ Yarn - Install with yarn -○ npm - Install with npm -``` - -If you are logged in, the CLI will also prompt you to select a workspace to link your agent to. - -The CLI automatically installs dependencies and creates a `my-agent` directory. See [Project Structure](/adk/project-structure) for a full breakdown of the generated files. - -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 command: - -1. Generates TypeScript types for your integrations -2. Builds your agent -3. Starts a local development server -4. Watches for file changes and automatically rebuilds - -### View the Control Panel - -While `adk dev` is running, visit [`http://localhost:3001/`](http://localhost:3001/) to access the Control Panel. This gives you a visual overview of your agent project where you can browse conversations, actions, workflows, tables, triggers, knowledge bases, and [configure integration settings](/adk/managing-integrations#integration-configuration). - -You can also test your agent directly from the built-in Chat view: - - - Control Panel - Control Panel - - -### 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? ->> -``` - -## Build your agent - -Compile your agent for production: - -```bash -adk build -``` - -This creates an optimized build in the `.adk/bot/.botpress/dist` directory. - -## Deploy your agent - -When you're ready, you can deploy your agent to Botpress Cloud: - -```bash -adk deploy -``` - -This uploads your agent to your Botpress workspace and makes it available for use. - - - If you skipped workspace selection during `adk init`, run `adk login` then `adk link` to connect your agent before deploying. - - - - You deployed your first agent using the ADK! - - -## Next steps - - - - Learn about ADK project organization - - - Create your first conversation handler - - diff --git a/adk/zai/overview.mdx b/adk/zai/overview.mdx index da0c331f..f349d065 100644 --- a/adk/zai/overview.mdx +++ b/adk/zai/overview.mdx @@ -9,7 +9,7 @@ Zai is an LLM utility library that provides a clean, type-safe API for common AI - Verify a Boolean condition within a piece of content - Generate or summarize text -We recommend using Zai with the [ADK](/adk/introduction) and [SDK](/integrations/sdk/overview) to help process LLM inputs and outputs. +We recommend using Zai with the [ADK](/adk/get-started/welcome) and [SDK](/integrations/sdk/overview) to help process LLM inputs and outputs. diff --git a/docs.json b/docs.json index 7392cd00..539d1dd0 100644 --- a/docs.json +++ b/docs.json @@ -89,9 +89,14 @@ "group": "ADK", "tag": "Beta", "pages": [ - "/adk/introduction", - "/adk/quickstart", - "/adk/project-structure", + { + "group": "Get started", + "pages": [ + "/adk/get-started/welcome", + "/adk/get-started/quickstart", + "/adk/get-started/quickstart-coding-assistant" + ] + }, { "group": "Concepts", "pages": [ diff --git a/index.mdx b/index.mdx index bae6847c..7e0e10b4 100644 --- a/index.mdx +++ b/index.mdx @@ -38,8 +38,8 @@ import { IntegrationsCard } from '/home-components/IntegrationsCard.jsx' TypeScript library for building AI agents from code Beta