box.json
List the extra packages your agent needs, such as bx-playwright. You install them; the build carries them into the app.
box.json
BxAgents already bundles BX AI, ColdBox and the other modules agents use, so most agents need nothing more. When an agent needs a package that is not bundled, for example bx-playwright for browser tools, list it in a box.json at the project root and install it yourself:
{
"name": "support-bot",
"dependencies": {
"bx-playwright": "*"
},
"devDependencies": {
"testbox": "*"
}
}
BxAgents never installs anything. Install packages the way you normally do, with CommandBox (box install) or the BoxLang binary (install-bx-module bx-playwright --local), from the project root. bxAgents new scaffolds a box.json for you, with TestBox as a development dependency installed into lib/testbox, and a .gitignore that already ignores lib/ and boxlang_modules/. Commit box.json; keep the installed folders out of version control.
Where installed packages go
| What | Folder in the project | What build does with it |
|---|---|---|
BoxLang modules (bx-playwright, ...) | boxlang_modules/ | BoxLang loads this folder from the project root, so chat, invoke and test find them. build copies it to .build/app/boxlang_modules, so serve and a packaged .bxa carry it too. |
| ColdBox libraries and modules | lib/coldbox, lib/modules/<name> | Copied into the app over the bundled ones, so a project can add or override a library. |
| Test tools (TestBox, ...) | lib/<name> or tests/ | Not copied: the app does not need them. |
Development dependencies
A BoxLang module that is only in devDependencies is left out of .build/app, and the build says which. A module is matched to box.json by the slug in its own box.json, or by its folder name (bxplaywright for bx-playwright). One listed in both sections is kept.
Using an installed module
A module that registers tools, such as bx-playwright, is used by naming its tools in the agent's tools. If the module is not installed, the error says how to install it:
tools:
- "*@bxplaywright"
box.json is different from modules/, which holds ColdBox modules that are part of your project's own source.