manifest.yaml-Referenz

manifest.yaml beschreibt eine einzelne Capability für den Selu-Orchestrator. Die Datei liegt im Wurzelverzeichnis eines Capability-Ordners neben dem Dockerfile und der optionalen prompt.md.

Minimales Beispiel

manifest.yaml

id: weather-lookup
class: tool
image: ghcr.io/example/weather-lookup:1.0.0

Beispiel mit statischen Tools

manifest.yaml

id: weather-lookup
class: tool
image: ghcr.io/example/weather-lookup:1.0.0

tools:
  - name: get_current_weather
    description: Aktuelle Wetterbedingungen für einen Standort abrufen.
    input_schema:
      type: object
      properties:
        location:
          type: string
          description: Stadtname oder Koordinaten
        units:
          type: string
          description: "Einheitensystem: metric oder imperial"
          default: "metric"
      required: ["location"]
    recommended_policy: allow

credentials:
  - name: WEATHER_API_KEY
    scope: system
    required: true
    description: API-Schlüssel für den Wetterdienst

resources:
  max_memory_mb: 128
  max_cpu_fraction: 0.5

Beispiel mit dynamischen Tools

manifest.yaml

id: file-manager
class: tool
image: ghcr.io/example/file-manager:2.0.0
tool_source: dynamic
discovery_tool_name: list_available_tools

credentials:
  - name: CLOUD_STORAGE_TOKEN
    scope: user
    required: false
    description: Optionaler Token für Cloud-Storage-Integration

resources:
  max_memory_mb: 256
  max_cpu_fraction: 0.75

Schema

Felder auf oberster Ebene

Feld	Typ	Erforderlich	Standard	Beschreibung
id	string	Ja		Eindeutiger Bezeichner (Kleinbuchstaben, Bindestriche).
class	string	Nein	"tool"	"tool" oder "environment".
image	string	Ja		Docker-Image, das diese Capability implementiert.
tool_source	string	Nein	"manifest"	Wie Tools definiert werden: "manifest" oder "dynamic".
discovery_tool_name	string	Nein	"list_tools"	Name des Tools für die dynamische Erkennung.
tools	list	Nein	[]	Statische Tool-Definitionen (nur bei tool_source: "manifest").
network	object	Nein	Siehe unten	Netzwerkzugriffs-Konfiguration.
filesystem	string	Nein	"none"	Dateisystem-Zugriffsrichtlinie.
credentials	list	Nein	[]	Benötigte Anmeldedaten und Secrets.
resources	object	Nein	Siehe unten	Container-Ressourcenlimits.

Achtung

Wenn tool_source auf "dynamic" gesetzt ist, muss das tools-Feld leer sein ([]). Dynamische Capabilities ermitteln ihre verfügbaren Tools zur Laufzeit durch Aufruf des Discovery-Tools.

Tool-Quellen

Selu unterstützt zwei Methoden, um die Tools einer Capability zu definieren:

Statische Tools (tool_source: manifest)

Tools werden direkt in der manifest.yaml-Datei deklariert. Das ist der klassische Ansatz und bleibt der Standard.

Dynamische Tools (tool_source: dynamic)

Tools werden zur Laufzeit durch Aufruf eines speziellen Discovery-Tools auf dem Capability-Container ermittelt. Dies ermöglicht:

• Anpassung der verfügbaren Tools basierend auf Laufzeitbedingungen
• Verschiedene Tools je nach vorhandenen Anmeldedaten
• Aktualisierung des Tool-Sets ohne Manifest-Änderung

Bei dynamischer Erkennung wird Selu:

1. Den Capability-Container starten
2. Das Discovery-Tool aufrufen (Standardname: list_tools)
3. Die zurückgegebenen Tool-Definitionen parsen
4. Die Ergebnisse cachen und periodisch synchronisieren

Das Discovery-Tool muss ein JSON-Array von Tool-Definitionen zurückgeben:

[
  {
    "name": "read_file",
    "description": "Dateiinhalt lesen",
    "input_schema": {
      "type": "object",
      "properties": {
        "path": {"type": "string", "description": "Dateipfad"}
      },
      "required": ["path"]
    },
    "recommended_policy": "ask"
  }
]

tools[*] (nur statischer Modus)

Jeder Eintrag beschreibt eine aufrufbare Funktion, die Agenten nutzen können.

Feld	Typ	Erforderlich	Beschreibung
name	string	Ja	Tool-Name, verwendet im gRPC-InvokeRequest.tool_name.
description	string	Ja	Wird dem Agenten gesendet, um zu erklären, was das Tool tut.
input_schema	object	Ja	JSON-Schema, das die Parameter des Tools definiert.
requires_confirmation	bool	Nein	Legacy-Feld — stattdessen recommended_policy verwenden.
recommended_policy	string	Nein	Empfohlene Sicherheitsrichtlinie: "allow", "ask" oder "block".
terminal_on_success	bool	Nein	Tool-Schleife nach erfolgreichem Aufruf sofort beenden. Standard false.

network

Feld	Typ	Standard	Beschreibung
mode	string	"none"	Netzwerkmodus: "none", "allowlist" oder "any".
hosts	array	[]	Erlaubte Hosts im allowlist-Modus (Format: "host:port").

Netzwerk-Hosts unterstützen Wildcard-Matching für Subdomains:

• "api.example.com:443" — matcht genau api.example.com auf Port 443
• "*.example.com:443" — matcht jede Subdomain wie cdn.example.com oder api.example.com
• "*.example.com" — matcht Subdomains auf jedem Port

Hinweis

Wildcard-Muster wie "*.example.com" matchen Subdomains, aber nicht die Root-Domain selbst. Um sowohl example.com als auch seine Subdomains zu erlauben, beide separat auflisten.

filesystem

Wert	Beschreibung
"none"	Nur-Lese-Dateisystem, kein persistenter Speicher.
"temp"	Beschreibbares /tmp-Verzeichnis (wird bei Container-Neustart geleert).
"workspace"	Benanntes Docker-Volume unter /workspace (nur environment-Klasse).

credentials[*]

Feld	Typ	Erforderlich	Standard	Beschreibung
name	string	Ja		Name der Umgebungsvariable.
scope	string	Ja		"system" (geteilt) oder "user" (pro Benutzer).
credential_type	string	Nein	"secret"	Typ der Anmeldedaten (derzeit nur "secret").
required	bool	Nein	true	Ob diese Anmeldedaten zwingend erforderlich sind.
description	string	Nein	""	Menschenlesbare Erklärung für Benutzer.

resources

Feld	Typ	Standard	Beschreibung
max_memory_mb	integer	128	Speicherlimit in Megabytes.
max_cpu_fraction	number	0.5	CPU-Limit in Kernen (0.5 = halber Kern).
max_cpu_seconds	integer	30	Maximale CPU-Zeit pro Tool-Aufruf.
pids_limit	integer	64	Maximale Prozesse/Threads.

Dynamische Tool-Erkennung

Capabilities mit tool_source: dynamic müssen ein Discovery-Tool implementieren, das die aktuell verfügbaren Tools zurückgibt.

Discovery-Tool-Schnittstelle

Das Discovery-Tool wird wie jedes andere Tool aufgerufen, sollte aber ein JSON-Array mit allen verfügbaren Tools zurückgeben:

server.py

def invoke(self, request, context):
    if request.tool_name == "list_tools":
        # Verfügbare Tools basierend auf aktuellem Zustand zurückgeben
        tools = []

        # Immer verfügbar
        tools.append({
            "name": "basic_operation",
            "description": "Führt eine Basisoperation aus",
            "input_schema": {
                "type": "object",
                "properties": {
                    "input": {"type": "string"}
                },
                "required": ["input"]
            },
            "recommended_policy": "allow"
        })

        # Nur verfügbar wenn Anmeldedaten konfiguriert
        if os.getenv("PREMIUM_API_KEY"):
            tools.append({
                "name": "premium_feature",
                "description": "Zugriff auf Premium-Funktionen",
                "input_schema": {
                    "type": "object",
                    "properties": {
                        "query": {"type": "string"}
                    }
                },
                "required": ["query"]
            },
            "recommended_policy": "ask"
            })

        return pb2.InvokeResponse(
            result=json.dumps(tools),
            success=True
        )

Synchronisierungsverhalten

Selu synchronisiert dynamische Tools automatisch:

• Beim Start — Best-Effort-Synchronisation für alle geladenen Agenten
• Bei Installation/Update — Tools werden als Teil des Installationsprozesses erkannt
• Beim Setup — Frische Erkennung vor der Anzeige von Tool-Richtlinien

Wenn sich Tools zwischen Synchronisierungen ändern:

• Hinzugefügte Tools erhalten die globale Standardrichtlinie (aus recommended_policy oder "block")
• Entfernte Tools werden aus Richtlinientabellen und dem Cache gelöscht
• Geänderte Tools aktualisieren ihre gecachten Definitionen

Wenn die Erkennung fehlschlägt, behält Selu die zuvor gecachten Tools bei und loggt einen Fehler.

Validierung

Häufige Validierungsfehler:

• Dynamisch + statisch Konflikt — tool_source: dynamic erfordert tools: []
• Fehlendes Discovery-Tool — Dynamische Capabilities müssen das Discovery-Tool implementieren
• Ungültige Tool-Schemas — Sowohl statische als auch erkannte Tools müssen gültiges JSON-Schema haben
• Netzwerk-Host-Format — Hosts müssen im Format "hostname:port" sein

Statisch vs. dynamisch wählen

Verwende statische Tools wenn:

• Die Capability einen festen Satz an Tools bereitstellt
• Tool-Definitionen sich nicht basierend auf Laufzeitbedingungen ändern
• Einfacheres Deployment und Debugging gewünscht ist

Verwende dynamische Tools wenn:

• Verfügbare Tools von konfigurierten Anmeldedaten abhängen
• Tools ohne Manifest-Änderung hinzugefügt/entfernt werden sollen
• Tools durch externen Zustand oder APIs bestimmt werden

Tipp

Dynamische Erkennung erhöht die Komplexität, bietet aber Flexibilität. Starte mit statischen Tools und migriere nur zu dynamisch, wenn die Laufzeit-Anpassbarkeit benötigt wird.

Nächste Schritte

• gRPC-Schnittstelle — Protokolldetails für die Implementierung von Capability-Servern.
• Container-Richtlinien — Sicherheits- und Ressourcenanforderungen für Docker-Images.
• Eingebaute Tools — Tools, die allen Agenten standardmäßig zur Verfügung stehen.