Zum Inhalt springen
Selu Docs

Admin Web API Referenz

Selu bietet mehrere nur-für-Admins zugängliche HTTP-Endpunkte zur Verwaltung von Agenten, Benutzern und Systemkonfiguration. Alle Endpunkte erfordern Authentifizierung über Session-Cookie.

Agenten-Verwaltung

Abschnitt betitelt „Agenten-Verwaltung“

POST /agents/update/start

Abschnitt betitelt „POST /agents/update/start“

Starte einen Agenten-Update-Job im Hintergrund.

Anfrage:

POST /agents/update/start
Content-Type: application/x-www-form-urlencoded


entry_json={"id":"weather","name":"Weather Assistant",...}

Parameter:

  • entry_json (string) — JSON-kodierter Marketplace-Eintrag für den zu aktualisierenden Agenten

Antwort:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

Fehler-Antwort:

{
  "error_key": "agents.update.error.invalid_payload"
}

GET /agents/update/status/{job_id}

Abschnitt betitelt „GET /agents/update/status/{job_id}“

Hole den aktuellen Status eines Hintergrund-Agenten-Update-Jobs.

Parameter:

  • job_id (path) — UUID des Update-Jobs

Antwort:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "weather",
  "agent_name": "Weather Assistant",
  "target_version": "1.2.0",
  "progress": 75,
  "message_key": "agents.update.phase.downloading",
  "done": false,
  "success": false,
  "redirect_to": null,
  "error_key": null
}

Antwort-Felder:

  • progress (number) — Fertigstellungsgrad in Prozent (0-100)
  • message_key (string) — I18n-Schlüssel für aktuelle Statusnachricht
  • done (boolean) — Ob der Job abgeschlossen ist
  • success (boolean) — Ob der Job erfolgreich abgeschlossen wurde (nur relevant wenn done true ist)
  • redirect_to (string|null) — URL zum Weiterleiten nach Abschluss (typischerweise Setup-Seite)
  • error_key (string|null) — I18n-Schlüssel für Fehlernachricht wenn Job fehlgeschlagen ist

Status-Nachrichten-Schlüssel:

  • agents.update.phase.preparing — Job startet
  • agents.update.phase.downloading — Docker-Images werden heruntergeladen
  • agents.update.success.updated — Update erfolgreich abgeschlossen
  • agents.update.success.setup_required — Update abgeschlossen, Setup erforderlich
  • agents.update.error.docker — Docker-Verbindung fehlgeschlagen
  • agents.update.error.start — Update konnte nicht gestartet werden
  • agents.update.error.failed — Update-Prozess fehlgeschlagen

POST /agents/update (legacy)

Abschnitt betitelt „POST /agents/update (legacy)“

Synchroner Agenten-Update-Endpunkt. Noch verfügbar für formular-basierte Updates, kann aber mehrere Minuten blockieren.

Anfrage:

POST /agents/update
Content-Type: application/x-www-form-urlencoded


entry_json={"id":"weather","name":"Weather Assistant",...}

Antwort: HTTP 302 Weiterleitung zur Agenten-Seite oder Setup-Assistent.

Tool-Richtlinien-Verwaltung

Abschnitt betitelt „Tool-Richtlinien-Verwaltung“

POST /agents/{agent_id}/policy

Abschnitt betitelt „POST /agents/{agent_id}/policy“

Aktualisiere eine Tool-Richtlinie für einen spezifischen Agenten. Wird von der HTMX-basierten Berechtigungsschnittstelle verwendet.

Parameter:

  • agent_id (path) — Agenten-Identifikator
  • capability_id (form) — Capability-ID (verwende __builtin__ für eingebaute Tools)
  • tool_name (form) — Tool-Name
  • policy (form) — Richtlinien-Wert: allow, ask oder block
  • scope (form) — global (nur Admin) oder user (Standard)

Anfrage:

POST /agents/weather/policy
Content-Type: application/x-www-form-urlencoded


capability_id=search&tool_name=web_search&policy=ask&scope=user

Antwort: HTTP 200 (leerer Body) bei Erfolg, HTTP 500 bei Fehler.

POST /agents/{agent_id}/policy/reset

Abschnitt betitelt „POST /agents/{agent_id}/policy/reset“

Setze eine persönliche Richtlinien-Überschreibung eines Nutzers auf den globalen Standard zurück.

Parameter:

  • agent_id (path) — Agenten-Identifikator
  • capability_id (form) — Capability-ID
  • tool_name (form) — Tool-Name
  • return_to (form, optional) — URL zum Weiterleiten nach Reset

Antwort: HTTP 200 mit HX-Redirect Header zur Agenten-Berechtigungsseite.

Update-Job-Lebenszyklus

Abschnitt betitelt „Update-Job-Lebenszyklus“

Agenten-Updates folgen diesem Ablauf:

  1. Start — POST zu /agents/update/start gibt eine job_id zurück
  2. Polling — GET /agents/update/status/:job_id wiederholt bis done: true
  3. Ergebnis verarbeiten — success Feld und redirect_to URL prüfen

Fortschrittsverfolgung

Abschnitt betitelt „Fortschrittsverfolgung“

Das progress Feld spiegelt echten Docker-Image-Download-Fortschritt wider:

  • 0-10: Initialisierung
  • 10-90: Images herunterladen (basiert auf tatsächlichem Docker-Layer-Fortschritt)
  • 90-100: Update finalisieren

Fehlerbehandlung

Abschnitt betitelt „Fehlerbehandlung“

Wenn ein Update fehlschlägt:

  • done wird true sein
  • success wird false sein
  • error_key enthält einen I18n-Schlüssel für die Fehlernachricht
  • Bestehende Agenten-Installation bleibt unverändert

Authentifizierung

Abschnitt betitelt „Authentifizierung“

Alle Admin-Endpunkte erfordern:

  1. Gültiges Session-Cookie (von /login)
  2. Benutzerkonto mit is_admin = 1

Nicht autorisierte Anfragen geben HTTP 403 zurück.