Lesson 4: Scaffolding Your First Agent

Run bxAgents new and see exactly what it creates for you.

Scaffolding Your First Agent

With BoxLang, bx-ai and BxAgents installed (Lesson 3), scaffold your first project:

bxAgents new my-agent --model=openai/gpt-5

--model is required - a provider/model slug (you'll see exactly how this gets parsed in Lesson 5). --name and --description are optional; --name defaults to the target directory's own name. new refuses to run if the target already contains an Agent.bx.

What gets created

my-agent/
├── Agent.bx
├── instructions.md
├── tools/
├── skills/
├── subagents/
├── models/
├── gateways/
├── schedules/
├── mcp/
├── interceptors/
├── modules/
└── tests/
    ├── box.json
    └── specs/
        └── AgentSpec.bx

Plus a .env declaring BOXLANG_HOME=.build/runtime (matching serve's own scoped runtime home) and a .gitignore (.build/, dist/, .env) - new never overwrites either if they already exist.

Every convention folder is created empty. You add files to the ones your agent actually needs and leave the rest alone - an empty tools/ folder has zero effect on the generated app.

Agent.bx looks like this

class extends="bxModules.bxai.models.runnables.AiAgent" {

	function init() {
		super.init(
			name        : "my-agent",
			description : "",
			model       : aiModel( provider: "openai", params: { model: "gpt-5" } )
		)
		return this
	}

}

It extends bx-ai's own AiAgent directly - more on exactly what that means in Lesson 5.

The test suite runs itself

new also runs box install inside the scaffolded tests/ folder, so bxAgents test (Lesson 19) works immediately with no separate step. This is best-effort - if box isn't on PATH or the install fails, new still succeeds and just tells you to run it yourself. Pass --skipInstall to opt out entirely.

Try it

bxAgents new my-agent --model=openai/gpt-5
cd my-agent
ls

You now have a real, if minimal, BxAgents project. The next four lessons walk through what's actually required to run it.

Next: Lesson 5 - Agent.bx: The Agent Itself