Quickstart

This guide walks you through installing the ADK and creating your first agent project.

You will need:

• A Botpress account
• Node.js (v22.0.0 or higher)
• A supported package manager — bun, pnpm, yarn or npm

Installation

Install the ADK CLI globally:

macOS & Linux

curl -fsSL https://github.com/botpress/adk/releases/latest/download/install.sh | bash

Verify the installation:

adk --version

Create your first agent

Initialize a new agent project:

adk init my-agent

 ▄▀█ █▀▄ █▄▀  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:

 ▄▀█ █▀▄ █▄▀  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 with:

• agent.config.ts — Agent configuration, state schemas, and integration dependencies
• agent.json — Workspace and bot IDs for your linked agent
• package.json — Project configuration with dev, build, and deploy scripts
• tsconfig.json — TypeScript configuration
• src/ — Source code with subdirectories for conversations, actions, tables, triggers, workflows, and knowledge
• .mcp.json — MCP configuration for AI coding assistants (Claude Code, Cursor, etc.)
• CLAUDE.md / AGENTS.md — AI assistant instructions for your project

The CLI generates .mcp.json for Claude Code by default. To add MCP configuration for other supported editors, run adk mcp:init --all inside your project.

Navigate into your project:

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:

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

Chat in the terminal

Open a new terminal window and start a conversation with your agent:

adk chat

Botpress Chat
Type "exit" or press ESC key to quit
👤 Hey!
🤖 Hello! How can I assist you today?
>>

View the Control Panel

While adk dev is running, visit http://localhost:3001/ to access the Control Panel. This gives you a visual breakdown of your agent project — browse actions, tools, workflows, tables, and configure integration settings.

Build your agent

Compile your agent for production:

adk build

This creates an optimized build in the .adk/bot/.botpress/dist directory.

Deploy your agent

If you skipped workspace selection during adk init, run adk login then adk link to connect your agent before deploying.

When you’re ready, deploy your agent to Botpress Cloud:

adk deploy

This uploads your agent to your Botpress workspace and makes it available for use.

You deployed your first agent using the ADK!

Next steps

Project Structure

Learn about ADK project organization

Conversations

Create your first conversation handler