Project structure

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

Directory structure

agent.config.ts

agent.json

package.json

tsconfig.json

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.

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:

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

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({ input }) {
    // Your logic here
    return { message: "This is your action's output." };
  },
});

src/tools/

Tools that the AI model can call during conversations. Tools are provided to the execute() function.

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

export default new Autonomous.Tool({
  name: "myTool",
  description: "A tool that does something useful",
  input: z.object({ query: z.string() }),
  output: z.object({ result: z.string() }),
  handler: async ({ query }) => {
    return { result: "Tool 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],
});

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:

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:

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):

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

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