Configuration

Configuration defines your agent’s identity, models, state schemas, dependencies, and runtime settings. Everything is centralized in agent.config.ts.

agent.config.ts

The main configuration file uses defineConfig from @botpress/runtime:

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({}),
    tags: {},
  },

  user: {
    state: z.object({}),
    tags: {},
  },

  conversation: {
    tags: {},
  },

  message: {
    tags: {},
  },

  workflow: {
    tags: {},
  },

  configuration: {
    schema: z.object({
      apiKey: z.string(),
      maxRetries: z.number().default(3),
    }),
  },

  dependencies: {
    integrations: {
      chat: { version: "chat@0.7.7", enabled: true },
      webchat: { version: "webchat@0.3.0", enabled: true },
    },
  },
});

Config options

Show defineConfig options

name · string

Agent name. Used to identify your agent in the Botpress dashboard.

description · string

Optional description of your agent.

defaultModels · object

Default LLM models for your agent.

Show properties

autonomous · string

Model used for execute() calls in conversations and workflows.

zai · string

Model used for Zai operations (zai.extract(), zai.check(), etc.).

bot · object

Bot-level state schema and tags. See State.

user · object

User-level state schema and tags. See State.

conversation · object

Conversation-level tags.

message · object

Message-level tags.

workflow · object

Workflow-level tags.

configuration · object

Runtime configuration schema. Values are set via adk config and accessed at runtime via the configuration import.

Show properties

schema · z.ZodObject · required

A Zod object schema defining the configuration fields. Must be z.object().

dependencies · object

Integration and interface dependencies. See Managing Integrations.

events · object

Custom event definitions. Each key is an event name, with an optional schema and description.

evals · object

Optional evaluation settings.

Show properties

idleTimeout · number

Timeout in seconds for idle eval conversations.

judgePassThreshold · number

Pass threshold for LLM judge assertions (1-5).

judgeModel · string

Model to use for LLM judge assertions (e.g., "openai:gpt-4o").

Accessing configuration at runtime

Import configuration from @botpress/runtime to access your agent’s configuration values:

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

const apiKey = configuration.apiKey;
const maxRetries = configuration.maxRetries;

Configuration values are defined by the configuration.schema in agent.config.ts and set via the adk config command or the Botpress dashboard.

Configuration is read-only at runtime. Attempting to set a value will throw an error.

Managing configuration

Interactive configuration

Run adk config to validate and interactively set all configuration values:

adk config

📝 Configuration (development)

✓ Configuration validated successfully

This validates your values against the schema and prompts for any missing or invalid fields.

adk config requires a configuration.schema in your agent.config.ts. Without one, you’ll see “No configuration schema defined.”

Get and set values

Set and retrieve individual configuration values. Note that config:get reads persisted values only and does not resolve schema defaults:

adk config:set supportEmail "[e-mail]"

✓ Configuration updated (development)
  supportEmail = [e-mail]

adk config:get supportEmail

📝 Configuration value (development)

  Key:   supportEmail
  Value: [e-mail]

Production configuration

Use the --prod flag to manage production configuration separately from development:

adk config --prod
adk config:set supportEmail "[e-mail]" --prod
adk config:get supportEmail --prod

Agent configuration (adk config) is separate from integration configuration. Integration settings like API keys are configured in agent.config.ts under dependencies or via the Control Panel during adk dev. See Managing Integrations for details.

Environment variables

You can use process.env directly in agent.config.ts and throughout your agent code. This is useful for keeping sensitive values like API keys out of your source code:

configuration: {
  schema: z.object({
    apiKey: z.string().default(process.env.MY_API_KEY ?? ""),
    webhookUrl: z.string().default(process.env.WEBHOOK_URL ?? ""),
  }),
},

Then access them at runtime via the typed configuration import:

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

const response = await fetch("https://api.example.com/data", {
  headers: { Authorization: `Bearer ${configuration.apiKey}` },
});

There is no dedicated secrets API in the ADK. For integration-specific credentials (like OAuth tokens), configure them in agent.config.ts under dependencies or via the Botpress dashboard. See Managing Integrations for details.

Default models

The defaultModels field sets which LLM models your agent uses:

defaultModels: {
  autonomous: "cerebras:gpt-oss-120b",
  zai: "cerebras:gpt-oss-120b",
},

• autonomous: used by execute() in conversations and workflows
• zai: used by Zai operations like zai.extract(), zai.check(), zai.text()

You can override the model per-call using the model prop on execute().

Custom events

Define custom events that your agent can emit and listen to:

export default defineConfig({
  name: "my-agent",
  events: {
    orderPlaced: {
      description: "Fired when an order is placed",
      schema: z.object({
        orderId: z.string(),
        total: z.number(),
      }),
    },
  },
});

Custom events can be subscribed to in Triggers and Conversations (via the events prop).

Dependencies

The dependencies field declares which integrations your agent uses:

dependencies: {
  integrations: {
    chat: { version: "chat@0.7.7", enabled: true },
    webchat: { version: "webchat@0.3.0", enabled: true },
    slack: { version: "slack@1.0.0", enabled: true },
  },
},

See Managing Integrations for details on adding, removing, and configuring integrations.