Beschreibungen zu erlaubten API Endpunkte über einen eigenen Endpunkt anbieten

[dergel]

Gerade wenn es um Agentnutzung geht, muss ein Agent eigentlich zu jedem Endpunkt immer interpretieren, was dieser macht und was die Parameter sind und anbieten. Das muss er dann über die Doku oder spezifische Skills erkennen.

Da wäre es doch gut, wenn es genau einen Punkt gibt, bei dem genau diese erlaubten Endpunkte angezeigt werden und beschrieben sind, wie auch die Parameter. Ähnlich wie bei einem MCP.

[dergel]

Ergänzung zur Begründung — warum ein Agent das heute nicht selbst lösen kann.

Die Spezifikation existiert bereits, sie ist nur nicht abrufbar. OpenAPIConfig baut sie aus derselben Routentabelle, in die sich alle RoutePackages eintragen. Ausgeliefert wird sie aber unter page=api/openapi, also hinter rex::isBackend() und perm: api[] — ein Aufrufer mit Bearer-Token bekommt dort HTML. Es braucht also kein neues Datenmodell, nur einen token-authentifizierten Ausgang für das, was ohnehin schon aufgebaut wird.

Die härtere Hälfte: ein Token kennt seine eigenen Scopes nicht. Es gibt keine Selbstauskunft. Ein Agent weiß damit nicht, was er darf, und kann folglich nicht unterscheiden, ob er eine Aufgabe weglassen oder anders angehen muss.

Was heute geht — und warum es nicht reicht. Die Auth unterscheidet sauber:

Antwort	Bedeutung
200	Route existiert, Scope vorhanden
401	Route existiert, Scope fehlt
404	Route existiert nicht

Damit lässt sich eine Vermutung verifizieren, aber nichts aufzählen — den Pfad muss man erst raten. Die naheliegende Heuristik „Scope-Name minus letztes Segment ergibt den Pfad" trägt nur teilweise, weil die Aktion mal am Ende und mal in der Mitte steht:

media/list            → media                   passt
media/get             → media/{filename}/info   passt nicht
media/get/file        → media/{filename}/file   passt nicht
system/clangs/update  → system/clangs/{id}       passt nicht

In 1.2 trifft sie bei 20 von 66 Routen (gemessen über lib/RoutePackage/). Praktisch heißt das: Die Pfade müssen dem Agenten außerhalb der API mitgeteilt werden, per Doku oder Skill — genau das, was dieses Issue beseitigen will.

Der Vergleich mit MCP trägt weiter, als er zunächst klingt. Bei tools/list ist nicht die Liste das Entscheidende, sondern dass sie nach Berechtigung gefiltert ist: Der Client sieht nur, was er tatsächlich aufrufen darf. Eine ungefilterte Routenliste löst das Problem nur halb, weil der Agent dann weiter Routen probiert, für die er keinen Scope hat.

Zwei Punkte, die beim Entwurf leicht in die falsche Richtung kippen:

1. Der Endpunkt selbst sollte keinen eigenen Scope brauchen, sondern für jedes gültige Token antworten. Ein Scope, den man vergessen kann, reproduziert das Problem für genau die Token, bei denen er vergessen wurde.
2. Nicht mehr ausgeben, als der Aufrufer darf. Werden auch Routen ohne passenden Scope gelistet, entsteht eine Landkarte der Angriffsfläche statt einer Fähigkeitsliste.

Hilfreich wäre außerdem die Antwortform pro Route: Listenrouten liefern {data, meta}, manche Detailrouten das Objekt flach, und eine Liste enthält nicht zwingend dieselben Felder wie die Einzelabfrage — heute nur durch Ausprobieren herauszufinden.

---

Dieser Text wurde durch eine KI erstellt.