Plantillas de agentes

Cada `--template` integrado, cómo tomar un proyecto desde GitHub o ForgeBox, y cómo publicar el tuyo.

Plantillas de agentes

bxAgents new crea un proyecto de una de tres formas mutuamente excluyentes - consulta la Referencia de la CLI para la sintaxis exacta de los flags y las reglas de validación. Esta página entra a fondo en las tres: qué genera exactamente cada --template integrado, qué aspecto debe tener un origen --repo/--forgebox para funcionar como fuente de proyecto, y cómo construir y publicar el tuyo.

bxAgents new my-agent --model=openai/gpt-5 --template=<nombre>   # una plantilla integrada
bxAgents new my-agent --repo=owner/repo-name                     # clonar un repositorio de GitHub
bxAgents new my-agent --forgebox=some-package-slug               # instalar un paquete de ForgeBox

Los tres caminos acaban en lo mismo: un directorio que contiene un Agent.bx en su raíz, listo para bxAgents build. Lo que cambia es de dónde viene ese Agent.bx (y todo lo que lo rodea).

Las 8 plantillas --template integradas

Todas las plantillas parten exactamente del mismo esqueleto base - Agent.bx, instructions.md, todas las carpetas de convención vacías, una carpeta tests/ lista para ejecutar, un .env y un .gitignore - y encima añaden una cantidad pequeña y concreta de contenido ya cableado. Ninguna necesita cambios en el validador: el contenido extra de cada una reutiliza una forma de configuración que ProjectValidator ya acepta, así que un proyecto creado con cualquier plantilla valida limpiamente por construcción.

minimal

La opción por defecto cuando se omite --template por completo. ES el esqueleto base descrito arriba - sin archivos extra. Úsala cuando partes de un agente en blanco y vas añadiendo convenciones tú mismo a medida que las necesitas.

webui-chat

Añade gateways/webui.bx, que expone la UI web de chat integrada en /chat:

// gateways/webui.bx
class {

	function configure() {
		return {
			exposes : "webui",
			path    : "/chat"
		};
	}

}

Después de bxAgents build && bxAgents serve, el agente está accesible en http://localhost:8080/chat - una página de chat estática real respaldada por un almacén de conversaciones generado sobre SQLite. De fábrica no se configura ningún apiKeyEnvVar/users, así que la página está abierta por defecto; consulta La UI web de chat para protegerla.

slack-bot

Añade gateways/slack.bx, un adaptador de canal Slack de tipo push (Socket Mode - un websocket persistente, sin necesidad de un webhook público):

// gateways/slack.bx
class {

	function configure() {
		return {
			type           : "slack",
			botTokenEnvVar : "SLACK_BOT_TOKEN",
			appTokenEnvVar : "SLACK_APP_TOKEN"
		};
	}

}

También añade al .env las líneas de ejemplo correspondientes:

## Slack gateway (gateways/slack.bx) - see https://api.slack.com/apps
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

Rellena ambos valores reales desde una app de Slack con Socket Mode activado antes de bxAgents serve - consulta Slack para los pasos de configuración de la app.

telegram-bot

Añade gateways/telegram.bx, un adaptador de canal Telegram de tipo push (long-poll mediante getUpdates):

// gateways/telegram.bx
class {

	function configure() {
		return {
			type           : "telegram",
			botTokenEnvVar : "TELEGRAM_BOT_TOKEN"
		};
	}

}

También añade al .env la línea de ejemplo correspondiente:

## Telegram gateway (gateways/telegram.bx) - from @BotFather
TELEGRAM_BOT_TOKEN=...

Consigue un token de @BotFather y colócalo antes de servir.

github-bot

Añade gateways/github.bx, un adaptador de canal GitHub de tipo push (dirigido por webhooks, con hilos de comentarios en issues/PR filtrados por @mention):

// gateways/github.bx
class {

	function configure() {
		return {
			type                : "github",
			tokenEnvVar         : "GITHUB_TOKEN",
			webhookSecretEnvVar : "GITHUB_WEBHOOK_SECRET",
			botNameEnvVar       : "GITHUB_BOT_NAME"
		};
	}

}

También añade al .env las líneas de ejemplo correspondientes:

## GitHub gateway (gateways/github.bx) - a PAT with repo/issues+PR read+write scope
GITHUB_TOKEN=...
GITHUB_WEBHOOK_SECRET=...
GITHUB_BOT_NAME=...

GITHUB_TOKEN necesita un PAT con permisos de lectura/escritura sobre repo + issues/PR; GITHUB_WEBHOOK_SECRET es el secreto de firma que hayas configurado en el webhook del repositorio; GITHUB_BOT_NAME es el nombre de la cuenta con la que responde el bot, usado para filtrar por @mention. Consulta GitHub para la configuración del webhook.

mcp-server

Añade un servidor de tools MCP de ejemplo, más una entrada de gateway que lo expone:

// mcp/exampleServer.bx
class {

	function configure() {
		return {
			description : "Example MCP tool server",
			version     : "1.0.0"
		};
	}

}

// gateways/mcpExpose.bx
class {

	function configure() {
		return {
			exposes : "mcp",
			path    : "/mcp",
			target  : "exampleServer"
		};
	}

}

target nombra la entrada mcp/* que se expone - aquí, el servidor de ejemplo de arriba. Después de build/serve, cualquier cliente que hable MCP puede conectarse en /mcp. Añade funciones reales anotadas con @AITool (o cualquier otro miembro exponible por MCP) a mcp/exampleServer.bx, o añade directamente más archivos mcp/*.bx, según mcp/.

scheduled

Añade un scheduler ColdBox real, escrito a mano, que llama al agente de forma periódica:

// schedules/Scheduler.bx
class extends="coldbox.system.web.tasks.ColdBoxScheduler" {

	function configure() {
		task( "example" )
			.call( () => getInstance( "my-agent" ).run( "Give me a status update" ) )
			.everyDayAt( "00:00" )
	}

}

(El argumento de getInstance(...) es siempre el propio name del agente creado, de modo que resuelve la clave de binding correcta de WireBox.) Esto es contenido real de schedules/, no un marcador de posición - edita configure() directamente para añadir o cambiar tareas usando el propio DSL de scheduler de ColdBox (everyMinute(), everyHourAt(), cron(...), etc.).

multi-agent

La única plantilla que cambia el propio Agent.bx raíz, en lugar de limitarse a añadir archivos a su lado. Declara dos subagentes mediante una sobrescritura de configure():

// Agent.bx
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
	}

	function configure() {
		return {
			subAgents : [ "researcher", "writer" ]
		};
	}

}

...y crea ambos como carpetas de subagente reales y funcionales:

subagents/
├── researcher/
│   ├── Agent.bx
│   └── instructions.md
└── writer/
    ├── Agent.bx
    └── instructions.md

El Agent.bx de cada subagente es una clase de agente completa y construible (siempre contra el proveedor mock - un subagente aquí es una demostración de la forma de la delegación, no un agente funcional de fábrica):

// subagents/researcher/Agent.bx
class extends="bxModules.bxai.models.runnables.AiAgent" {

	function init() {
		super.init(
			name        : "researcher",
			description : "Gathers facts on a topic. Does not write final prose - that's the writer's job.",
			model       : aiModel( provider: "mock", params: { model: "mock-model" } )
		)
		return this
	}

}

researcher reúne hechos; writer convierte los hallazgos en prosa final - un ejemplo mínimo de delegación entre dos roles. Consulta subagents/ para ver en qué se diferencia el array subAgents de configure() (nombres de carpeta a cablear) del argumento subAgents de super.init() (instancias de AiAgent ya construidas), y el ejemplo de equipo multiagente para un recorrido más completo.

Tomar un proyecto desde GitHub (--repo)

bxAgents new my-agent --repo=owner/repo-name
# o una URL completa:
bxAgents new my-agent --repo=https://github.com/owner/repo-name.git

En lugar de crear el andamiaje desde una plantilla integrada, --repo clona un repositorio existente y lo usa directamente como el nuevo proyecto. El clonado se hace con una dependencia JGit incluida (org.eclipse.jgit:org.eclipse.jgit, desde Maven Central) - no hace falta instalar ningún binario git ni tenerlo en el PATH; el cliente git viaja dentro del propio jar del módulo.

Qué hace que un repositorio sea una plantilla válida: un Agent.bx en la raíz del repositorio, igual que en cualquier proyecto creado con el andamiaje. Más allá de eso, no hay ningún manifiesto ni archivo marcador especial que añadir - cualquier proyecto BxAgents (tuyo, de un compañero, un ejemplo de examples/) ya es un origen --repo válido tal cual.

Qué ocurre al clonar, en orden:

1. La forma abreviada owner/repo-name se resuelve a https://github.com/owner/repo-name.git; un valor que ya contenga :// o empiece por git@ se usa tal cual (así que también funciona una URL HTTPS de un GitLab/Bitbucket/etc. autoalojado, no solo GitHub).
2. Se niega a ejecutarse si el directorio de destino ya existe y no está vacío - nunca se clona por encima de archivos existentes.
3. Clona en modo shallow (--depth=1 - solo el estado actual, sin historial) mediante el cloneRepository() de JGit.
4. Siempre elimina después la carpeta .git resultante, incondicionalmente - no hay ningún flag para conservarla. Es deliberado: el historial git y el remoto origin de un repositorio-plantilla no tienen ninguna razón legítima para sobrevivir dentro de un proyecto nuevo, y dejarlos ahí es una trampa real (el primer git init/commit/push de tu proyecto podría interactuar con el repositorio upstream de la plantilla en vez de con el tuyo). Si de verdad quieres el historial git del repositorio origen, clónalo a mano con git clone en lugar de usar bxAgents new --repo.
5. Verifica que existe Agent.bx en la raíz clonada - si no, toda la operación falla con un error claro que nombra lo que falta, en lugar de dejar atrás un directorio a medias que no es un proyecto BxAgents.

--model, --name y --description no son obligatorios ni se usan con --repo - el proyecto clonado ya define su propio Agent.bx (y por tanto su propio nombre/modelo). Pasar --name/--description de todos modos produce un aviso en la salida en vez de un error, y por lo demás se ignora. El paso automático de box install del tests/ creado (y --skipInstall) tampoco aplican aquí - la carpeta tests/ del proyecto clonado, si la tiene, se deja exactamente como se clonó.

Tomar un proyecto desde ForgeBox (--forgebox)

bxAgents new my-agent --forgebox=some-package-slug

Instala un paquete de ForgeBox - el registro de paquetes de CommandBox, que puede alojar la plantilla de una aplicación o proyecto completos, no solo una librería - y lo usa como el nuevo proyecto. Esto habla directamente con la propia API REST pública de ForgeBox (https://www.forgebox.io/api/v1), usando el soporte nativo bx:http/http() de BoxLang - no hace falta la CLI box.

Qué hace que una entrada de ForgeBox sea una plantilla válida: un Agent.bx en la raíz de su archivo publicado (o anidado exactamente una carpeta más adentro - ver la nota sobre desanidado más abajo). ForgeBox tiene un tipo de entrada bxagents dedicado exactamente a esto ("BxAgents" en la interfaz de ForgeBox) - navegarlo es la forma más rápida de encontrar un punto de partida - pero bxAgents new --forgebox en sí no filtra ni se fija en el type declarado de una entrada al instalar; solo le importa si el archivo descargado, una vez extraído, contiene un Agent.bx.

Qué ocurre al instalar, en orden:

1. Se niega a ejecutarse si el directorio de destino ya existe y no está vacío.
2. GET /entry/<slug> busca el paquete. Un slug que no existe falla de forma clara e inmediata - no se intenta ninguna descarga.
3. Resuelve la URL de descarga de la versión actual desde el propio latestVersion.downloadURL de la entrada (recurriendo a la entrada más reciente de su array versions si por algún motivo falta).
4. Descarga el archivo y lo extrae con la propia BIF extract() integrada de BoxLang (soporte zip - sin ningún código de descompresión hecho a medida).
5. Desanida un nivel automáticamente, si lo hay: muchos archivos de ForgeBox (siguiendo lo típico de una exportación zip de GitHub) envuelven todo su contenido en una única carpeta de primer nivel. Si la extracción produce exactamente una entrada de primer nivel y es un directorio, su contenido se sube un nivel para que el propio directorio de destino acabe siendo la raíz del proyecto.
6. Verifica que existe Agent.bx en la raíz (posiblemente ya desanidada) - si no, toda la operación falla, ya que un slug de ForgeBox podría ser perfectamente una librería sin relación en vez de una plantilla de proyecto.

Igual que con --repo: --model/--name/--description no son obligatorios (se avisa y se ignoran si se pasan de todos modos - el proyecto instalado define los suyos), y el paso automático de box install de tests/ y --skipInstall no aplican.

Publicar tu propia plantilla

Una plantilla BxAgents - tanto si la compartes vía GitHub, ForgeBox, o ambos - es simplemente un proyecto BxAgents corriente (un Agent.bx en su raíz, más las convenciones que use) con los detalles concretos rellenados para que otra persona los copie y adapte, en vez de dejados como marcadores de posición para ti.

1. Construye el proyecto

Parte de cualquiera de las 8 plantillas integradas de arriba (o de cero) y moldéalo hasta convertirlo en aquello de lo que quieres que la gente parta:

bxAgents new my-template --model=openai/gpt-5 --template=<el punto de partida más cercano>

Merece la pena hacer un par de cosas de forma deliberada, ya que otra persona hará bxAgents new --repo=.../--forgebox=... sobre esto y esperará que funcione sin más:

• Mantén Agent.bx genérico y construible de fábrica. No fijes una clave de API real ni apuntes por defecto a un modelo solo de pago - la sobrescritura mock/mock-model de test() (ya incluida en el andamiaje) hace que bxAgents test siga funcionando sin ninguna configuración aunque el modelo real de init() necesite una clave que solo tienes tú.
• Incluye un instructions.md real que describa el propósito verdadero del agente, no el marcador genérico "You are a helpful AI agent" que new crea por defecto.
• Documenta las variables de entorno necesarias en .env como líneas de ejemplo comentadas (SLACK_BOT_TOKEN=xoxb-..., etc.), exactamente como hacen arriba las plantillas slack-bot/telegram-bot/github-bot - es lo primero que alguien lee después de clonar.
• Verifícalo en frío, igual que lo recibiría un desconocido: rm -rf .build dist, y después bxAgents build && bxAgents test (y bxAgents doctor para detectar cualquier cosa relacionada con el entorno o las dependencias) desde un checkout completamente nuevo.
• Nunca hagas commit de .build/, dist/, ni de un .env real - el .gitignore incluido ya cubre los tres; consérvalo.

2a. Publícalo en GitHub

No hace falta nada específico de BxAgents - sube el proyecto a un repositorio público de GitHub con Agent.bx en la raíz (o sube un subárbol; --repo solo desanida la convención de anidado único propia de ForgeBox, no disposiciones arbitrarias de repositorio, así que mantén Agent.bx en la raíz real del repositorio). Cualquiera puede entonces ejecutar:

bxAgents new my-agent --repo=your-org/your-template-repo

Una sección breve de "Getting Started" en el propio README.md del repositorio (qué variables de entorno definir, a qué modelo apuntar) ayuda muchísimo, ya que --repo no lee ni muestra nada del README - es puramente para la persona que lo clona.

2b. Publícalo en ForgeBox

Los paquetes de ForgeBox se describen con un box.json en la raíz del proyecto - el mismo archivo que usa el sistema de paquetes de CommandBox en todo lo demás. Como mínimo:

{
	"name": "My BxAgents Template",
	"slug": "my-bxagents-template",
	"version": "1.0.0",
	"type": "bxagents",
	"shortDescription": "A short description of what this agent template does",
	"private": false
}

• slug es el nombre único con el que la gente instala (--forgebox=my-bxagents-template) - es también lo que busca getEntry(), así que elige uno con el que estés a gusto de por vida.
• type debería ser bxagents - el tipo de entrada dedicado de ForgeBox para proyectos/plantillas BxAgents (ejecuta box forgebox types para verlo junto al resto de tipos). bxAgents new --forgebox nunca inspecciona type al instalar, pero declararlo correctamente es lo que hace que tu plantilla aparezca en la categoría "BxAgents" de ForgeBox en lugar de en una genérica, de modo que la gente pueda encontrarla navegando. Añade también keywords descriptivas (por ejemplo "boxlang", "ai-agent"), ya que es lo que usa la búsqueda de texto completo.
• version debería incrementarse (box bump --patch/--minor/--major, desde dentro de la carpeta de la plantilla) cada vez que publiques un cambio - bxAgents new --forgebox instala siempre lo que resuelva latestVersion en ese momento.

Después, desde dentro del proyecto:

box forgebox register   # una vez, si aún no tienes cuenta en ForgeBox
box publish

publish lee por convención los archivos readme/instructions/changelog de la carpeta y los publica como la descripción, las notas de instalación y el changelog de la entrada - merece la pena tener un README.md real por la misma razón que en el camino de GitHub. Una vez publicado, cualquiera puede ejecutar:

bxAgents new my-agent --forgebox=my-bxagents-template