Agent.bx

Die eine erforderliche Datei - eine Klasse, die bx-ais eigenes AiAgent erweitert, sodass sie DER Agent IST.

Agent.bx

Agent.bx ist die einzige erforderliche Datei in einem BX-Agents-Projekt. Sie erweitert bx-ais eigenes AiAgent, sie ist also der Agent - der Build instanziiert sie, statt eine aus einer Konfigurationsstruktur neu aufzubauen, sodass das, was geschrieben wird, auch läuft. Erben und hinzufügen, was gebraucht wird: private Hilfsmethoden, überschriebene Methoden, im Code registrierte Tools. Weil es sich um eine echte Klasse statt um einen struct-zurückgebenden Deskriptor handelt, kann eine IDE sie wie jede andere BoxLang-Klasse introspizieren - Sprung zur Definition, Autovervollständigung auf geerbten Methoden, alles.

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
	}

}

bxAgents new erzeugt genau diese Form als Gerüst. instructions.md ist optional - instructions direkt in super.init() setzen, oder die Datei neben Agent.bx ablegen und sie vom Build einbinden lassen (siehe Tabelle unten).

Was der Build über die Klasse legt

Die Regel: eine explizit deklarierte Konvention gewinnt; ansonsten hat die Klasse das letzte Wort.

Ein Agent, der alles in seiner eigenen init() setzt, bekommt also nichts aufgezwungen, während einer, der nur das Minimum setzt, trotzdem die Konventionen übernimmt, für die er nichts erklärt hat. Alles Folgende ist optional - eine configure() deklarieren, die einen dieser Schlüssel zurückgibt, um zu überschreiben, was die Klasse selbst gesetzt hat, oder den passenden Konventionsordner instructions.md/tools//subagents/:

Die Klasse wird in die generierte App nach agent/classes/ kopiert und dort über ihren eigenen absoluten Dateipfad instanziiert (nie eine relative Lookup, die von einer registrierten Zuordnung abhängen würde), genau wie tools/, skills/ und mcp/ kopiert werden - sodass eine paketierte .bxa sie mitführt, und chat/invoke/serve sie alle auf dieselbe Weise instanziieren, egal ob ein echter ColdBox-Container bootet oder nicht.

configure() (optional) - überschreibt, was die Klasse gesetzt hat

Eine configure()-Methode ist vollständig optional. Sie nur deklarieren, um bestimmte Felder von außerhalb der Klasse zu überschreiben - nützlich, um deploymentspezifische Werte (z. B. ein anderes Modell pro Umgebung) aus dem Klassenkörper selbst herauszuhalten:

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",
				{ url : "https://other.com/mcp", name : "other" }
			]
		};
	}

}

The model slug

model ist BX Agents' eigene Konvention - bx-ai selbst nimmt provider und model als zwei separate Argumente an aiModel(). BX Agents teilt den Slug nur am ersten /, sodass ein Provider, der selbst einen Schrägstrich enthält (wie OpenRouters openrouter/anthropic/claude-x), trotzdem korrekt geparst wird:

Hat model überhaupt keinen /, muss es entweder ein bekannter Core-Provider-Name sein oder zum Namen eines models/-Eintrags passen - die Validierung lehnt alles andere ab. Die erkannten Core-Provider sind: bedrock, claude, cohere, deepseek, docker, elevenlabs, gemini, grok, groq, huggingface, minimax, mistral, mock, ollama, openai, openai-compatible, openrouter, perplexity, voyage (mit bx-ais eigenem CORE_PROVIDERS synchron gehalten). mock ist ein echter Provider, nützlich für Tests und CI - er macht nie einen Netzwerkaufruf.

Diese Slug-Aufteilungskonvention durchläuft ein per configure() deklarierter model-String - super.init()s eigenes model-Argument nimmt hingegen direkt eine echte AiModel-Instanz (aiModel( provider: "...", params: { model: "..." } )), da die Klasse bereits bx-ais eigene API spricht.

Umgebungs-Overrides

Agent.bx kann eine nach einer Umgebung benannte Methode deklarieren (z. B. production(), development(), oder ein beliebiger eigener Name), die eine Struktur von Overrides zurückgibt - das funktioniert unabhängig davon, ob die Klasse auch eine configure() deklariert:

class extends="bxModules.bxai.models.runnables.AiAgent" {

	function init() {
		super.init(
			name        : "override-agent",
			description : "An agent with an environment override",
			model       : aiModel( provider: "openai", params: { model: "gpt-5" } )
		)
		return this
	}

	function production() {
		return {
			model : "openai/gpt-5-mini"
		};
	}

}

Die aktive Umgebung wird nach dieser Rangfolge aufgelöst (höchste gewinnt):

1. --environment-CLI-Flag (bxAgents build --environment=production)
2. Umgebungsvariable BX_AGENTS_ENV
3. "development" (Standard)

Das ist eine reine Build-Zeit-Entscheidung, unabhängig von ColdBoxs eigener Laufzeit-Umgebungserkennung (die generierte App liest getSetting("environment") selbst, gemäß ColdBoxs environments-Konvention) - diese Rangfolge entscheidet nur, welche environment()-Override-Methode an Agent.bx, und welche boxlang-{env}.json/miniserver-{env}.json-Dateien, die Build-Pipeline anwendet.

Existiert keine zur aktiven Umgebung passende Methode, wird kein Override angewendet.

Merge-Semantik

Die vollständige Auflösungsreihenfolge (niedrigste zu höchste Priorität) ist:

1. configure() (optional)
2. die passende Umgebungs-Override-Methode, falls vorhanden
3. boxlang.json
4. boxlang-{environment}.json
5. miniserver.json
6. miniserver-{environment}.json

Struct-Schlüssel werden rekursiv gemergt - eine verschachtelte Struktur aus einer höher priorisierten Quelle überschreibt nur die Schlüssel, die sie tatsächlich setzt, und lässt Geschwisterschlüssel aus einer niedriger priorisierten Quelle unangetastet. Arrays und alle skalaren Werte werden vollständig ersetzt, nie angehängt oder verkettet.

boxlang.json/boxlang-{env}.json/miniserver.json/miniserver-{env}.json sind allesamt optionale JSON-Dateien im Projekt-Root, nützlich für Konfiguration, die sich leichter als Daten denn als BoxLang-Code ausdrücken lässt (z. B. Modell-Standardwerte):

// boxlang.json
{
	"modelDefaults": { "temperature": 0.7, "maxTokens": 1000 }
}

// boxlang-production.json
{
	"modelDefaults": { "temperature": 0.2 }
}

Ein Build mit --environment=production ergibt hier modelDefaults: { temperature: 0.2, maxTokens: 1000 } - das rekursive Merge behielt maxTokens aus der Basisdatei, da boxlang-production.json es nie erwähnte.