Skip to main content
This guide walks you through installing the ADK and creating your first agent project.
You will need:

​
Installation

Install the ADK CLI globally: 
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


Select a template:

› Blank
    Start with an empty agent project

  Hello World
    Start with a conversation agent project
Select the Hello World template, then follow the prompts to set up the agent. This creates a new my-agent directory with:
  • agent.config.ts - Agent configuration
  • agent.json - Configuration for your linked bot
  • dependencies.json - Integration dependencies
  • package.json - Project configuration
  • tsconfig.json - TypeScript configuration
  • src/ - Source code directory structure

​
Install dependencies

Once you’ve finished the setup, navigate into your project: 
cd my-agent
Install the dependencies: 
bun install

​
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 ADK console

Visit http://localhost:3001/ to access the interactive ADK console. This gives you an intuitive, visual breakdown of your agent project and lets you configure its integration’s settings.

​
Build your agent

Compile your agent for production: 
adk build

📦 Loaded project: my-agent
📝 Generating assets types...
✅ Assets types generated
🔨 Generating Botpress bot project...
✅ Bot project generated
🏗️  Building agent...

✅ Build completed successfully!
📦 Output directory: <project-path>/.adk/bot/.botpress/dist
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: 
adk deploy

📤 Deploying bot to Botpress...

✅ Agent deployed successfully!
🌐 Your agent is now live on Botpress
🤖 Bot ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
🏢 Workspace ID: wkspace_xxxxxxxxxxxxxxxxxxxxxxxxxx
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