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

Introduction to BxAgents

A 20-lesson course from "what is BxAgents" to a deployed, multi-channel agent.

coursegetting-started

Introduction to BxAgents

Twenty lessons, start to finish: install the CLI, scaffold a project, understand Agent.bx, wire up tools, skills and subagents, expose your agent over HTTP and to chat platforms, ship the generated web UI, schedule background work, test it for real, and package + deploy it. Every lesson links back to the full Conventions reference for the deep dive - this course is the guided path through it.

Info

Each lesson tracks your progress in this browser (no account needed) - visit a lesson and it's marked read, and Continue where you left off below picks up right where you stopped.

  1. Lesson 1: Welcome to BxAgentsWhat this course covers, what you'll build, and how each lesson is organized.
  2. Lesson 2: What Is BxAgents?Why conventions over configuration, and why assembly happens once at build time.
  3. Lesson 3: Installing BxAgentsInstall BoxLang, bx-ai and BxAgents, and verify the bxAgents command works.
  4. Lesson 4: Scaffolding Your First AgentRun bxAgents new and see exactly what it creates for you.
  5. Lesson 5: Agent.bx - The Agent ItselfThe one required file - a real class the build instantiates, not a config struct.
  6. Lesson 6: instructions.md and the System PromptThe optional file that becomes your agent's system prompt.
  7. Lesson 7: Building Your AgentbxAgents build and the five-phase pipeline that turns your project into an app.
  8. Lesson 8: Talking to Your Agentchat, invoke and serve - three ways to run the exact same built agent.
  9. Lesson 9: Giving Your Agent ToolsAny @AITool-annotated function under tools/ becomes a callable tool.
  10. Lesson 10: Packaging SkillsClaude Agent Skills - one subfolder per SKILL.md, loaded on demand.
  11. Lesson 11: Composing SubagentsNested agents, each an ordinary BxAgents project of its own, wired as callable tools.
  12. Lesson 12: Named Model ConfigsReusable named model configurations, referenced from Agent.bx by name.
  13. Lesson 13: Exposing Your Agent over HTTP and MCPgateways/ entries with an exposes key turn your agent into a real HTTP route.
  14. Lesson 14: Connecting Chat PlatformsChannel-adapter gateways - nine chat platforms plus http/cli/mock, all one GatewaySession.
  15. Lesson 15: The Generated Web Chat UIA complete browser chat client - sidebar, streaming, approvals, SQLite store.
  16. Lesson 16: Scheduling Background Workschedules/Scheduler.bx - a real, hand-written ColdBox scheduler, passed through untouched.
  17. Lesson 17: Hosting and Consuming MCP ServersMCP in both directions - consume remote servers from Agent.bx, host your own under mcp/.
  18. Lesson 18: Interceptors and Module DependenciesColdBox lifecycle hooks scoped by @scope, and BoxLang module dependencies under modules/.
  19. Lesson 19: Testing Your AgentA ready-to-run TestBox suite, mockResponses(), and matchers built for agent behavior.
  20. Lesson 20: Packaging, Deploying, and Wrapping UpPackage to a .bxa, ship it to a real target, and where to go from here.

Who this is for

Anyone who wants to build an AI agent without hand-wiring a framework's API surface - you describe an agent with files and folders, and bxAgents build assembles a real, runnable ColdBox application out of it. No prior BoxLang or ColdBox experience is assumed, though it helps.

What you'll have built by Lesson 20

An agent with its own tools and a packaged skill, reachable from the CLI, a browser chat UI, and an HTTP API, with a test suite that runs with no API key, and a packaged .bxa ready to deploy.

Ready? Start with Lesson 1: Welcome to BxAgents.

Edit this page Download Markdown Last updated Sep 17, 2026, 5:15:06 PM