> ## Documentation Index
> Fetch the complete documentation index at: https://botpress-ak-docs-20-document-updating-variables-from-outsid.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Project structure

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

## Directory structure

<Tree>
  <Tree.Folder name="src" defaultOpen>
    <Tree.Folder name="conversations">
      <Tree.File name="index.ts" />
    </Tree.Folder>

    <Tree.Folder name="workflows">
      <Tree.File name="index.ts" />
    </Tree.Folder>

    <Tree.Folder name="actions">
      <Tree.File name="index.ts" />
    </Tree.Folder>

    <Tree.Folder name="tools">
      <Tree.File name="index.ts" />
    </Tree.Folder>

    <Tree.Folder name="tables">
      <Tree.File name="index.ts" />
    </Tree.Folder>

    <Tree.Folder name="triggers">
      <Tree.File name="index.ts" />
    </Tree.Folder>

    <Tree.Folder name="knowledge">
      <Tree.File name="index.ts" />
    </Tree.Folder>
  </Tree.Folder>

  <Tree.File name="agent.config.ts" />

  <Tree.File name="agent.json" />

  <Tree.File name="package.json" />

  <Tree.File name="tsconfig.json" />
</Tree>

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

```typescript expandable theme={null}
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:

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

<CodeGroup>
  ```ts All channels theme={null}
  import { Conversation } from "@botpress/runtime";

  export default new Conversation({
    channel: "*",
    handler: async ({ execute }) => {
      await execute({
        instructions: "You are a helpful assistant.",
      });
    },
  });
  ```

  ```ts Specific channel theme={null}
  import { Conversation } from "@botpress/runtime";

  export default new Conversation({
    channel: "webchat.channel",
    handler: async ({ execute }) => {
      await execute({
        instructions: "You are a helpful assistant.",
      });
    },
  });
  ```

  ```ts Array of channels theme={null}
  import { Conversation } from "@botpress/runtime";

  export default new Conversation({
    channel: [
      "chat.channel",
      "webchat.channel"
    ],
    handler: async ({ execute }) => {
      await execute({
        instructions: "You are a helpful assistant.",
      });
    },
  });
  ```
</CodeGroup>

### `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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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`):

```typescript theme={null}
import { configuration } from "@botpress/runtime";

// Access configuration values
const apiKey = configuration.apiKey;
const maxRetries = configuration.maxRetries;
```

<Tip>
  State schemas are defined in `agent.config.ts` under `bot.state` and `user.state`. The configuration schema is defined under `configuration.schema`.
</Tip>

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

<Tip>
  Don't edit files in the `.botpress` directory manually. They are automatically generated and will be overwritten.
</Tip>

## Next steps

<CardGroup Cols={2}>
  <Card title="Conversations" horizontal icon="message-square" href="/adk/concepts/conversations">
    Learn about conversation handlers
  </Card>

  <Card title="Workflows" horizontal icon="workflow" href="/adk/concepts/workflows">
    Create long-running processes
  </Card>
</CardGroup>