Schnelleinstieg

Der vollständige Lebenszyklus eines Projekts: Gerüst erstellen, bearbeiten, bauen, ausführen.

Schnelleinstieg

Diese Seite führt durch den vollständigen Lebenszyklus eines BX-Agents-Projekts: Gerüst erstellen, bearbeiten, bauen, ausführen.

1. Ein Projekt anlegen

bxAgents new my-agent --model=openai/gpt-5

--model ist erforderlich (ein provider/model-Slug - siehe Agent.bx dafür, wie er geparst wird). --name und --description sind optional; --name fällt standardmäßig auf den eigenen Namen des Zielverzeichnisses zurück.

Das erzeugt:

my-agent/
├── Agent.bx
├── instructions.md
├── tools/
├── skills/
├── subagents/
├── models/
├── gateways/
├── schedules/
├── mcp/
├── interceptors/
├── modules/
└── tests/
    ├── box.json
    └── specs/
        └── AgentSpec.bx

Agent.bx sieht so aus:

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
	}

}

Es extends bx-ais eigenes AiAgent, es ist also der Agent - erben und direkt an der Klasse hinzufügen, was der Agent auch braucht. Siehe Agent.bx.

Jeder Konventionsordner wird leer angelegt - Dateien zu denen hinzufügen, die der eigene Agent tatsächlich braucht, und den Rest löschen (oder einfach ignorieren).

2. Bearbeiten

instructions.md öffnen und den Systemprompt des Agenten schreiben. Ein Tool hinzufügen:

// tools/Greeter.bx
class {

	@AITool( "Say hello to someone by name." )
	function sayHello( name ) {
		return "Hello, " & arguments.name & "!";
	}

}

Siehe den Abschnitt Konventionen für jeden anderen Ordner (skills/, subagents/, gateways/, schedules/, mcp/, interceptors/, models/, modules/).

3. Testen

cd tests && box install && cd ..   # einmalig, um testbox/ zu holen
bxAgents test

Die generierte tests/specs/AgentSpec.bx besteht sofort - sie baut den Agenten gegen den mock-Provider (kein API-Schlüssel oder Netzwerk nötig) und prüft eine skriptierte Antwort. Siehe tests/ für mockResponses() und die eigenen Specs zur Verfügung stehenden Custom Matcher (toHaveCalledTool usw.).

4. Bauen

bxAgents build

Führt die vollständige Build-Pipeline aus - Konfigurationsauflösung, Discovery, Validierung, Codegenerierung, Manifest-Normalisierung - und schreibt eine echte ColdBox-Anwendung nach .build/app/, plus .build/manifest.json. bxAgents build --environment=production ausführen, um gegen einen Umgebungs-Override von Agent.bx zu bauen (siehe Agent.bx).

Scheitert das Projekt an der Validierung (doppelte Tool-Namen, ein fehlerhafter Cron-Ausdruck, ein unbekannter Modell-Provider, ...), schlägt build mit jedem gesammelten Fehler fehl - nicht nur mit dem ersten.

5. Ausführen

Zwei Wege, mit dem gebauten Agenten zu sprechen - beide laden dieselbe GeneratedAgentFactory.bx und bauen denselben Agentenbaum, laufen also nie auseinander:

Interaktiv, vom Terminal aus:

bxAgents chat

Über HTTP, über einen echten boxlang-miniserver-Prozess:

bxAgents serve --port=8080

Hat das Projekt einen gateways/*-Eintrag mit { exposes: "agent", path: "/api/chat" }, ist der Agent jetzt unter POST http://localhost:8080/api/chat/invoke erreichbar (und /stream, /batch, /info - siehe gateways/).

6. Inspizieren, paketieren, ausliefern

bxAgents inspect              # .build/manifest.json hübsch ausgeben
bxAgents package --version=1.0.0   # schreibt dist/my-agent-1.0.0.bxa + .sha256
bxAgents deploy --destination=/path/to/somewhere   # kopiert die neueste .bxa dorthin

Siehe Das Manifest und Deployment & Secrets.

7. Aufräumen

bxAgents clean

Entfernt nur .build/ und dist/ - eigene Quell-Konventionen (Agent.bx, tools/ usw.) werden nie angefasst.

Nächste Schritte

• Jeden Konventionsordner unter Konventionen durchgehen.
• Die funktionierenden Beispielprojekte unter examples/ ansehen.
• Die Flags jedes Verbs in der CLI-Referenz nachschlagen.