BX Agents

Einen Agenten in Ordnern und Dateien beschreiben; daraus eine echte ColdBox-Anwendung bauen.

overview
BX Agents - Build. Constrain. Orchestrate. A conventions-based agent framework for BoxLang. Conventions first: convention over configuration for faster development. Pluggable and extensible: swap models, tools, memory and more with ease. Powerful agents: create agents that reason, act, and collaborate effectively. Production ready: built for performance, reliability, and real-world applications. The agent framework native to BoxLang.
Loslegen Auf GitHub ansehen

BX Agents ist ein konventionsbasiertes KI-Agenten-Framework für BoxLang, aufgebaut auf ColdBox und BX AI. Ein Agent wird mit Dateien und Ordnern beschrieben - nicht über die API-Oberfläche eines Frameworks - und bxAgents build setzt daraus eine echte, lauffähige ColdBox-Anwendung zusammen.

Zur Build-Zeit zusammengesetzt

Discovery, Validierung und Codegenerierung laufen einmal, nicht bei jedem Start. Was danach läuft, ist eine ganz normale ColdBox-App.

Ordner sind die API

Agent.bx und instructions.md sind die einzigen erforderlichen Dateien. Jeder andere Konventionsordner ist optional und beeinflusst die Ausgabe nur, wenn er existiert.

Tools und Skills

Eine mit @AITool annotierte Funktion in tools/ ablegen, oder einen SKILL.md-Ordner in skills/ - beides wird automatisch erkannt und eingebunden.

Agenten, so weit das Auge reicht

subagents/ verschachtelt genau denselben Konventionsbaum, sodass ein Team von Spezialisten nur aus weiteren Ordnern besteht - von den Blättern aus gebaut.

Zwölf Gateway-Typen

Telegram, Slack, Discord, E-Mail, WhatsApp, Teams, Twilio, GitHub und Signal, plus http, cli und mock.

Eine generierte Web-Chat-Oberfläche

In Agent.bx anfordern, und der Build erzeugt ein themenfähiges, streamendes Chat-Frontend mit Sitzungsverlauf.

In vier Schritten einen Agenten bauen

1
Installieren
install-bx-module bx-ai bx-agents

box install bx-ai,bx-agents
2
Gerüst erstellen
bxAgents new my-agent --model=openai/gpt-5

Anschließend instructions.md bearbeiten und die benötigten Konventionsordner ergänzen.

3
Bauen
bxAgents build

Discovery, Validierung, Manifest, Codegenerierung - nach .build/app/.

4
Damit sprechen
bxAgents chat
# oder über HTTP bereitstellen:
bxAgents serve --port=8080

Was build tatsächlich erzeugt

Der eigene Konventionsbaum, und die einfache ColdBox-Anwendung, in die build ihn verwandelt.

your-agent/
├── Agent.bx           # name, model, description
├── instructions.md    # the system prompt
├── tools/             # @AITool functions
├── skills/            # SKILL.md capabilities
├── subagents/         # nested agent trees
├── models/            # named model configs
├── gateways/          # HTTP/MCP/chat exposure
├── schedules/         # a real ColdBox scheduler
├── mcp/               # MCP servers you host
├── interceptors/      # lifecycle hooks
└── modules/           # module dependencies

.build/app/
├── Application.bx
├── config/
│   ├── ColdBox.bx
│   ├── WireBox.bx
│   ├── Router.bx
│   └── Scheduler.bx
├── agent/
│   └── GeneratedAgentFactory.bx
├── tools/  skills/  mcp/
├── handlers/  interceptors/
└── index.bxm
Warum zur Build-Zeit zusammensetzen statt zur Request-Zeit?

Die meisten Agenten-Frameworks verdrahten Tools, Skills, Routen und Zeitpläne zur Request-Zeit miteinander, bei jedem Start. BX Agents macht das Gegenteil: bxAgents build führt Discovery, Validierung und Codegenerierung genau einmal aus und erzeugt dabei eine einfache ColdBox-Anwendung unter .build/app/.

Diese zu starten - über bxAgents serve, einen echten boxlang-miniserver- Prozess, oder eine portable .bxa, überall dort eingesetzt, wo BoxLang läuft - ist danach nur noch das Starten einer gewöhnlichen App. Kein Scannen von Konventionen, kein dynamisches Durchsuchen von Dateien, keine Build-Zeit-Arbeit, die in den Request-Pfad verschoben wird.

Mit einer Datei anfangen

Nur Agent.bx ist erforderlich. instructions.md ist optional - Instruktionen direkt in der Klasse setzen, oder die Datei ablegen und sie vom Build einbinden lassen. Jeder andere Ordner beeinflusst die generierte Ausgabe nur, wenn er existiert und Inhalt hat - Konventionen werden also genau dann hinzugefügt, wenn sie tatsächlich gebraucht werden.

Agent.bx IST der Agent

Agent.bx erweitert direkt bx-ais eigenes AiAgent - der Build instanziiert die eigene Klasse, statt eine aus einer Konfigurationsstruktur neu aufzubauen, sodass das, was geschrieben wird, auch läuft, und eine IDE sie wie jede andere Klasse introspizieren kann. Siehe Agent.bx.

Von überall erreichbar

Chat-Plattformen

Neun Push-Style-Gateways - Telegram, Slack, Discord, E-Mail, WhatsApp Cloud, Teams, Twilio, GitHub und Signal - koordiniert von einer Session mit queue-/steer-/interrupt-Richtlinien.

HTTP und MCP

Den Agenten über HTTP-Routen bereitstellen, oder lokale MCP-Server aus mcp/ hosten, damit andere Clients die eigenen Tools aufrufen können.

Ausliefern

Eine portable .bxa paketieren und mit local, ssh, docker, digitalocean, ftp oder sftp ausliefern - Secrets bleiben Umgebungsvariablen, nie Build-Artefakte.

Wie es weitergeht

Installation

BoxLang, BX AI und BX Agents installieren.

Schnelleinstieg

Den ersten Agenten anlegen, bauen und mit ihm chatten.

Konventionen

Eine Seite pro Konventionsordner, von Anfang bis Ende.

Die Build-Pipeline

Genau das, was build tut, in der richtigen Reihenfolge.

CLI-Referenz

Jedes Verb und seine Flags.

Deployment & Secrets

Eine .bxa paketieren und sicher ausliefern.

Jeder Konventionsordner hat außerdem ein funktionierendes, baubares Beispielprojekt unter examples/.

Warning

BX Agents befindet sich in aktiver Entwicklung. Bekannte Einschränkungen hält die ehrlichen Lücken fest - was gegen eine echte laufende App getestet ist, was noch nur gegen BX AIs "mock"-Provider läuft, und eine echte Eigenheit im vorgelagerten ColdBox, auf die dieses Projekt gestoßen ist und die es umschifft hat.

Edit this page Download Markdown Last updated Aug 21, 2026, 6:33:28 PM