Configuration defines your agent’s identity, models, state schemas, dependencies, and runtime settings. Everything is centralized in agent.config.ts.
agent.config.tsThe 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 the 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 ({ // your config schema }), }, dependencies: { integrations: { chat: "chat@0.7.7" , webchat: "webchat@0.3.0" , }, }, });
Config options Show defineConfig options
Agent name. Used to identify your agent in the Botpress dashboard.
Optional description of your agent.
Default LLM models for your agent. Model used for execute() calls in conversations and workflows.
Model used for Zai operations (zai.extract(), zai.check(), etc.).
Bot-level state schema and tags. See State . User-level state schema and tags. See State . Runtime configuration schema. Values are set via adk config and accessed at runtime via the configuration import. A Zod object schema defining the configuration fields. Must be z.object().
Custom event definitions. Each key is an event name, with an optional schema and description.
Evaluation settings. Timeout in seconds for idle eval conversations.
Pass threshold for LLM judge assertions (1-5).
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 Validate configuration Run adk config to validate all configuration values and set any that are missing:
📝 Configuration (development) ✓ Configuration validated successfully
This validates your values against the schema and prompts for any missing or invalid fields. Requires a configuration.schema in your agent.config.ts.
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 "help@mycompany.com"
✓ Configuration updated (development) supportEmail = help@mycompany.com
adk config:get supportEmail
📝 Configuration value (development) Key: supportEmail Value: help@mycompany.com
Production configuration Use the --prod flag to manage production configuration separately from development:
adk config --prod adk config:set supportEmail "help@mycompany.com" --prod adk config:get supportEmail --prod
Agent configuration (adk config) is separate from integration configuration. Integration settings like API keys are managed in the Control Panel during adk dev. 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" , },
autonomousexecute() in conversations and workflowszaizai.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 : "chat@0.7.7" , webchat : "webchat@0.3.0" , slack : "slack@1.0.0" , }, },
Integration settings (API keys, tokens, etc.) are configured in the Control Panel during adk dev, not in agent.config.ts. 
