Abilities für KI-Agenten

Mit WordPress 6.9 kam die Abilities API: Ein Plugin beschreibt, was es kann, mit einem Schema für Ein- und Ausgabe, und KI-Werkzeuge können diese Abilities über REST oder einen MCP-Adapter finden und ausführen. Easy SVG Pro registriert vier davon. Ein Agent kann jedes Icon der Seite lesen, ein neues in die Icon-Bibliothek legen und Icons in einem Icon-Set hinzufügen oder entfernen. Jedes Icon, das er schreibt, läuft durch denselben Sanitizer wie ein Upload.

Die vier Abilities

Alle vier liegen in der Kategorie easy-svg-pro mit dem Label "Easy SVG".

Wann es sie gibt

Ein Agent sieht die Abilities nur, wenn all das zutrifft:

Welche Icons list-icons meldet, hängt außerdem an Funktionen: die kostenlose Bibliothek nur, solange ihre Icon-Funktion im kostenlosen Plugin an ist, Sammlungen aus Themes, Ordnern und Code nur bei eingeschalteten Mehrere Sammlungen, und Sets nur bei eingeschaltetem Icon-Set-Editor.

Aufruf per REST

WordPress liefert Abilities unter /wp-json/wp-abilities/v1/ aus. Authentifizier dich mit einem Anwendungspasswort eines Administrators. WordPress bietet Anwendungspasswörter nur über HTTPS an, oder auf einer Seite mit dem Umgebungstyp local.

export SITE="https://example.com"
export AUTH="agent-bot:abcd efgh ijkl mnop qrst uvwx"

# Was kann diese Seite?
curl -s -u "$AUTH" "$SITE/wp-json/wp-abilities/v1/abilities?category=easy-svg-pro"

Der Endpunkt zum Ausführen ist /wp-json/wp-abilities/v1/abilities/<name>/run. WordPress wählt die HTTP-Methode aus den Annotationen der Ability: Nur lesende laufen mit GET, zerstörende und idempotente mit DELETE, alle anderen mit POST. Bei GET und DELETE steht die Eingabe im Query-Parameter input, bei POST im JSON-Body unter input.

Icons auflisten

curl -s -u "$AUTH" -G "$SITE/wp-json/wp-abilities/v1/abilities/easy-svg-pro/list-icons/run" \
	--data-urlencode "input[search]=arrow" \
	--data-urlencode "input[per_page]=50"

{
	"items": [
		{ "slug": "arrow-right", "label": "Arrow Right", "collection": "acme", "source": "set" }
	],
	"total": 1,
	"page": 1,
	"per_page": 50,
	"has_more": false,
	"truncated": false
}

Eingabefelder:

Ein Icon in die Bibliothek legen

curl -s -u "$AUTH" -X POST "$SITE/wp-json/wp-abilities/v1/abilities/easy-svg-pro/add-icon/run" \
	-H "Content-Type: application/json" \
	-d '{"input":{"label":"Arrow","markup":"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M5 12h14"/></svg>"}}'

{ "added": true, "slug": "arrow-2", "label": "Arrow", "collection": "easy-svg", "source": "library" }

Ein vergebener Name bekommt eine Nummer. Der slug in der Antwort ist der, den WordPress wirklich gespeichert hat, nach dem Schreiben zurückgelesen. Nimm ihn, nie einen, den du selbst aus dem Label ableitest.

Icons zu einem Set hinzufügen

icons ist ein Objekt, dessen Schlüssel der Name ist, den jedes Icon bekommen soll. Jeder Wert enthält label und markup.

curl -s -u "$AUTH" -X POST "$SITE/wp-json/wp-abilities/v1/abilities/easy-svg-pro/add-icons-to-set/run" \
	-H "Content-Type: application/json" \
	-d '{"input":{"set_id":42,"icons":{"cart":{"label":"Warenkorb","markup":"<svg ...>...</svg>"}}}}'

{ "set_id": 42, "slug": "acme", "report": [ { "slug": "cart", "state": "added" } ] }

Einen Namen, den das Set schon hat, meldet sie als exists und lässt ihn in Ruhe. Überschreiben kann diese Ability nicht. slug ist der Sammlungs-Slug, den Templates nutzen, zum Beispiel acme/cart.

Icons aus einem Set entfernen

curl -s -u "$AUTH" -X DELETE -G "$SITE/wp-json/wp-abilities/v1/abilities/easy-svg-pro/remove-icon-from-set/run" \
	--data-urlencode "input[set_id]=42" \
	--data-urlencode "input[slugs][]=cart"

{ "set_id": 42, "slug": "acme", "report": [ { "slug": "cart", "state": "removed" } ] }

Einen Namen, den das Set nicht hat, meldet sie als not_found. Die anderen werden trotzdem entfernt.

Aufruf aus PHP

Abilities sind normale WordPress-Objekte, dein eigener Code kann sie also auch ausführen, zum Beispiel aus einem Queue-Worker, der Aufträge abarbeitet, die ein Agent in einer Tabelle hinterlassen hat.

/**
 * Ein Icon über die Ability in die Bibliothek legen, mit allen ihren Prüfungen.
 */
function acme_agent_add_icon( $label, $markup ) {
	if ( ! function_exists( 'wp_get_ability' ) ) {
		return new WP_Error( 'acme_no_abilities', 'Dieses WordPress hat keine Abilities API.' );
	}

	$ability = wp_get_ability( 'easy-svg-pro/add-icon' );
	if ( null === $ability ) {
		return new WP_Error( 'acme_no_ability', 'Schalte Abilities für KI-Agenten unter Icons, Funktionen ein.' );
	}

	$result = $ability->execute(
		array(
			'label'  => (string) $label,
			'markup' => (string) $markup,
		)
	);

	if ( is_wp_error( $result ) ) {
		error_log( sprintf( 'Icon abgelehnt: %s (%s)', $result->get_error_message(), $result->get_error_code() ) );
	}

	return $result;
}

execute() prüft die Eingabe gegen das Schema und führt die Berechtigungsprüfung aus, braucht also einen aktuellen Benutzer mit manage_options. Läuft dieser Code außerhalb eines REST-Requests und schreibt Sets, ergänz auch easy_svg_pro_set_write_context, damit er die Set-Sperre nimmt.

Fehler, die ein Agent verstehen sollte

Jede Ablehnung ist ein WP_Error mit festem Code, ein Client kann also danach verzweigen.

Stolperfallen

• list-icons liefert keine Set-IDs. Die Set-Abilities brauchen set_id, aber list-icons meldet Sets nur per Slug. Such die ID selbst heraus, zum Beispiel mit GET /wp-json/easy-svg-pro/v1/sets/list (interne Route) oder im Tab Icon-Sets, und gib sie dem Agenten.
• Set-Slugs in list-icons sind Post-Slugs. Auf Seiten, die ältere Versionen liefen, heißt die registrierte Sammlung eines Sets vielleicht acme-x, während list-icons acme sagt. Die Set-Abilities antworten mit dem registrierten Slug.
• Dasselbe Icon doppelt. Sind Mehrere Sammlungen und Icon-Set-Editor beide an, erscheinen die Icons eines Sets einmal mit source: collection und einmal mit source: set. Filter nach source, wenn du zählst.
• Eine unbekannte source liefert nichts. Ein Tippfehler wie sets ergibt eine leere Liste, nicht alles. Das ist Absicht.
• Abgelehnte Icons fehlen im Bericht. Bei add-icons-to-set fliegt ein Icon, das der Sanitizer ablehnt, vor dem Zusammenführen raus und taucht in report einfach nicht auf. Vergleich die gesendeten Namen mit den zurückgemeldeten.
• Ein unbekanntes Set schlägt nicht fehl. add-icons-to-set und remove-icon-from-set antworten bei einer set_id, die kein Icon-Set ist, mit leerem slug und leerem report statt mit einem Fehler. Werte einen leeren slug als Fehlschlag.
• Keine Obergrenze pro Aufruf. Die REST-Route hinter den Set-Abilities nimmt höchstens 25 Icons, die Abilities wenden diese Grenze nicht an. Schick trotzdem vernünftige Portionen.
• MCP braucht einen Adapter. Die Abilities tragen mcp-Metadaten, aber Easy SVG Pro bringt keinen MCP-Server mit. Prüf die Schlüsselnamen gegen den Adapter, den deine Seite nutzt.

Siehe auch

• easy-svg-pro/list-icons
• easy-svg-pro/add-icon
• easy-svg-pro/add-icons-to-set
• easy-svg-pro/remove-icon-from-set
• Auf Set-Änderungen reagieren
• REST-API