Lección 5: Agent.bx - el agente en sí
El único archivo obligatorio - una clase real que el build instancia, no un struct de configuración.
En esta página
Agent.bx - el agente en sí
Agent.bx es el único archivo obligatorio de un proyecto BxAgents. Extiende el propio
AiAgent de bx-ai,
así que es el agente - el build lo instancia en lugar de reconstruir uno a partir de un
struct de configuración, de modo que lo que escribes es lo que se ejecuta.
class extends="bxModules.bxai.models.runnables.AiAgent" {
function init() {
super.init(
name : "my-agent",
description : "A helpful assistant",
instructions: "You are a helpful assistant.",
model : aiModel( provider: "openai", params: { model: "gpt-5" } )
)
return this
}
}
Al ser una clase real y no un descriptor que devuelve un struct, un IDE puede introspeccionarla como cualquier otra clase de BoxLang - ir a la definición, autocompletar métodos heredados, todo. Hereda y añade lo que necesites: helpers privados, métodos sobrescritos, tools registradas por código.
La regla: una declaración explícita gana
Todo lo que el build puede añadir por encima de la clase es opcional - declara un método
configure() que devuelva cualquiera de las claves de abajo para sobrescribir lo que la
propia clase fijó, o apóyate en la carpeta de convención correspondiente:
| Lo que declaras | Lo que emite el build | Si no lo declaras |
|---|---|---|
instructions.md | withInstructions( fileRead( ... ) ) | se mantienen las instrucciones de la clase |
model en configure() | setModel( aiModel( ... ) ) | se mantiene el modelo de la clase |
name / description en configure() | setName() / setDescription() | se mantienen los de la clase |
| (nada que declarar) | withTools( aiToolRegistry().getAll() ) | siempre - las tools/ descubiertas se añaden |
subAgents en la clase, o subagents/ en disco | addSubAgent( ... ) por cada hijo | se añaden igualmente |
checkpointer en configure() | withCheckpointer( ... ) | se inyecta igualmente con el valor por defecto cache |
El checkpointer es lo único que el build rellena sin que se lo pidas. Un agente
accesible desde un gateway sin checkpointer tiene el humano-en-el-bucle roto en
silencio, así que una clase que no fije ninguno recibe igualmente el valor por
defecto cache.
El slug del modelo
model es una convención propia de BxAgents - bx-ai en sí toma provider y model como
dos argumentos separados. BxAgents parte el slug solo por la primera /:
Valor de model | provider | model |
|---|---|---|
openai/gpt-5 | openai | gpt-5 |
openrouter/anthropic/claude-x | openrouter | anthropic/claude-x |
mock/mock-model | mock | mock-model |
mock es un proveedor real que nunca hace ninguna llamada de red - útil para pruebas
(consulta la Lección 19) y para seguir este curso sin ninguna
clave de API.
configure() - sobrescribir lo que fijó la clase
class extends="bxModules.bxai.models.runnables.AiAgent" {
function init() {
super.init(
name : "with-mcp-servers-agent",
model : aiModel( provider: "openai", params: { model: "gpt-5" } )
)
return this
}
function configure() {
return {
mcpServers : [ "https://example.com/mcp" ]
};
}
}
Campos útiles: name (que es además la clave de binding de este agente en WireBox - debe
ser única en todo el proyecto), model, description, subAgents (consulta la
Lección 11), mcpServers (consulta la
Lección 17), security, memory, checkpointer,
gatewaySession (consulta la Lección 14).
Sobrescrituras por entorno
Agent.bx puede declarar un método con el nombre de un entorno (production(),
development(), o cualquier nombre propio) que devuelva un struct de sobrescrituras:
function production() {
return {
model : "openai/gpt-5-mini"
};
}
El entorno activo se resuelve así, y gana el primero: flag --environment de la CLI >
variable de entorno BX_AGENTS_ENV > el valor por defecto "development".
bxAgents build --environment=production lo recoge. Usarás este mismo mecanismo para el
proveedor mock en tus pruebas (Lección 19).
Referencia completa: Agent.bx.