Lesson 5: Agent.bx - The Agent Itself

The one required file - a real class the build instantiates, not a config struct.

Agent.bx - The Agent Itself

Agent.bx is the only required file in a BxAgents 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.

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
	}

}

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. Inherit and add whatever you need: private helpers, overridden methods, tools registered in code.

The rule: an explicit declaration wins

Everything the build can layer on top of the class is optional - declare a configure() method returning any of the keys below to override what the class itself set, or rely on a matching convention folder:

The model slug

model is BxAgents' own convention - bx-ai itself takes provider and model as two separate arguments. BxAgents splits the slug on the first / only:

mock is a real provider that never makes a network call - useful for tests (see Lesson 19) and for following this course with no API key at all.

configure() - overriding what the class set

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" ]
		};
	}

}

Useful fields: name (also this agent's WireBox binding key - must be unique across the whole project), model, description, subAgents (see Lesson 11), mcpServers (see Lesson 17), security, memory, checkpointer, gatewaySession (see Lesson 14).

Environment overrides

Agent.bx may declare a method named after an environment (production(), development(), or any custom name) returning a struct of overrides:

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

The active environment resolves, highest wins: --environment CLI flag > BX_AGENTS_ENV env var > "development" default. bxAgents build --environment=production picks it up. You'll use this exact mechanism for the mock provider in your tests (Lesson 19).

Full reference: Agent.bx.

Next: Lesson 6 - instructions.md and the System Prompt