WordPress AI workflows: Abilities API w praktyce

#Czym jest WordPress Abilities API?

#Problem z obecnymi podejściami

WordPress REST API jest potężne, ale zorientowane na zasoby. Udostępnia endpointy jak /wp/v2/posts i /wc/v3/products, czyli operacje CRUD na obiektach danych. Agent AI może z nich korzystać, ale musi być wcześniej zaprogramowany: wiedzieć, co każdy endpoint robi, jakie parametry przyjmuje i jak połączyć wiele wywołań, żeby osiągnąć cel.

WPGraphQL poprawia sytuację, pozwalając na elastyczne zapytania, ale ma to samo fundamentalne ograniczenie: opisuje dane, nie możliwości.

Rozważmy scenariusz: chcesz, aby agent AI „napisał artykuł o wiosennym ogrodnictwie, zoptymalizował go pod SEO, dodał obrazek wyróżniający i zaplanował publikację na wtorek”. Z samym REST API agent musi:

1. Znać endpoint /wp/v2/posts i jego parametry
2. Wiedzieć, że dane SEO leżą w meta polach kontrolowanych przez Yoast lub RankMath
3. Wiedzieć, jak przesłać media przez /wp/v2/media
4. Znać format daty do planowania
5. Połączyć te wywołania w odpowiedniej kolejności

Z Abilities API wtyczka rejestruje wąskie operacje w rodzaju content/create-draft czy media/attach-image. Uwierzytelniona integracja wylistuje te abilities, które faktycznie wystawiono przez REST, obejrzy schematy i wywoła właściwy endpoint. Planowanie kolejności zostaje po stronie wywołującego, chyba że wtyczka dostarczy jedną operację wyższego poziomu domykającą całość.

#Przegląd architektury

Architektura ma cztery elementy. Kategoria grupuje pokrewne operacje. Ability ma unikalną nazwę w formacie przestrzeń/nazwa-ability, etykietę, opis, schematy i callbacki. Rejestr pozwala kodowi WordPressa odnaleźć zarejestrowane abilities. Widoczność w REST jest opcjonalnym transportem dla uwierzytelnionych systemów zewnętrznych.

Rejestracja odbywa się na dedykowanych hookach i tu najłatwiej się potknąć. Kategorie rejestruje się na wp_abilities_api_categories_init funkcją wp_register_ability_category(), a abilities na wp_abilities_api_init funkcją wp_register_ability(). Po wpięciu w ogólny hook ładowania wtyczki kod potrafi wystartować, zanim rejestry będą gotowe, a ability po prostu nie istnieje i nikt tego nie zgłasza błędem.

Serwerową część opisuje oficjalny handbook dla WordPressa 6.9 i nowszych. WordPress 7.0 dołożył pakiety klienckie, które wczytują serwerowe abilities do JavaScriptu w kokpicie. To dodatek, a nie zamiennik rejestru PHP.

#Odkrywanie i wykonywanie przez REST

Domyślnie żadna ability nie jest widoczna z zewnątrz. Wtyczka włącza ją pojedynczo przez meta.show_in_rest. Dopiero wtedy uwierzytelniony klient wylistuje abilities pod /wp-json/wp-abilities/v1/abilities, pobierze jedną po przestrzeni nazw i nazwie, a następnie wywoła jej endpoint /run. Metoda HTTP zależy od adnotacji i charakteru operacji.

Uwierzytelnianie pozostaje takie samo jak w całym REST API WordPressa. Kluczowa jest tu jedna zasada: to, że ability pojawia się na liście, nie oznacza prawa do jej uruchomienia. WordPress i tak wykona jej permission_callback dla bieżącego użytkownika.

W praktyce ten podział bardzo pomaga. Wtyczka może zarejestrować ability wyłącznie na własny użytek, dla innego kodu PHP, zostawiając show_in_rest wyłączone. Inną, tylko do odczytu, można wystawić kontu serwisowemu z wąskim zestawem uprawnień. Operacja destrukcyjna powinna mieć i węższy permission callback, i dodatkowe kontrole na poziomie aplikacji.

#Jak połączyć Abilities API z agentem AI

#Model Context Protocol nie jest wbudowany

Model Context Protocol firmy Anthropic definiuje, jak agenci AI odkrywają i wykorzystują zewnętrzne narzędzia. Abilities API dostarcza opisy i schematy JSON, które dobrze się na ten format przekładają, ale rdzeń WordPressa nie wystawia endpointu MCP ani manifestu dla konkretnego dostawcy. To wciąż praca integracyjna.

Most robi kilka rzeczy samodzielnie: uwierzytelnia się w WordPressie, wybiera dozwolony podzbiór abilities, tłumaczy schematy, wymusza własne limity i mapuje błędy z powrotem do klienta. Dobry most udostępnia mniej operacji, niż potrafi wykonać użytkownik, na którego się loguje, a nie wszystko, co odkrył na liście.

#Wąski zakres jako decyzja projektowa

Przykład z obsługi klienta: asystent dostaje operację odczytu danych produktu i operację tworzenia szkicu zgłoszenia. Zwroty, kasowanie kont i zmiany ustawień zostają poza mostem, nawet jeśli konto techniczne teoretycznie ma do nich uprawnienia. Taki podział da się zrecenzować w code review. Jeden agent ogólnego przeznaczenia z rolą administratora nie da się zrecenzować w ogóle.

Schematy JSON mapują się na parametry narzędzi wprost, więc pokusa, żeby wystawić „wszystko, co się da”, jest duża. Koszt utrzymania mostu rośnie liniowo z liczbą operacji, a ryzyko szybciej.

#Co zmienia WordPress 7.1

WordPress 7.1 wychodzi 19 sierpnia 2026 i dotyka tego API w trzech miejscach: odkrywania, ekspozycji i punktów rozszerzeń wokół zapytania o rejestr.

Zacznijmy od odkrywania. Do tej pory kod, który potrzebował wycinka rejestru, pobierał wszystkie abilities i przesiewał tablicę ręcznie przez array_filter(). W 7.1 wp_get_abilities() przyjmuje opcjonalną tablicę $args z kluczami category, namespace, meta, item_include_callback i result_callback. Warunki łączy operator AND, więc ability trafia na listę tylko wtedy, gdy spełnia każdy podany argument. Nota programistyczna od razu zamyka najczęstsze nieporozumienie: „Filtering controls which abilities are returned during discovery. It does not determine whether the current user may execute an ability.” Filtrowanie decyduje o tym, co zwraca odkrywanie, a nie o tym, kto może cokolwiek uruchomić. O uprawnieniach nadal rozstrzyga permission_callback przy wykonaniu.

Druga zmiana to wspólny klucz meta['public']. Deklaruje, że operacja jest przeznaczona dla klientów zewnętrznych, bez powtarzania tej decyzji dla każdego kanału. Flagi kanałowe zostają w mocy: „Channel-specific settings take precedence over the general public setting.” Ustawienie kanałowe ma pierwszeństwo przed ogólnym public, a rdzeń rozstrzyga to jedną linią, $show_in_rest = $meta['show_in_rest'] ?? $meta['public'] ?? false;. Ability z show_in_rest ustawionym na false i public na true nadal nie pojawi się w REST. Rejestracja z nowym kluczem wygląda tak:

wp_register_ability(
    'my-plugin/export-users',
    array(
        'label'               => __( 'Export users', 'my-plugin' ),
        'description'         => __( 'Exports user data as CSV.', 'my-plugin' ),
        'category'            => 'data-export',
        'execute_callback'    => 'my_plugin_export_users',
        'permission_callback' => function (): bool {
            return current_user_can( 'export' );
        },
        'meta'                => array(
            'public' => true,
        ),
    )
);

Tu potrzebna jest trzeźwa uwaga, bo tę flagę łatwo przeczytać na wyrost. public zapisuje intencję: że daną operację wolno udostępnić klientom zewnętrznym, na przykład konsumentom REST, adapterom MCP czy agentom AI. Nie oznacza, że rdzeń zaczyna te adaptery dostarczać. W 7.1 nadal nie ma serwera MCP, zakresów tokenów przeznaczonych dla agentów, limitów zapytań, dziennika audytu ani kolejki akceptacji. Most opisany wyżej trzeba zbudować dokładnie tak samo jak przed 7.1.

Trzecia zmiana to nowe punkty rozszerzeń: filtry wp_get_abilities_item_include i wp_get_abilities_result pozwalają cudzemu kodowi wpłynąć na to samo zapytanie, a rest_abilities_collection_params rozszerza schemat argumentów kolekcji po stronie REST. Warto dopisać je do listy rzeczy sprawdzanych w code review: skoro inna wtyczka może zmienić wynik odkrywania, lista widziana przez integrację przestaje być funkcją wyłącznie Twojej rejestracji.

#Praktyczne zastosowania

#Workflow tworzenia treści

Najbardziej bezpośrednim zastosowaniem jest tworzenie treści. Zamiast surowego tekstu, który człowiek wkleja do WordPressa, agent obsługuje cały przepływ:

Użytkownik: "Stwórz kompleksowy przewodnik o ekologicznym zwalczaniu szkodników na nasz blog ogrodniczy"

Workflow agenta AI:
1. run: research_topics → znajduje trendy i luki konkurencji
2. run: generate_content → tworzy artykuł z nagłówkami i odniesieniami do obrazów
3. run: optimize_seo → dodaje meta opis, słowo kluczowe, linki wewnętrzne
4. run: generate_featured_image → tworzy obrazek wyróżniający generowany przez AI
5. run: create_draft → zapisuje jako szkic z całością metadanych
6. run: notify_editor → wysyła powiadomienie o recenzji do zespołu redakcyjnego

Każdą z tych operacji dostarcza inna wtyczka: SEO przez RankMath, obrazy przez wtyczkę do mediów, powiadomienia przez wtyczkę workflow. Kolejność i obsługa błędów są zadaniem agenta, nie rdzenia. Jeśli krok trzeci padnie po zapisaniu szkicu, ktoś musi zdecydować, czy szkic zostaje, czy jest wycofywany.

#Zarządzanie sklepem WooCommerce

Dla sklepów e-commerce warstwa nazwanych operacji porządkuje to, co dziś rozjeżdża się po kilku wtyczkach:

• Magazyn: monitorowanie stanów, sugestie zamówień, aktualizacja ilości
• Ceny: analiza cen konkurencji, sugestie korekt, masowe zmiany
• Opisy produktów: aktualizacja na podstawie atrybutów i celów SEO
• Obsługa klienta: zwroty, statusy zamówień, etykiety wysyłkowe
• Analiza sprzedaży: raporty, identyfikacja trendów, sugestie promocji

Właściciel sklepu mógłby powiedzieć „Sprawdź produkty, które nie sprzedały się od 90 dni i zasugeruj, czy obniżyć cenę, połączyć w pakiet, czy wycofać”. Zwróćmy uwagę, gdzie leży granica: analiza to odczyt, zmiana ceny to zapis. Powinny to być osobne abilities z różnymi uprawnieniami, a nie jedna operacja z flagą.

#Automatyzacja SEO

Zadania SEO, które wcześniej wymagały ręcznej pracy lub osobnych narzędzi, dobrze układają się w nazwane operacje:

• analyze_page_seo - zwraca wynik, brakujące meta tagi, gęstość słów kluczowych
• suggest_internal_links - znajduje powiązane treści do crosslinkowania
• check_broken_links - skanuje w poszukiwaniu 404 i sugeruje zamienniki
• generate_schema_markup - tworzy dane strukturalne JSON-LD
• optimize_images - kompresuje i dodaje alt text do obrazów
• audit_content_freshness - flaguje przestarzałe treści do przeglądu

Cztery pierwsze to czysty odczyt i można je wystawić kontu serwisowemu. Dwie ostatnie zmieniają bibliotekę mediów i treść, więc zasługują na węższy permission callback i na zapis w dzienniku prowadzonym przez projekt.

#Implementacja niestandardowych abilities w Twojej wtyczce

#Podstawowa rejestracja ability

Ability potrzebuje unikalnej nazwy, kategorii, czytelnych dla człowieka metadanych, schematów, callbacka wykonania i callbacka uprawnień. Kategorię rejestrujemy pierwszą, bo ability bez istniejącej kategorii nie przejdzie walidacji.

<?php
declare(strict_types=1);

add_action( 'wp_abilities_api_categories_init', function () {
    wp_register_ability_category(
        'maintenance',
        array(
            'label'       => __( 'Utrzymanie strony', 'wppoland' ),
            'description' => __( 'Operacje diagnostyczne i porządkowe.', 'wppoland' ),
        )
    );
} );

add_action( 'wp_abilities_api_init', function () {
    wp_register_ability(
        'wppoland/sprawdzenie-zdrowia-strony',
        array(
            'label'               => __( 'Sprawdzenie zdrowia strony', 'wppoland' ),
            'description'         => __( 'Uruchamia wybrane testy diagnostyczne i zwraca wynik punktowy.', 'wppoland' ),
            'category'            => 'maintenance',
            'input_schema'        => array(
                'type'       => 'object',
                'properties' => array(
                    'checks' => array(
                        'type'  => 'array',
                        'items' => array(
                            'type' => 'string',
                            'enum' => array( 'performance', 'security', 'seo', 'accessibility' ),
                        ),
                        'description' => 'Które testy uruchomić. Domyślnie wszystkie.',
                    ),
                ),
            ),
            'output_schema'       => array(
                'type'       => 'object',
                'properties' => array(
                    'overall_score' => array( 'type' => 'number', 'minimum' => 0, 'maximum' => 100 ),
                    'checks'        => array( 'type' => 'array' ),
                ),
            ),
            'execute_callback'    => 'wppoland_sprawdzenie_zdrowia',
            'permission_callback' => function () {
                return current_user_can( 'manage_options' );
            },
            'meta'                => array(
                'show_in_rest' => false,
                'annotations'  => array(
                    'readonly' => true,
                ),
            ),
        )
    );
} );

function wppoland_sprawdzenie_zdrowia( array $input ): array {
    $requested = $input['checks'] ?? array( 'performance', 'security', 'seo', 'accessibility' );
    $results   = array();

    foreach ( $requested as $check ) {
        $results[] = match ( $check ) {
            'performance'   => run_performance_check(),
            'security'      => run_security_check(),
            'seo'           => run_seo_check(),
            'accessibility' => run_accessibility_check(),
            default         => array( 'name' => $check, 'score' => 0, 'issues' => array( 'Nieznany typ testu' ) ),
        };
    }

    $overall = array_sum( array_column( $results, 'score' ) ) / max( 1, count( $results ) );

    return array(
        'overall_score' => round( $overall, 1 ),
        'checks'        => $results,
    );
}

Zwróć uwagę na dwa szczegóły. show_in_rest jest tu ustawione na false, bo diagnostyka służy na razie tylko innemu kodowi PHP, który sięgnie po nią przez wp_get_ability(). Uprawnienie dobrano do tego, co operacja ujawnia; manage_options przy raporcie o bezpieczeństwie jest uzasadnione, przy odczycie tytułu strony byłoby przesadą.

#Kompozycja jest zadaniem wywołującego

Rdzeń daje rejestrację, odkrywanie, walidację i wykonanie. Nie zbuduje planera przepływów z deklaracji zależności, bo takiej deklaracji po prostu nie ma. Jeśli kilka operacji musi wykonać się w ustalonej kolejności, masz dwie drogi: napisać jedną serwerową ability obejmującą całą transakcję albo pozwolić zrecenzowanej warstwie orkiestracji wywoływać osobne abilities.

Wariant serwerowy jest bezpieczniejszy przy zmianach powiązanych ze sobą. Jeden callback zwaliduje komplet danych, zatrzyma się na pierwszym błędzie i zwróci jeden ustrukturyzowany wynik. Kompozycja po stronie klienta sprawdza się przy niezależnych odczytach, ale wtedy to wywołujący odpowiada za częściowe niepowodzenia i ponawianie.

#Kontrole operacyjne dodaj świadomie

Nie licz na nieudokumentowane hooki pośredniczące, które „opakują” wywołanie. Walidację domenową umieść w callbacku wykonania. Limity zapytań nakładaj na bramie, na reverse proxy lub w warstwie aplikacji. Zapisuj tylko te pola audytowe, które projekt ma prawo przechowywać.

#Bezpieczeństwo WordPressa dostępnego dla AI

#Uwierzytelnianie i autoryzacja

Endpointy abilities korzystają z uwierzytelniania REST API WordPressa. Dla żądań z tej samej domeny działają ciasteczka, dla dostępu zewnętrznego udokumentowane są hasła aplikacji, a projekt może dołożyć własną wtyczkę uwierzytelniania.

Uwierzytelnianie odpowiada na pytanie, kim jest wywołujący. permission_callback odpowiada, czy ten użytkownik może wykonać tę konkretną operację. Obie kontrole muszą zostać. Współdzielone konto administratora unieważnia sens wąskiego kontraktu, bo z perspektywy WordPressa każdy agent jest wtedy tą samą osobą.

Trzecią granicą jest widoczność w REST. Zarejestrowana ability pozostaje wewnętrzna, dopóki show_in_rest nie ma wartości true. To jedna linia w diffie i warto ją traktować jak zmianę uprawnień, a nie literówkę w konfiguracji.

#Zatwierdzanie ryzykownych zmian

Rdzeń WordPressa nie ma ogólnej kolejki akceptacji dla abilities. Jeśli zwrot, usunięcie danych albo zmiana ustawień wymagają potwierdzenia przez człowieka, trzeba to zbudować w aplikacji domenowej. Typowy wzorzec: ability tworzy żądanie w stanie oczekującym, a uprawniony użytkownik zatwierdza je osobną akcją w kokpicie.

Rozdziel zatwierdzanie od wykonania. Rekord akceptacji powinien wskazywać proponowaną zmianę, osobę recenzującą, czas wygaśnięcia i skrót danych wejściowych. Jeśli ta sama akceptacja obsłuży zmodyfikowane wejście, wraca luka, którą proces miał zamknąć.

#Ścieżka audytu

API nie tworzy kompletnej ścieżki audytu samo z siebie. Dla operacji wystawionych na zewnątrz zdecyduj, co musi zostać zapisane:

• uwierzytelniony użytkownik WordPressa albo konto serwisowe,
• nazwa ability i identyfikator korelacji żądania,
• kategoria wyniku i czas trwania,
• odwołanie do akceptacji przy zmianach wrażliwych,
• znacznik czasu i wersja aplikacji.

Nie loguj sekretów, pełnych promptów ani zbędnych danych osobowych. Retencja i dostęp do dzienników wymagają właściciela, a nie tylko tabeli w bazie.

#Sanityzacja danych wejściowych

Abilities API waliduje dane wejściowe względem zadeklarowanego JSON Schema przed wykonaniem, ale sprawdza kształt, a nie bezpieczeństwo. Ciąg poprawny wobec "type": "string" nadal bywa groźny w SQL, w HTML albo w nagłówku wiadomości. Wewnątrz callbacka stosuj funkcje WordPressa (sanitize_text_field(), wp_kses_post(), esc_url_raw()) dobrane do miejsca docelowego i korzystaj z przygotowanych zapytań do bazy.

#Porównanie z istniejącymi podejściami

#REST API vs. Abilities API

#WPGraphQL vs. Abilities API

WPGraphQL wyróżnia się w elastycznym odpytywaniu danych, pozwalając klientom pobrać dokładnie to, czego potrzebują, w jednym zapytaniu. Abilities API nie jest jego zamiennikiem. Ability może wewnętrznie użyć GraphQL do pobrania danych, wystawiając na zewnątrz interfejs wyższego poziomu.

Ujmując to prosto: GraphQL odpowiada na pytanie „jakie masz dane?”, a Abilities API na „co potrafisz zrobić?”.

#Kiedy używać czego

• REST API: integracje serwer-serwer, aplikacje mobilne, tradycyjne frontendy
• WPGraphQL: złożone pobieranie danych, headless frontendy, architektury Jamstack
• Abilities API: integracja z agentami AI, zautomatyzowane workflow, odkrywanie operacji

#Przyszłość przepływów pracy opartych na AI w WordPressie

#Orkiestracja wielu agentów

W miarę dojrzewania systemów AI zobaczymy wyspecjalizowanych agentów współpracujących nad zadaniami WordPressa: agent treściowy pisze, agent SEO optymalizuje, agent QA recenzuje i testuje. Abilities API daje im wspólny słownik operacji; koordynacja i rozstrzyganie konfliktów pozostają po stronie warstwy, która nimi steruje.

#Implikacje dla marketplace

Ekosystem wtyczek prawdopodobnie wyewoluuje w stronę pakietów abilities, czyli wtyczek istniejących głównie po to, by udostępniać operacje do automatyzacji. Wyobraź sobie wtyczkę bez interfejsu, rejestrującą kilkadziesiąt operacji SEO. Jej recenzja dotyczy wtedy przede wszystkim tego, jakie uprawnienia deklarują permission callbacki.

#WordPress jako backend automatyzacji

Z Abilities API WordPress staje się backendem, który da się orkiestrować, bo jego możliwości są opisane w jednym miejscu i w jednym formacie. Multisite z WooCommerce, LMS, członkostwem i wtyczkami eventowymi zyskuje spójny sposób wystawiania ich na zewnątrz, bez wymyślania osobnego kontraktu dla każdej integracji.

#Integracja z zewnętrznymi usługami AI

Abilities API nie zawiera ogólnej funkcji do wywoływania zdolności zewnętrznego dostawcy. Wtyczka może natomiast odpytać zewnętrzny serwis przez HTTP API WordPressa i opakować to we własną ability. Klucze, timeouty, ponowienia, kontrola kosztów i walidacja odpowiedzi zostają wtedy po stronie wtyczki.

Trzymaj takie wywołanie za wąską operacją domenową. Ability o nazwie media/utworz-zatwierdzony-wariant da się zrecenzować i przetestować. Ogólnego przekaźnika promptów, który przyjmuje dowolną instrukcję i zapisuje wynik prosto w meta wpisu, nie da się ani zrecenzować, ani sensownie ograniczyć.

#Jak zacząć

Na WordPressie 6.9 lub nowszym:

1. Wybierz jedną operację. Zacznij od małej ability tylko do odczytu.
2. Zarejestruj kategorię. Hook wp_abilities_api_categories_init.
3. Zarejestruj ability. Funkcja wp_register_ability() na wp_abilities_api_init.
4. Opisz schematy. Wejście i wyjście w JSON Schema, z opisami po ludzku.
5. Sprawdź uprawnienia. Przetestuj na koncie uprawnionym i nieuprawnionym.
6. Zostaw REST prywatny domyślnie. show_in_rest włączaj dopiero dla realnego konsumenta.
7. Dołóż brakujące kontrole. Limity, audyt i akceptacje to część architektury projektu, nie prezent od rdzenia.

Korzyść pojawia się nawet bez agenta AI: dostajesz spójny kontrakt między komponentami WordPressa a automatyzacją. Wtyczki odnajdą nazwane operacje, obejrzą schematy i wywołają je przez ten sam rejestr, zamiast integrować się z prywatnymi funkcjami cudzego kodu.

Przy tworzeniu wtyczek WordPress warto od początku rozdzielić to, co wtyczka robi, od tego, jak to prezentuje. Podobnie przy tworzeniu stron WordPress i opiece nad WordPress opłaca się z góry ustalić, które operacje mogą kiedykolwiek trafić poza instalację. Po pomoc wdrożeniową napisz przez stronę kontaktu, podając wersję WordPressa, listę wtyczek, planowaną operację, tożsamość wywołującego i wymagany zakres danych. Wycena jest zawsze indywidualna.

Zweryfikowane względem oficjalnego handbooka WordPress Abilities API oraz not programistycznych WordPressa 7.0 i 7.1, 9 sierpnia 2026.