Agent.bx

The one required file - a class that extends bx-ai's own AiAgent, so it IS the agent.

Agent.bx

Agent.bx is the only required file in a BX Agents project. It extends bx-ai's own AiAgent, so it is the agent - the build instantiates it rather than rebuilding one from a config struct, so what you write is what runs. Inherit and add whatever you need: private helpers, overridden methods, tools registered in code. Because it's a real class rather than a struct-returning descriptor, an IDE can introspect it like any other BoxLang class - jump to definition, autocomplete on inherited methods, the works.

class extends="bxModules.bxai.models.runnables.AiAgent" {

	function init() {
		super.init(
			name        : "my-agent",
			description : "A helpful assistant",
			instructions: "You are a helpful assistant.",
			model       : aiModel( provider: "openai", params: { model: "gpt-5" } )
		)
		return this
	}

}

bxAgents new scaffolds exactly this shape. instructions.md is optional - set instructions directly in super.init(), or drop the file beside Agent.bx and let the build wire it in for you (see the table below).

What the build layers on top of the class

The rule: an explicitly declared convention wins; otherwise the class is in charge.

So an agent that sets everything in its own init() gets nothing imposed on it, while one that sets the bare minimum still picks up the conventions it didn't speak for. Everything below is optional - declare a configure() returning any of these keys to override what the class itself set, or the matching instructions.md/tools//subagents/ convention folder:

The class is copied into the generated app at agent/classes/ and instantiated there by its own absolute file path (never a relative lookup that would depend on a registered mapping), exactly as tools/, skills/ and mcp/ are copied - so a packaged .bxa carries it, and chat/invoke/serve all instantiate it the same way whether or not a real ColdBox container is booted.

configure() (optional) - overriding what the class set

A configure() method is entirely optional. Declare it only to override specific fields from outside the class - useful for keeping deployment-specific values (a different model per environment, say) out of the class body itself:

class extends="bxModules.bxai.models.runnables.AiAgent" {

	function init() {
		super.init(
			name  : "with-mcp-servers-agent",
			model : aiModel( provider: "openai", params: { model: "gpt-5" } )
		)
		return this
	}

	function configure() {
		return {
			mcpServers : [
				"https://example.com/mcp",
				{ url : "https://other.com/mcp", name : "other" }
			]
		};
	}

}

The model slug

model is BX Agents' own convention - bx-ai itself takes provider and model as two separate arguments to aiModel(). BX Agents splits the slug on the first / only, so a provider that itself contains a slash (like OpenRouter's openrouter/anthropic/claude-x) still parses correctly:

If model has no / at all, it must be either a known core provider name or match a models/ entry's name - validation rejects anything else. The recognized core providers are: bedrock, claude, cohere, deepseek, docker, elevenlabs, gemini, grok, groq, huggingface, minimax, mistral, mock, ollama, openai, openai-compatible, openrouter, perplexity, voyage (kept in sync with bx-ai's own CORE_PROVIDERS). mock is a real provider, useful for tests and CI - it never makes a network call.

This slug-splitting convention is what a configure()-declared model string goes through - super.init()'s own model argument instead takes a real AiModel instance directly (aiModel( provider: "...", params: { model: "..." } )), since the class already speaks bx-ai's own API.

Environment overrides

Agent.bx may declare a method named after an environment (e.g. production(), development(), or any custom name) returning a struct of overrides - this works whether or not the class also declares a configure():

class extends="bxModules.bxai.models.runnables.AiAgent" {

	function init() {
		super.init(
			name        : "override-agent",
			description : "An agent with an environment override",
			model       : aiModel( provider: "openai", params: { model: "gpt-5" } )
		)
		return this
	}

	function production() {
		return {
			model : "openai/gpt-5-mini"
		};
	}

}

The active environment is resolved with this precedence (highest wins):

1. --environment CLI flag (bxAgents build --environment=production)
2. BX_AGENTS_ENV environment variable
3. "development" (default)

This is a build-time decision only, distinct from ColdBox's own runtime environment detection (the generated app reads getSetting("environment") on its own, per ColdBox's environments convention) - this precedence only decides which environment() override method on Agent.bx, and which boxlang-{env}.json/miniserver-{env}.json files, the build pipeline applies.

If no method matching the active environment exists, no override is applied.

Merge semantics

The full resolution order (lowest to highest precedence) is:

1. configure() (optional)
2. the matching environment-override method, if any
3. boxlang.json
4. boxlang-{environment}.json
5. miniserver.json
6. miniserver-{environment}.json

Struct keys are merged recursively - a nested struct in a higher-precedence source only overrides the keys it actually sets, leaving sibling keys from a lower-precedence source intact. Arrays and all scalar values are replaced whole, never appended or concatenated.

boxlang.json/boxlang-{env}.json/miniserver.json/miniserver-{env}.json are all optional project-root JSON files, useful for config that's easier to express as data than as BoxLang code (e.g. model defaults):

// boxlang.json
{
	"modelDefaults": { "temperature": 0.7, "maxTokens": 1000 }
}

// boxlang-production.json
{
	"modelDefaults": { "temperature": 0.2 }
}

Building with --environment=production here yields modelDefaults: { temperature: 0.2, maxTokens: 1000 } - the recursive merge kept maxTokens from the base file since boxlang-production.json never mentioned it.