agent.yaml Referenz

agent.yaml ist das Herzstück jedes Agenten-Pakets. Es teilt dem Selu-Orchestrator mit, wer der Agent ist, wie er geroutet werden soll und welche Capabilities er verwenden kann.

Minimales Beispiel

name: hello-world
version: 0.1.0
display_name: Hello World
description: Ein einfacher Begrüßungsagent.
author: dein-benutzername
license: MIT
model:
  default: anthropic/claude-sonnet

Vollständiges Schema

Felder auf oberster Ebene

Feld	Typ	Erforderlich	Beschreibung
name	string	Ja	Eindeutige Kennung. Kleinbuchstaben, Bindestriche erlaubt. Muss im Marketplace eindeutig sein.
version	string	Ja	Semantische Versionsnummer (MAJOR.MINOR.PATCH).
display_name	string	Ja	Menschenlesbarer Name, der in der UI und im Marketplace angezeigt wird.
description	string	Ja	Einzeilige Zusammenfassung (max. 160 Zeichen).
author	string	Ja	Marketplace-Benutzername oder Organisation.
license	string	Ja	SPDX-Lizenzkennung (z.B. MIT, Apache-2.0).
model	object	Ja	LLM-Konfiguration.
routing	object	Nein	Wie der Orchestrator Nachrichten an diesen Agenten weiterleitet.
session	object	Nein	Session-Management und Isolationseinstellungen.
capabilities	list	Nein	Capabilities, die dieser Agent verwenden kann.
memory	object	Nein	Session- und Langzeit-Speichereinstellungen.
events	object	Nein	Event-Abonnements und Ausgaberegeln.
tags	list[string]	Nein	Marketplace-Discovery-Tags.

model

model:
  default: anthropic/claude-sonnet
  fallback: openai/gpt-4o
  temperature: 0.7
  max_tokens: 4096

Feld	Typ	Erforderlich	Beschreibung
default	string	Ja	Anbieter/Modell-Kennung. Der konfigurierte Anbieter des Benutzers hat Vorrang.
fallback	string	Nein	Wird verwendet, wenn das Standard-Modell nicht verfügbar ist.
temperature	float	Nein	Sampling-Temperatur (0.0–2.0). Standard 0.7.
max_tokens	int	Nein	Maximale Antwort-Tokens. Standard 4096.

session

session:
  trigger: mention              # mention | always | auto
  idle_timeout_minutes: 30     # Session-Bereinigungstimeout
  isolation: per_thread        # shared | per_thread

Feld	Typ	Erforderlich	Beschreibung
trigger	string	Nein	Wann dieser Agent aktiviert wird. Standard mention.
idle_timeout_minutes	int	Nein	Minuten bis inaktive Sessions bereinigt werden. Standard 30.
isolation	string	Nein	Session-Isolationsmodus. Standard shared.

Session-Isolationsmodi

• shared (Standard) — Verwendet aktive Sessions für denselben Benutzer+Agent threadübergreifend wieder. Capability-Container und Arbeitsbereiche werden zwischen Gesprächen geteilt.
• per_thread — Erzwingt dedizierte Sessions pro Thread. Jeder Gesprächs-Thread erhält seine eigenen Capability-Container und isolierte Arbeitsbereiche.

:::tip Wann per-Thread-Isolation verwenden Verwende isolation: per_thread für zustandsabhängige Agenten wie Programmier-Assistenten oder Arbeitsbereich-Manager, wo du Thread-übergreifende Zustandskollisionen verhindern möchtest. Dies stellt sicher, dass Arbeit in einem Gespräch nicht mit einem anderen interferiert. :::

:::caution Ressourcenverbrauch Per-Thread-Isolation verbraucht mehr Speicher und CPU, da jeder Thread separate Capability-Container ausführt. Verwende es nur für Agenten, die wirklich Arbeitsbereich-Isolation benötigen. :::

capabilities

Capabilities werden per Referenz aufgelistet. Sie können auf ein lokales Verzeichnis oder ein Remote-Docker-Image verweisen.

Lokale Capability

capabilities:
  - name: weather
    path: ./capabilities/weather

Remote-Image

capabilities:
  - name: weather
    image: ghcr.io/selu-bot/cap-weather:1.2.0

Feld	Typ	Erforderlich	Beschreibung
name	string	Ja	Kennung, die in Tool-Aufrufen verwendet wird.
path	string	Nein	Relativer Pfad zu einem lokalen Capability-Verzeichnis.
image	string	Nein	Docker-Image-URI. Wird verwendet, wenn path nicht gesetzt ist.
parameters	object	Nein	Statische Schlüssel-Wert-Konfiguration, die beim Start an die Capability übergeben wird.

routing

routing:
  mode: inline          # inline | dedicated
  triggers:
    - mention: "@weather"
    - intent: weather_query
  priority: 10

Siehe Routing & Sessions für vollständige Details.

memory

memory:
  session_ttl: 3600       # Sekunden
  max_history: 50         # Nachrichten
  long_term: true         # Vektor-basiertes Langzeitgedächtnis aktivieren

Beispiel: Zustandsabhängiger Programmier-Agent

Für Agenten, die persistente Arbeitsbereiche oder Dateisysteme verwalten, verwende Per-Thread-Isolation:

name: coding-assistant
display_name: Programmier-Assistent
description: KI-Pair-Programmer mit persistentem Arbeitsbereich
author: selu-team
license: MIT
model:
  default: anthropic/claude-sonnet
session:
  isolation: per_thread
  idle_timeout_minutes: 60
capabilities:
  - name: workspace
    path: ./capabilities/workspace

Dies stellt sicher, dass jedes Programmier-Gespräch sein eigenes isoliertes Dateisystem und Git-Repository erhält, wodurch verhindert wird, dass ein Projekt mit einem anderen interferiert.

Validierung

Führe selu validate in deinem Agent-Verzeichnis aus, um deine agent.yaml vor der Veröffentlichung gegen das Schema zu prüfen.

selu validate ./my-agent