Skip to main content
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, 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
    }),
  },

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

  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. 
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/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