Example: A Minimal Agent
Build the smallest complete BxAgents project - one agent, one tool, one skill.
Example: A Minimal Agent
The smallest complete BxAgents project is examples/minimal-agent/ - three files that show the whole shape of a project: an Agent.bx, instructions, one tool, and one skill. Every other example in this guide series builds on exactly this shape.
The project
minimal-agent/
├── Agent.bx
├── instructions.md
├── tools/
│ └── Greeter.bx
└── skills/
└── greeting/
└── SKILL.md
Agent.bx extends bx-ai's own AiAgent and declares a name, description, and model in init():
class extends="bxModules.bxai.models.runnables.AiAgent" {
function init() {
super.init(
name : "minimal-agent",
description : "The smallest complete BX Agents project: one tool, one skill.",
model : aiModel( provider: "mock", params: { model: "mock-model" } )
)
return this
}
}
instructions.md is the system prompt - a plain Markdown file, copied in as-is at build time:
## Minimal Agent
You are a friendly assistant. When someone tells you their name, use the
`sayHello` tool to greet them, and follow the greeting skill's guidance
on tone.
The tool
Any class under tools/ with an @AITool-annotated function becomes a callable tool automatically - no registration step, no config entry. tools/Greeter.bx:
class {
@AITool( "Say hello to someone by name." )
function sayHello( name ) {
return "Hello, " & arguments.name & "!";
}
}
The string passed to @AITool is the tool's description, sent to the model exactly as written - see Tools for how BoxLang argument types map to the JSON schema the model sees.
The skill
A skill under skills/<name>/SKILL.md is guidance the model can pull in when it decides it's relevant - not always-on like instructions.md. skills/greeting/SKILL.md:
---
name: greeting
description: How to greet people warmly.
---
Always greet the user warmly and use their name if known.
See Skills for how description drives when a skill actually gets used.
Build and run
cd examples/minimal-agent
bxAgents build
bxAgents chat
build assembles everything above into a plain ColdBox application under .build/app (see The Build Pipeline); chat boots the generated agent in-process and drops you into a terminal REPL against it. Try:
> My name is Ada.
The model should reach for the sayHello tool and reply warmly, per the skill's guidance - both from a single sentence of instructions plus a two-line tool and a two-line skill.
Where to go next
- Example: A Multi-Agent Team - the same shape, with subagents delegating to each other.
- Example: A Scheduled Agent - the same shape, woken by a cron schedule instead of a chat prompt.
- Tools and Skills for the full conventions these two files follow.