BX Agents

Describe an agent in folders and files; build it into a real ColdBox application.

overview
BX Agents - Build. Constrain. Orchestrate. A conventions-based agent framework for BoxLang. Conventions first: convention over configuration for faster development. Pluggable and extensible: swap models, tools, memory and more with ease. Powerful agents: create agents that reason, act, and collaborate effectively. Production ready: built for performance, reliability, and real-world applications. The agent framework native to BoxLang.
Get Started View on GitHub

BX Agents is a conventions-based AI agent framework for BoxLang, built on ColdBox and BX AI. You describe an agent with files and folders - not a framework's API surface - and bxAgents build assembles a real, runnable ColdBox application out of it.

Assembled at build time

Discovery, validation and code generation run once, not on every boot. What you run afterwards is a plain ColdBox app.

Folders are the API

Agent.bx and instructions.md are the only required files. Every other convention folder is optional and only shapes the output if it exists.

Tools and skills

Drop an @AITool-annotated function into tools/, or a SKILL.md folder into skills/ - both are discovered and wired for you.

Agents all the way down

subagents/ nests the exact same convention tree, so a team of specialists is just more folders - built leaf-first.

Twelve gateway types

Telegram, Slack, Discord, Email, WhatsApp, Teams, Twilio, GitHub and Signal, plus http, cli and mock.

A web chat UI, generated

Ask for it in Agent.bx and the build produces a themeable, streaming chat front end with session history.

Build one in four steps

1
Install
install-bx-module bx-ai bx-agents

box install bx-ai,bx-agents
2
Scaffold
bxAgents new my-agent --model=openai/gpt-5

Then edit instructions.md and add whichever convention folders you need.

3
Build
bxAgents build

Discovery, validation, manifest, code generation - into .build/app/.

4
Talk to it
bxAgents chat
# or serve it over HTTP:
bxAgents serve --port=8080

What build actually produces

Your convention tree, and the plain ColdBox application build turns it into.

your-agent/
├── Agent.bx           # name, model, description
├── instructions.md    # the system prompt
├── tools/             # @AITool functions
├── skills/            # SKILL.md capabilities
├── subagents/         # nested agent trees
├── models/            # named model configs
├── gateways/          # HTTP/MCP/chat exposure
├── schedules/         # a real ColdBox scheduler
├── mcp/               # MCP servers you host
├── interceptors/      # lifecycle hooks
└── modules/           # module dependencies

.build/app/
├── Application.bx
├── config/
│   ├── ColdBox.bx
│   ├── WireBox.bx
│   ├── Router.bx
│   └── Scheduler.bx
├── agent/
│   └── GeneratedAgentFactory.bx
├── tools/  skills/  mcp/
├── handlers/  interceptors/
└── index.bxm
Why assemble at build time instead of at request time?

Most agent frameworks wire tools, skills, routes and schedules together at request time, on every boot. BX Agents does the opposite: bxAgents build runs discovery, validation and code generation exactly once, producing a plain ColdBox application under .build/app/.

Starting it - via bxAgents serve, a real boxlang-miniserver process, or a portable .bxa deployed anywhere BoxLang runs - is then just booting an ordinary app. No convention scanning, no dynamic file walking, no build-time work deferred into the request path.

Start with one file

Only Agent.bx is required. instructions.md is optional - set instructions directly in the class, or drop the file in and let the build wire it in. Every other folder only affects the generated output if it exists and has content in it - so you add conventions as you actually need them.

Agent.bx IS the agent

Agent.bx extends BX AI's own AiAgent directly - the build instantiates your class rather than rebuilding one from a config struct, so what you write is what runs, and an IDE can introspect it like any other class. See Agent.bx.

Reach it from anywhere

Chat platforms

Nine push-style gateways - Telegram, Slack, Discord, Email, WhatsApp Cloud, Teams, Twilio, GitHub and Signal - coordinated by one session with queue / steer / interrupt policies.

HTTP and MCP

Expose the agent over HTTP routes, or host local MCP servers from mcp/ so other clients can call your tools.

Ship it

Package a portable .bxa and deploy it with local, ssh, docker, digitalocean, ftp or sftp - secrets stay environment variables, never build artifacts.

Where to go next

Installation

Install BoxLang, BX AI and BX Agents.

Quick Start

Scaffold, build and chat with your first agent.

Conventions

One page per convention folder, start to finish.

The Build Pipeline

Exactly what build does, in order.

CLI Reference

Every verb and its flags.

Deployment & Secrets

Package a .bxa and ship it, safely.

Every convention folder also has a working, buildable sample under examples/.

Warning

BX Agents is under active development. Known Limitations tracks the honest gaps - what's tested against a real running app, what still only runs against BX AI's "mock" provider, and one real upstream ColdBox quirk this project ran into and worked around.

Edit this page Download Markdown Last updated Aug 21, 2026, 6:33:28 PM