Agent.yaml
La forma predeterminada de definir un agente - ajustes sencillos en un archivo YAML, sin código.
En esta página
Agent.yaml
Agent.yaml es la forma predeterminada de definir un agente. Es un archivo YAML sencillo - un nombre, un modelo y cualquiera de los ajustes opcionales de abajo - y el build lo convierte en un agente en ejecución. La mayorÃa de los agentes no necesitan más que este archivo y un instructions.md a su lado.
name: support
description: Answers customer questions about orders
model: openai/gpt-5
environments:
test:
model: mock/mock-model
bxAgents new genera el andamiaje exactamente con esta forma. Cuando la definición necesita código real (hooks, instrucciones dinámicas, tools registradas en código), usa la opción avanzada: un Agent.bx basado en clase, que se genera con bxAgents new --class.
Una carpeta contiene una definición de agente. Un Agent.yaml (o Agent.yml) junto con un Agent.bx en la misma carpeta es un error - dos definiciones de un mismo agente dejarÃan ambiguo qué ajustes ganan - y build falla y nombra ambos archivos para que conserves uno. Esto aplica a la raÃz del proyecto y a cada carpeta de subagente, y un proyecto puede mezclar los dos: una raÃz YAML con un subagente basado en clase, o al revés.
Ajustes
| Clave | Tipo | Notas |
|---|---|---|
name | string | También se convierte en la clave de binding de config/WireBox.bx de este agente en tiempo de build, asà que debe ser única en todo el proyecto (raÃz + cada subagente). |
model | string | Un slug provider/model, un nombre de proveedor sin más, o el nombre de una entrada de models/. Ver The model slug. |
description | string | Opcional. |
instructions | string | Instrucciones en lÃnea, opcionales. Ver Instrucciones. |
subAgents | lista de strings | Nombres de carpetas hermanas bajo el subagents/ del proyecto raÃz. Ver subagents/. |
mcpServers | lista | Servidores MCP remotos - cada entrada es un string de URL o { url, name }. Ver mcp/. |
security | mapa | Se reenvÃa tal cual a los ajustes del módulo bxai de la app generada; el SecurityDirector de bx-ai lo convierte en middleware de guardarraÃles. |
memory | string o mapa | La memoria de conversación del agente. Un string suelto es el tipo (cache); un mapa es { type, ...config } y se pasa a aiMemory(). |
checkpointer | mapa | { type: cache\|file\|jdbc, ...config }. Por defecto { type: cache } si se omite. |
gatewaySession | mapa | { policy, maxQueueDepth }, ambos opcionales. Ver Agent.bx para los valores; son idénticos. |
agentApi | mapa | { enabled, tokenEnvVar }, ambos opcionales. Ver La ruta de agente siempre activa. |
environments | mapa | Sobreescrituras por entorno. Ver Entornos. |
Son los mismos ajustes que devuelve el configure() de un Agent.bx, asà que todo el comportamiento documentado para ellos aplica sin cambios.
Una clave desconocida es un error, y el mensaje lista las válidas. Un error de tipeo como modle: de otro modo no harÃa nada, en silencio. Los ajustes que llegan en versiones posteriores (por ejemplo tools) se rechazan igual hasta que existan, en lugar de ignorarse en silencio. Todo lo de forma libre pertenece a un Agent.bx.
Un valor del tipo equivocado (un texto donde va una lista, por ejemplo) y un valor vacÃo (model: sin nada detrás) también son errores.
Instrucciones
Las instrucciones del agente son su system prompt. Ponlas en un instructions.md junto a Agent.yaml, la opción habitual porque el archivo es Markdown sencillo y fácil de editar:
my-agent/
├── Agent.yaml
└── instructions.md
Para un prompt corto puedes escribirlas en lÃnea:
name: greeter
model: openai/gpt-5
instructions: |
You greet people by name.
Keep it to one sentence.
Si existen ambas, gana instructions.md - el archivo es la elección más deliberada, asà que una lÃnea instructions: suelta no puede sobreescribirlo. Si no existe ninguna, build falla y lo dice.
Entornos
environments contiene sobreescrituras indexadas por nombre de entorno. Es la forma YAML de los métodos de sobreescritura por entorno (production()) que puede declarar un Agent.bx:
name: support
model: openai/gpt-5
environments:
production:
model: openai/gpt-5-mini
staging:
description: Staging copy
El entorno activo se elige con esta precedencia, de mayor a menor:
- la bandera de CLI
--environment(bxAgents build --environment=production) - la variable de entorno
BX_AGENTS_ENV development
Solo se aplica el bloque del entorno activo, encima de los ajustes de nivel superior; las claves que no menciona se dejan como están. Cada bloque acepta las mismas claves que el nivel superior, salvo el propio environments.
bxAgents test hace el build contra el entorno test, y por eso un proyecto generado lleva un bloque test que apunta al proveedor mock: sus tests no necesitan clave de API ni red.
Un Agent.yaml no puede calcular su entorno. El método detectEnvironment() descrito en Overrides de entorno necesita código, asà que un proyecto que lo necesite usa un Agent.bx.
Las sobreescrituras se fusionan luego con boxlang.json, boxlang-{environment}.json, miniserver.json y miniserver-{environment}.json exactamente como se describe en Semántica de fusión.
Requisitos
Leer YAML necesita el módulo bx-yaml, 1.1.0 o posterior. BxAgents lo incluye, asà que no hay nada que instalar. Las etiquetas YAML globales (como !!java.io.File) se rechazan, de modo que el Agent.yaml de un proyecto clonado no puede hacer que el build instancie clases Java arbitrarias.
¿YAML o Agent.bx?
| Usa | Cuándo |
|---|---|
Agent.yaml | El agente es configuración: un nombre, un modelo, instrucciones, memoria, subagentes. Es casi todo agente. |
Agent.bx | La definición misma necesita código: hooks, instrucciones dinámicas, tools registradas en código, un método sobreescrito o detectEnvironment(). |
Puedes empezar con YAML y cambiar después: crea el Agent.bx, pasa los ajustes y borra el Agent.yaml.