Agent.yaml
The default way to define an agent - plain settings in a YAML file, no code.
Agent.yaml
Agent.yaml is the default way to define an agent. It is a plain YAML file - a name, a model, and any of the optional settings below - and the build turns it into a running agent. Most agents need nothing more than this file and an instructions.md beside it.
name: support
description: Answers customer questions about orders
model: openai/gpt-5
environments:
test:
model: mock/mock-model
bxAgents new scaffolds exactly this shape. When the definition needs real code (hooks, dynamic instructions, tools registered in code), use the advanced option instead: a class-based Agent.bx, scaffolded with bxAgents new --class.
A folder holds one agent definition. An Agent.yaml (or Agent.yml) together with an Agent.bx in the same folder is an error - two definitions of one agent would leave it ambiguous which settings win - and build fails and names both files so you can keep one. This applies to the project root and to every subagent folder, and a project can mix the two: a YAML root with a class-based subagent, or the other way round.
Settings
| Key | Type | Notes |
|---|---|---|
name | string | Also becomes this agent's config/WireBox.bx binding key at build time, so it must be unique across the whole project (root + every subagent). |
model | string | A provider/model slug, a bare provider name, or the name of a models/ entry. See The model slug. |
description | string | Optional. |
instructions | string | Optional inline instructions. See Instructions. |
subAgents | list of strings | Names of sibling folders under the root project's subagents/. See subagents/. |
mcpServers | list | Remote MCP servers - each entry a URL string or { url, name }. See mcp/. |
security | mapping | Forwarded verbatim into the generated app's bxai module settings; bx-ai's own SecurityDirector turns it into guardrail middleware. |
memory | string or mapping | The agent's conversation memory. A bare string is the type (cache); a mapping is { type, ...config } and is passed through to aiMemory(). |
checkpointer | mapping | { type: cache\|file\|jdbc, ...config }. Defaults to { type: cache } if omitted. |
gatewaySession | mapping | { policy, maxQueueDepth }, both optional. See Agent.bx for the values; they are identical. |
agentApi | mapping | { enabled, tokenEnvVar }, both optional. See The always-on agent route. |
environments | mapping | Per-environment overrides. See Environments. |
These are the same settings an Agent.bx's configure() returns, so every behavior documented for them applies unchanged.
An unknown key is an error, and the message lists the valid ones. A typo such as modle: would otherwise do nothing, quietly. Settings that arrive in later releases (for example tools) are rejected the same way until they exist, rather than being silently ignored. Anything free-form belongs in an Agent.bx.
A value of the wrong type (a text where a list belongs, say) and an empty value (model: with nothing after it) are errors too.
Instructions
The agent's instructions are its system prompt. Put them in an instructions.md beside Agent.yaml, the usual choice because the file is plain Markdown and easy to edit:
my-agent/
├── Agent.yaml
└── instructions.md
For a short prompt you can write them inline instead:
name: greeter
model: openai/gpt-5
instructions: |
You greet people by name.
Keep it to one sentence.
If both exist, instructions.md wins - the file is the more deliberate choice, so a stray instructions: line cannot override it. If neither exists, build fails and says so.
Environments
environments holds overrides keyed by environment name. It is the YAML spelling of the environment-override methods (production()) an Agent.bx can declare:
name: support
model: openai/gpt-5
environments:
production:
model: openai/gpt-5-mini
staging:
description: Staging copy
The active environment is chosen with this precedence, highest first:
- the
--environmentCLI flag (bxAgents build --environment=production) - the
BX_AGENTS_ENVenvironment variable development
Only the block for the active environment is applied, on top of the top-level settings; keys it does not mention are left alone. Each block accepts the same keys as the top level, except environments itself.
bxAgents test builds against the test environment, which is why a scaffolded project carries a test block pointing at the mock provider: its tests need no API key or network access.
An Agent.yaml cannot compute its environment. The detectEnvironment() method described under Environment overrides needs code, so a project that needs it uses an Agent.bx.
The overrides then merge with boxlang.json, boxlang-{environment}.json, miniserver.json and miniserver-{environment}.json exactly as described in Merge semantics.
Requirements
Reading YAML needs the bx-yaml module, 1.1.0 or later. BxAgents bundles it, so there is nothing to install. Global YAML tags (such as !!java.io.File) are rejected, so a cloned project's Agent.yaml cannot make the build instantiate arbitrary Java classes.
YAML or Agent.bx?
| Use | When |
|---|---|
Agent.yaml | The agent is configuration: a name, a model, instructions, memory, subagents. This is almost every agent. |
Agent.bx | The definition itself needs code: hooks, dynamic instructions, tools registered in code, an overridden method, or detectEnvironment(). |
You can start with YAML and switch later: create the Agent.bx, move the settings across, and delete the Agent.yaml.