Configuration

Understand your project structure and how to configure your agent.

Project structure

Here’s a breakdown of the key files in your project after running adk init:

src

actions

conversations

knowledge

tables

triggers

workflows

evals

.mcp.json

agent.config.ts

agent.json

agent.local.json

AGENTS.md

CLAUDE.md

The agent.json file stores the shared production link (workspaceId, botId, and apiUrl) and is safe to commit. The agent.local.json file is gitignored and holds per-developer overrides, including the development bot ID (devId).

The ADK scans src/ and discovers primitives automatically. Each file exports a primitive (a Conversation, Workflow, Action, etc.) and the framework registers it at build time.

agent.config.ts

Everything about your agent is configured in agent.config.ts by calling defineConfig and passing in a configuration object.

Here’s the hello-world template default configuration with all available fields shown:

import { z, defineConfig } from "@botpress/runtime"

export default defineConfig({
  // Identity
  name: "my-agent",
  description: "An AI agent built with Botpress ADK",

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

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

  // Metadata tags
  conversation: { tags: {} },
  message: { tags: {} },
  workflow: { tags: {} },

  // Sensitive values (API keys, tokens)
  secrets: {},

  // Deploy-time settings
  configuration: {
    schema: z.object({}),
  },

  // Integrations
  dependencies: {
    integrations: {},
  },

  // Custom events
  events: {},

  // Test settings
  evals: {},
})

Models

The defaultModels field controls which LLM your agent uses:

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

Model	Used by
autonomous	execute() calls in conversations and workflows
zai	Zai operations like zai.extract(), zai.check(), zai.text()

If you don’t set defaultModels, the ADK defaults to openai:gpt-4.1-mini-2025-04-14 for autonomous and openai:gpt-4.1-2025-04-14 for zai.

You can pass an array of models for fallback. If the first model fails, the next one is tried:

defaultModels: {
  autonomous: ["cerebras:gpt-oss-120b", "openai:gpt-4.1-2025-04-14"],
},

You can also browse and set models from the dev console under Settings > LLM Config.

To override the model on a specific execute() call:

await execute({
  model: "openai:gpt-4.1-2025-04-14",
  instructions: "You are a helpful assistant.",
})

State

The state field lets you define schemas for data that your agent can persist across a certain scope. There are two available scopes:

Scope	Persists across	Use for
bot	All conversations and users	Global counters, shared config
user	All conversations for a given user	Preferences, profile data

You can define schemas for state using Zod. The ADK generates TypeScript types from them, so state access is fully typed:

bot: {
  state: z.object({
    totalConversations: z.number().default(0),
  }),
},
user: {
  state: z.object({
    name: z.string().optional(),
    preferredLanguage: z.string().default("en"),
  }),
},

For more information about reading and writing state at runtime, check out our guide to managing states.

Tags

The tags field lets you define metadata that you can attach to bots, users, conversations, messages, and workflows:

bot: {
  tags: {
    environment: { title: "Environment", description: "dev or prod" },
  },
},
conversation: {
  tags: {
    priority: { title: "Priority" },
  },
},

Tags are useful for filtering and organizing data in the Botpress platform.

Secrets

The secrets field lets you store sensitive values, like API keys or tokens. They are declared here, but values are managed separately per environment and never committed to version control:

secrets: {
  OPENAI_KEY: { description: "OpenAI API key" },
  SENTRY_DSN: { optional: true, description: "Error tracking DSN" },
},

For more information about using secrets, check out our guide on setting up your environment.

Configuration

The configuration field defines static, deploy-time settings. Unlike state, these are read-only at runtime:

configuration: {
  schema: z.object({
    apiEndpoint: z.string().default("https://api.example.com"),
    enableBeta: z.boolean().default(false),
  }),
},

For managing configuration values across environments, check out our guide to setting up your environment.

Dependencies

Dependencies declare which integrations your agent uses. Add them with the CLI:

adk add webchat
adk add slack@latest

The CLI resolves the version and updates agent.config.ts:

dependencies: {
  integrations: {
    webchat: "webchat@0.3.0",
    slack: "slack@1.0.0",
  },
},

For more information about finding, configuring, and managing integrations, check out our integrations guide.

Custom events

The events field lets you define custom events your agent can emit and subscribe to:

events: {
  orderPlaced: {
    description: "Fired when an order is placed",
    schema: z.object({
      orderId: z.string(),
      total: z.number(),
    }),
  },
},

You can then listen for these events within triggers and conversations. For more information, check out our guide on setting up triggers.

Evals

The evals field lets you configure how your agent’s automated tests run:

evals: {
  idleTimeout: 15000,
  judgePassThreshold: 3,
  judgeModel: "openai:gpt-4o",
},

Field	Description
idleTimeout	Milliseconds to wait for the agent to respond before timing out
judgePassThreshold	Pass threshold for LLM judge assertions (1-5)
judgeModel	Model used for LLM judge assertions

For more information, check out our full guide to writing and running evals.