Copy
View as MarkdownOpen in ChatGPTOpen in ClaudeReport an issueShare on XShare on LinkedInShare on Facebook

BxAgents

Build AI agents by convention — a conventions-based framework for AI agents powered by BoxLang AI.

overview
BxAgents - 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

BxAgents 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.

A terminal session: bxAgents new scaffolds a project, bxAgents build assembles a ColdBox app, bxAgents inspect prints the agent, model and environment, and bxAgents serve starts it on http://127.0.0.1:8080

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

Start from something, not nothing

new doesn't only scaffold a blank agent - pick one of 8 built-in templates, clone an existing GitHub repo, or install a ForgeBox package instead.

8 built-in templates

--template=webui-chat|slack-bot|telegram-bot|github-bot|mcp-server|scheduled|multi-agent - real, working content layered on the same base skeleton.

Clone a GitHub repo

--repo=owner/repo - a bundled JGit client clones it; no git binary required.

Install from ForgeBox

--forgebox=<slug> - talks to ForgeBox's REST API directly; no box CLI required.

See Agent Templates for every generated file in detail, and how to publish your own.

A chat UI you didn't have to build

Set exposes: "webui" on a gateway and the build emits a complete front end - conversation history, streaming replies, light/dark theming and a mobile layout - wired to your agent.

The generated web chat UI: a conversation sidebar on the left, a multi-turn transcript in the centre, and a themed header and message composer

The same conversation with the theme toggle switched to dark

The same page at a narrow viewport, where the transcript keeps the full width and the sidebar overlays it

It is generated CSS and generated markup - themeable from Agent.bx, with no front-end build step of your own.

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. BxAgents 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.

Check your setup at any time

bxAgents doctor output: BoxLang and bx-ai versions OK, Agent.bx found, project structure validates cleanly, and one warning that the qb module is missing

Where to go next

Installation

Install BoxLang, BX AI and BxAgents.

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.

Agent Templates

Every built-in starter, GitHub/ForgeBox sourcing, and publishing your own.

Deployment & Secrets

Package a .bxa and ship it, safely.

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

Warning

BxAgents 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 Sep 17, 2026, 5:15:06 PM