Project structure

ADK projects follow a consistent structure that organizes your agent’s code, configuration, and dependencies.

Directory structure

my-agent/
├── agent.config.ts          # Agent configuration
├── agent.json               # Linked bot configuration
├── dependencies.json         # Integration dependencies
├── package.json             # Node.js project configuration
├── tsconfig.json            # TypeScript configuration
└── src/                     # Source code
    ├── conversations/       # Conversation handlers
    ├── workflows/          # Long-running processes
    ├── actions/            # Callable functions
    ├── tables/             # Data storage schemas
    ├── triggers/           # Event subscriptions
    └── knowledge/          # Knowledge base sources

Configuration files

agent.config.ts

The main agent configuration file. Defines your agent’s name, description, default models, and state schemas.

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
    }),
  },

  user: {
    state: z.object({
      // User-level state
    }),
  },
});

agent.json

Links the agent to a bot in your Workspace:

{
  "botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "workspaceId": "wkspace_xxxxxxxxxxxxxxxxxxxxxxxxxx",
  "devId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

dependencies.json

Declares the integrations your agent uses. The ADK automatically generates TypeScript types for these integrations.

{
  "integrations": {
    "webchat": {
      "version": "webchat@latest",
      "enabled": true
    },
    "chat": {
      "version": "chat@latest",
      "enabled": true
    }
  }
}

package.json

Standard Node.js package configuration. Includes scripts for dev, build, and deploy commands.

{
  "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.

All channels

import { Conversation } from "@botpress/runtime";

export default new Conversation({
  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.

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.

import { Action, z } from "@botpress/runtime";

export default new Action({
  name: "yourAction",
  input: z.object({}),
  output: z.object({}),
  async handler() {
    // 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.

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.

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.

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],
});

Generated files

The ADK generates TypeScript types in .adk/bot/.botpress:

• .botpress/types/ - Type definitions for integrations and interfaces
• .botpress/dist/ - Compiled output (created during build)

Don’t edit files in the .botpress directory manually. They are automatically generated and will be overwritten.

Next steps

Conversations

Learn about conversation handlers

Workflows

Create long-running processes