Die Abilities API

Die Abilities API beantwortet eine Frage, die mit KI dringend wurde: Woher soll ein Programm wissen, was diese WordPress-Website kann? Eine Route allein sagt es nicht – sie hat keine Beschreibung in natürlicher Sprache, keinen klaren Zweck, oft kein Schema. Eine Fähigkeit dagegen ist genau das: ein benannter, beschriebener, typisierter und rechtlich abgesicherter Vorgang. Diese Lektion zeigt, wie Sie Fähigkeiten registrieren und worauf es dabei ankommt, damit ein Agent sie richtig einsetzt.

1. Was eine Fähigkeit ist

Der Unterschied zu einer REST-Route liegt in der Beschreibung. Eine Route sagt „POST /termine“ – das versteht ein Mensch nach der Lektüre der Dokumentation. Eine Fähigkeit sagt „Bucht einen Werkstatttermin für ein Datum und gibt die Buchungsnummer zurück“, dazu welche Felder erwartet werden und wer sie nutzen darf. Damit kann ein Sprachmodell entscheiden, ob sie zur Aufgabe passt.

1<?php
2add_action( 'abilities_api_init', function () {
3    wp_register_ability( 'radwerk/freie-plaetze', [
4        'label'       => 'Freie Plätze abfragen',
5        'description' => 'Gibt die Zahl freier Werkstatttermine für ein Datum zurück.',
6        'input_schema'  => [
7            'type'       => 'object',
8            'properties' => [
9                'datum' => [ 'type' => 'string', 'format' => 'date' ],
10            ],
11            'required'   => [ 'datum' ],
12        ],
13        'output_schema' => [
14            'type'       => 'object',
15            'properties' => [ 'frei' => [ 'type' => 'integer' ] ],
16        ],
17        'execute_callback'    => 'radwerk_freie_plaetze',
18        'permission_callback' => fn() => current_user_can( 'read' ),
19        'meta' => [
20            'public'    => false,
21            'annotations' => [ 'readOnlyHint' => true ],
22        ],
23    ] );
24} );

2. Die Bestandteile im Einzelnen

1<?php
2wp_register_ability( 'radwerk/freie-plaetze', [
3    'label'       => 'Freie Plätze abfragen',
4    'description' => 'Gibt die Zahl freier Werkstatttermine für ein Datum zurück.',
5    'input_schema' => [
6        'type'       => 'object',
7        'properties' => [ 'datum' => [ 'type' => 'string', 'format' => 'date' ] ],
8        'required'   => [ 'datum' ],
9    ],
10    'output_schema' => [
11        'type'       => 'object',
12        'properties' => [ 'frei' => [ 'type' => 'integer' ] ],
13    ],
14    'execute_callback'    => function ( array $eingabe ) {
15        $frei = radwerk_freie_plaetze( $eingabe['datum'] );
16        return [ 'frei' => $frei ];
17    },
18    'permission_callback' => fn() => current_user_can( 'read' ),
19] );

3. Gute Fähigkeiten schneiden

Die Qualität einer Fähigkeit entscheidet darüber, ob ein Agent nützlich oder gefährlich ist. Bewährt haben sich vier Regeln. Erstens: eng schneiden. Eine Fähigkeit „Beitrag verwalten“, die anlegen, ändern und löschen kann, ist schlechter als drei getrennte Fähigkeiten mit je eigener Rechteprüfung. Zweitens: ehrlich beschreiben, auch die Grenzen – „nur für veröffentlichte Beiträge“ gehört in die Beschreibung. Drittens: Schemata eng fassen, mit erlaubten Werten statt freiem Text, wo es geht. Viertens: lesende und schreibende Fähigkeiten klar trennen und Letztere nur dort freigeben, wo es wirklich nötig ist.

4. Freigabe und Sichtbarkeit

Fähigkeiten sind nicht automatisch für externe Agenten sichtbar. Standardmäßig bleiben sie intern; erst eine ausdrückliche Freigabe in den Metadaten macht sie über den MCP Adapter verfügbar. Das ist eine bewusste Entscheidung des Projekts: Wer eine Fähigkeit registriert, öffnet damit nicht automatisch die Website nach außen. Zusätzlich lassen sich Fähigkeiten als rein lesend kennzeichnen – ein Hinweis, den Agenten und Oberflächen nutzen können, um schreibende Aufrufe besonders zu behandeln, etwa mit einer Rückfrage.

5. Ein Beispiel

Ein Fahrradladen registrierte vier Fähigkeiten: freie Termine suchen, Termin buchen, Termin stornieren und Werkstattauslastung der Woche abfragen. Die beiden lesenden sind freigegeben, die beiden schreibenden verlangen eine Anmeldung mit der passenden Rolle und sind zunächst nur intern nutzbar. Die Beschreibungen entstanden in mehreren Anläufen: Anfangs buchte ein Testagent Termine an Sonntagen, weil die Beschreibung nichts über Öffnungszeiten sagte. Nach der Ergänzung „bucht nur an Werktagen; Sonntag und Montag sind geschlossen“ und einer zusätzlichen Prüfung im Code trat das Problem nicht mehr auf. Diese Erfahrung ist typisch: Die meiste Arbeit steckt nicht im Registrieren, sondern im genauen Beschreiben und Begrenzen.

6. Häufige Fragen

Ersetzen Fähigkeiten die REST API? Nein, sie liegen daneben. Die REST API bleibt für Datenzugriffe und Anwendungen; Fähigkeiten beschreiben Vorgänge für KI und andere Aufrufer. Beide können dieselbe Funktion im Hintergrund nutzen.

Kann ich Kernfunktionen als Fähigkeiten nutzen? WordPress und Plugins bringen zunehmend eigene Fähigkeiten mit. Welche vorhanden sind, lässt sich im Verzeichnis abfragen – so vermeiden Sie, etwas doppelt zu registrieren.

Wie teste ich eine Fähigkeit? Wie jede andere Funktion: Eingabe hinein, Ergebnis prüfen. Weil die Schemata die Eingaben festlegen, lassen sich auch Grenzfälle gut testen – ganz ohne Modell und ohne Kosten.

7. Übung zum Selbermachen

Registrieren Sie in Ihrem Übungsplugin die Fähigkeit uebung/beitraege-zaehlen, die für einen übergebenen Monat die Zahl veröffentlichter Beiträge zurückgibt – mit Eingabeschema für das Format Jahr-Monat und der Rechteprüfung read. Schreiben Sie die Beschreibung dann zweimal: einmal knapp („Zählt Beiträge“) und einmal genau. Überlegen Sie bei jeder Fassung, welche Fehlaufrufe möglich wären. Ergänzen Sie danach eine zweite, schreibende Fähigkeit und entscheiden Sie bewusst, ob Sie sie freigeben.

Stand: September 2026, WordPress 7.1, PHP 8.3. Kursmaterial der Klarwerk Akademie. WordPress entwickelt sich schnell – maßgeblich ist die aktuelle Dokumentation auf developer.wordpress.org.