WordPress e IA: a Abilities API desde o WordPress 6.9

#O que é a WordPress Abilities API?

#O problema com as abordagens atuais

A WordPress REST API é poderosa mas orientada a recursos. Expõe endpoints como /wp/v2/posts e /wc/v3/products, operações CRUD sobre objetos de dados. Um agente de IA pode usar estes endpoints, mas precisa de ser pré-programado para saber o que cada endpoint faz, que parâmetros aceita e como encadear várias chamadas para atingir um objetivo.

O WPGraphQL melhora isto ao permitir consultas flexíveis, mas partilha a mesma limitação de fundo: descreve dados, não capacidades.

Considere este cenário: quer que um agente de IA «escreva um artigo sobre jardinagem de primavera, o otimize para SEO, adicione uma imagem de destaque e agende a publicação para a próxima terça-feira». Com a REST API, o agente precisa de:

1. Conhecer o endpoint /wp/v2/posts e os seus parâmetros
2. Saber que os dados de SEO residem num campo meta controlado pelo Yoast ou pelo RankMath
3. Saber como carregar media via /wp/v2/media
4. Conhecer o formato de data para agendamento
5. Encadear estas chamadas pela ordem correta

Com a Abilities API, um plugin regista operações estreitas, do género conteudo/criar-rascunho ou media/anexar-imagem. Uma integração autenticada lista as abilities expostas por REST, inspeciona os esquemas e chama o endpoint adequado. O que muda é o contrato: deixa de ser preciso decorar URLs e formatos internos. O planeamento continua do lado de quem chama, a não ser que o plugin ofereça uma operação de nível mais alto.

#Visão geral da arquitetura

A API tem quatro peças. A categoria agrupa operações relacionadas. A ability transporta um identificador único no formato namespace/nome-da-ability, uma etiqueta, uma descrição, esquemas e callbacks. O registo permite que o código WordPress descubra as abilities disponíveis. A exposição REST é um transporte opcional para sistemas externos autenticados.

O registo acontece em hooks dedicados: as categorias em wp_abilities_api_categories_init com wp_register_ability_category(), as abilities em wp_abilities_api_init com wp_register_ability(). A temporização importa mais do que parece. Registar num hook genérico de carregamento de plugin pode acontecer antes de os registos estarem prontos, e a ability simplesmente não aparece.

O manual oficial documenta a API do lado do servidor para o WordPress 6.9 e versões seguintes. Um registo típico fica assim:

add_action('wp_abilities_api_categories_init', function () {
    wp_register_ability_category('analytics', [
        'label'       => __('Analítica', 'meu-plugin'),
        'description' => __('Leitura de dados de analítica deste site.', 'meu-plugin'),
    ]);
});

add_action('wp_abilities_api_init', function () {
    wp_register_ability('meu-plugin/gerar-relatorio', [
        'label'        => __('Gerar relatório analítico', 'meu-plugin'),
        'description'  => __('Cria um relatório de analítica para o período indicado.', 'meu-plugin'),
        'category'     => 'analytics',
        'input_schema' => [
            'type'       => 'object',
            'properties' => [
                'start_date' => ['type' => 'string', 'format' => 'date'],
                'end_date'   => ['type' => 'string', 'format' => 'date'],
            ],
            'required'   => ['start_date', 'end_date'],
        ],
        'output_schema' => [
            'type'       => 'object',
            'properties' => ['report_url' => ['type' => 'string', 'format' => 'uri']],
        ],
        'execute_callback'    => 'meu_plugin_gerar_relatorio',
        'permission_callback' => fn () => current_user_can('manage_options'),
    ]);
});

Repare no que não está aqui: não há chave de limite de taxa nem de auditoria. Essas peças pertencem ao projeto, não à API.

#Descoberta e execução por REST

A exposição REST está desligada por predefinição. O plugin adere ability a ability, através de meta.show_in_rest. Quando está ativa, um cliente autenticado lista as abilities em /wp-json/wp-abilities/v1/abilities, obtém uma ability pelo namespace e pelo nome, e executa-a no respetivo endpoint /run. O método depende das anotações declaradas.

curl --user "utilizador:palavra-passe-de-aplicacao" \
  https://exemplo.pt/wp-json/wp-abilities/v1/abilities

Continuam a valer os métodos de autenticação da REST API do WordPress: cookie na mesma origem, Application Passwords para acesso externo, ou um plugin de autenticação personalizado. Listar uma ability não dá autorização para a executar, porque o WordPress avalia sempre o permission_callback dessa ability para o utilizador atual.

Na prática, esta distinção resolve muita coisa. Uma ability interna, usada só por outro código PHP, fica com show_in_rest a falso. Uma ability de leitura pode ser exposta a uma conta de serviço com capabilities limitadas. Uma operação destrutiva merece um permission callback mais estreito e controlos adicionais na aplicação.

#Ligar agentes de IA ao WordPress

#O que uma camada MCP herda da Abilities API

O Model Context Protocol define como agentes de IA descobrem e utilizam ferramentas externas. A Abilities API fornece descrições estruturadas e esquemas JSON, e são esses campos que ajudam uma integração a traduzir uma ability para o formato de ferramenta que o agente espera.

Convém dizê-lo sem rodeios: o núcleo do WordPress não expõe automaticamente um endpoint MCP nem um manifesto próprio de nenhum fornecedor. Instalar o WordPress 6.9 não põe um servidor MCP a correr.

#A ponte é trabalho de integração

Uma ponte tem de se autenticar no WordPress, escolher que abilities permite, traduzir esquemas, impor os seus próprios limites e devolver erros compreensíveis. A regra prática é expor menos operações do que o utilizador WordPress consegue executar, não todas as que a listagem revelar.

Um assistente de apoio ao cliente, por exemplo, recebe uma consulta de produto só de leitura e uma operação que cria um pedido de assistência em rascunho. Reembolsos, eliminação de utilizadores e alterações de configuração ficam de fora da ponte. Esta separação é bem mais fácil de rever do que entregar uma conta de administrador a um agente genérico.

Para sistemas que usam chamadas de função genéricas, os esquemas declarados mapeiam de forma direta para parâmetros de ferramentas, mas a conversão, os tempos limite e o tratamento de erros continuam a ser trabalho da ponte.

#Casos de uso práticos

#Fluxos de trabalho de criação de conteúdo

Em vez de a IA gerar texto bruto que um humano cola no WordPress, uma camada de orquestração encadeia abilities registadas por plugins diferentes:

Utilizador: "Cria um guia técnico sobre controlo biológico de pragas para o nosso blogue de jardinagem"

Fluxo de trabalho orquestrado:
1. pesquisar_topicos → encontra subtópicos em tendência e lacunas da concorrência
2. gerar_conteudo → cria o artigo com cabeçalhos e referências de imagens
3. otimizar_seo → adiciona meta descrição, palavra-chave foco, links internos
4. gerar_imagem_destaque → cria a imagem de destaque
5. criar_rascunho → guarda como rascunho com todos os metadados
6. notificar_editor → envia notificação de revisão à equipa editorial

Cada ability vem de um plugin diferente: o SEO do RankMath, as imagens de um plugin de media com IA, as notificações de um plugin de workflow. A Abilities API dá o vocabulário comum. A ordem, os erros a meio e as repetições são de quem orquestra.

#Gestão de loja WooCommerce

Em comércio eletrónico, o mesmo padrão aplica-se a operações do dia a dia:

• Gestão de inventário: monitorizar níveis de stock, gerar sugestões de reabastecimento, atualizar quantidades
• Otimização de preços: analisar preços da concorrência, sugerir ajustes, aplicar alterações em massa
• Descrições de produtos: gerar e atualizar descrições com base em atributos e objetivos de SEO
• Serviço ao cliente: atualizar estado de encomendas, gerar etiquetas de envio, preparar reembolsos para aprovação
• Análise de vendas: gerar relatórios, identificar tendências, sugerir promoções

Um proprietário de loja poderia pedir «analisa os produtos que não venderam em 90 dias e sugere se devem ter desconto, ser agrupados ou descontinuados». A leitura resolve-se com abilities de consulta e permissões estreitas. A parte que altera preços merece uma operação separada, com outra verificação de permissões e, provavelmente, aprovação humana.

#Automatização de SEO

Tarefas que antes exigiam trabalho manual tornam-se operações com nome próprio:

• analisar_seo_pagina, devolve pontuação, meta tags em falta e densidade de palavras-chave
• sugerir_links_internos, encontra conteúdo relacionado para ligação cruzada
• verificar_links_partidos, deteta 404 e sugere substituições
• gerar_dados_estruturados, cria JSON-LD
• otimizar_imagens, comprime e acrescenta texto alternativo
• auditar_atualidade, marca conteúdo desatualizado para revisão

Note que quase todas são de leitura. É a fronteira sensata para começar: primeiro o diagnóstico, só depois quem pode aplicar correções.

#Implementar abilities personalizadas no seu plugin

#Registo básico de uma ability

Uma ability precisa de nome único, categoria, metadados legíveis por humanos, esquemas, callback de execução e callback de permissões. A categoria regista-se primeiro.

add_action('wp_abilities_api_categories_init', function () {
    wp_register_ability_category('editorial', [
        'label'       => __('Editorial', 'wppoland'),
        'description' => __('Fila de revisão e publicação de conteúdo.', 'wppoland'),
    ]);
});

add_action('wp_abilities_api_init', function () {
    wp_register_ability('wppoland/fila-de-revisao', [
        'label'        => __('Listar conteúdo parado em revisão', 'wppoland'),
        'description'  => __('Devolve o conteúdo pendente de revisão há mais dias do que o limite indicado.', 'wppoland'),
        'category'     => 'editorial',
        'input_schema' => [
            'type'       => 'object',
            'properties' => [
                'tipo_de_conteudo' => [
                    'type' => 'string',
                    'enum' => ['post', 'page'],
                ],
                'parado_ha_dias' => [
                    'type'        => 'integer',
                    'minimum'     => 1,
                    'maximum'     => 90,
                    'description' => 'Dias em revisão a partir dos quais o item entra na lista.',
                ],
            ],
            'required'   => ['tipo_de_conteudo', 'parado_ha_dias'],
        ],
        'output_schema' => [
            'type'       => 'object',
            'properties' => [
                'total' => ['type' => 'integer'],
                'itens' => [
                    'type'  => 'array',
                    'items' => [
                        'type'       => 'object',
                        'properties' => [
                            'id'              => ['type' => 'integer'],
                            'titulo'          => ['type' => 'string'],
                            'dias_em_revisao' => ['type' => 'integer'],
                            'autor'           => ['type' => 'string'],
                        ],
                    ],
                ],
            ],
        ],
        'execute_callback'    => 'wppoland_fila_de_revisao',
        'permission_callback' => fn () => current_user_can('edit_others_posts'),
        'meta'                => [
            'show_in_rest' => false,
            'annotations'  => ['readonly' => true],
        ],
    ]);
});

A capability escolhida diz muito sobre a operação. edit_others_posts é o mínimo defensável aqui, porque a lista mostra rascunhos alheios; manage_options seria excessivo e daria a quem chama muito mais do que a leitura de uma fila. Escreva etiquetas traduzíveis e teste com um utilizador autorizado e outro sem autorização. Se nenhum cliente externo precisa da operação, deixe show_in_rest a falso e chame a ability internamente:

$ability = wp_get_ability('wppoland/fila-de-revisao');

if ($ability) {
    $resultado = $ability->execute([
        'tipo_de_conteudo' => 'post',
        'parado_ha_dias'   => 14,
    ]);
}

O permission_callback faz parte do registo da ability. O manual documenta o parâmetro, não o comportamento em chamadas internas, por isso trate a verificação como responsabilidade de quem chama e teste-a no seu próprio código.

#A composição pertence a quem chama

O núcleo trata de registo, descoberta, validação e execução. Não constrói um planeador de fluxos a partir de um campo de dependências declarado. Se várias operações têm de correr por ordem fixa, há duas saídas honestas: uma única ability no servidor que seja dona da transação, ou uma camada de orquestração revista a chamar abilities separadas.

Para alterações acopladas, a primeira opção é mais segura: um callback único valida a entrada completa, para no primeiro erro e devolve um resultado estruturado. A composição do lado do cliente serve para leituras independentes, mas obriga quem chama a tratar falhas parciais e repetições.

#Controlos operacionais são responsabilidade do projeto

Não conte com middleware não documentado nem com filtros mágicos antes da invocação. Ponha a validação de domínio no callback de execução, aplique limites de taxa no gateway ou no proxy inverso, e registe apenas os campos de auditoria que o projeto pode reter.

#Considerações de segurança para acesso externo

#Autenticação e autorização

A autenticação responde a quem é quem chama. O permission_callback da ability responde se esse utilizador WordPress pode executar aquela operação. Mantenha as duas verificações. Uma credencial de administrador partilhada anula a razão de ser de um contrato estreito.

A visibilidade REST é a terceira fronteira. Uma ability registada permanece interna enquanto show_in_rest for falso, e essa flag merece ser item obrigatório de revisão de código.

#Aprovação humana para alterações sensíveis

O núcleo do WordPress não fornece uma fila genérica de aprovação. Se um reembolso, uma eliminação ou uma alteração de configuração precisam de confirmação humana, essa fila constrói-se na aplicação de domínio: a ability cria um pedido pendente e um utilizador autorizado aprova-o através de uma ação de administração separada.

Mantenha aprovação e execução separadas. O registo de aprovação deve identificar a alteração proposta, quem reviu, o prazo de validade e o resumo exato da entrada. Reaproveitar uma aprovação para uma entrada modificada reabre a falha que o processo existia para fechar.

#Trilho de auditoria

A API não cria um trilho de auditoria completo de forma automática. Decida o que tem de ficar registado nas operações expostas ao exterior:

• utilizador WordPress autenticado ou conta de serviço,
• nome da ability e identificador de correlação do pedido,
• categoria do resultado e duração,
• referência de aprovação para alterações sensíveis,
• data e hora e versão relevante da aplicação.

Evite registar segredos, prompts completos ou dados pessoais desnecessários. A retenção e o acesso aos registos precisam de um responsável, não apenas de uma tabela.

#Sanitização de input

A Abilities API valida a entrada contra o esquema JSON declarado antes de executar. Isso verifica a forma, não torna uma string segura para todos os destinos. Aplique as funções de sanitização e escape adequadas ao contexto real, como sanitize_text_field() ou wp_kses_post(), e use consultas preparadas na base de dados.

#O que o WordPress 7.1 acrescenta a esta superfície

A abertura deste artigo resumia o lado do servidor a três funções e dois hooks. A 19 de agosto de 2026, o WordPress 7.1 alarga a contagem sem mexer no modelo: uma chave nova no registo, uma função de descoberta com argumentos e dois filtros novos.

A chave chama-se public e vive dentro de meta. A nota de programador de 4 de agosto descreve-a assim: «The flag provides a single, high-level way to indicate that an ability is intended to be available to external clients such as the REST API.» Ou seja, uma forma única e de alto nível de declarar que a ability se destina a clientes externos, a começar pela REST API.

A palavra a sublinhar é intenção. public regista que a operação pode ser alcançada a partir do exterior, por REST, por um adaptador MCP ou por um agente, e não cria nenhum desses consumidores. O núcleo continua sem servidor MCP, sem âmbitos OAuth próprios de agentes, sem limites de taxa, sem trilho de auditoria e sem fila de aprovação. Nada disso muda em 7.1.

A chave também não substitui as flags por canal. show_in_rest mantém-se totalmente suportada e prevalece, e a resolução no núcleo é literalmente esta:

$show_in_rest = $meta['show_in_rest'] ?? $meta['public'] ?? false;

A segunda novidade é wp_get_abilities( $args ). Antes de 7.1, quem precisava de um subconjunto tinha de ir buscar o registo inteiro e filtrá-lo à mão com array_filter(). O argumento é opcional e aceita:

Vale a pena citar a regra de combinação: «Conditions are combined using AND logic. An ability must satisfy every supplied argument to be included.» As condições acumulam-se e a ability tem de satisfazer todos os argumentos indicados para entrar na lista.

A nota de 5 de agosto faz ainda questão de deixar escrito que filtrar decide o que aparece na descoberta, não quem pode executar. Essa resposta continua a vir do permission_callback, avaliado a cada chamada. Os dois filtros novos, wp_get_abilities_item_include e wp_get_abilities_result, permitem intervir na seleção e no resultado, e rest_abilities_collection_params estende o esquema dos argumentos de coleção da REST API.

#Comparação com abordagens existentes

#REST API vs. Abilities API

#WPGraphQL vs. Abilities API

O WPGraphQL destaca-se na consulta flexível de dados, com os clientes a pedir exatamente aquilo de que precisam numa única consulta. A Abilities API não é um substituto. As abilities podem até usar GraphQL internamente para obter dados, enquanto expõem uma interface de nível superior.

Simplificando: o GraphQL responde a «que dados tens?», a Abilities API responde a «o que consegues fazer?».

#Quando usar o quê

• REST API: integrações servidor a servidor, aplicações móveis, consumo frontend tradicional
• WPGraphQL: obtenção complexa de dados, frontends headless, arquiteturas Jamstack
• Abilities API: integração com agentes de IA, fluxos de trabalho automatizados, descoberta de capacidades

#O futuro dos fluxos de trabalho WordPress orientados por IA

#Orquestração multi-agente

À medida que os sistemas de IA amadurecem, veremos vários agentes especializados a colaborar em tarefas WordPress: um trata da escrita, outro da otimização, outro das imagens, outro da revisão. A Abilities API fornece o vocabulário partilhado, não a coordenação.

#Implicações para o marketplace

O ecossistema de plugins deve evoluir para incluir bundles de abilities, plugins que existem sobretudo para expor operações a sistemas automatizados: sem interface visível, apenas dezenas de operações registadas. O valor desloca-se das interfaces para humanos para as capacidades para máquinas, e a revisão de segurança passa a ser o critério de qualidade que conta.

#WordPress como backend orquestrável

Com um registo de operações comum, um multisite com WooCommerce, LMS, subscrições e eventos passa a ter um catálogo inspecionável. A parte difícil deixa de ser técnica e passa a ser de governação: quem autoriza o quê, e com que rasto.

#Integração com serviços de IA externos

A Abilities API não inclui nenhuma função genérica para invocar abilities de serviços externos. Um plugin pode chamar um serviço externo com a HTTP API do WordPress e envolver essa chamada na sua própria ability, mas continua responsável por credenciais, tempos limite, repetições, controlo de custos e validação da resposta.

'execute_callback' => function (array $input) {
    $resposta = wp_remote_post('https://api.exemplo.pt/v1/imagens', [
        'timeout' => 20,
        'headers' => ['Authorization' => 'Bearer ' . wppoland_obter_chave()],
        'body'    => wp_json_encode(['prompt' => $input['prompt']]),
    ]);

    return is_wp_error($resposta)
        ? $resposta
        : wppoland_validar_variante(wp_remote_retrieve_body($resposta));
},

Mantenha a chamada externa atrás de uma operação de domínio estreita. Uma ability media/criar-variante-aprovada é muito mais fácil de rever do que um relé de prompts que aceita instruções arbitrárias e escreve o resultado nos metadados do artigo.

#Começar hoje

Para WordPress 6.9 ou superior:

1. Escolha uma operação. Comece por uma ability pequena e só de leitura.
2. Registe a categoria. Use wp_abilities_api_categories_init.
3. Registe a ability. Use wp_register_ability() em wp_abilities_api_init.
4. Defina esquemas. Descreva entrada e saída com JSON Schema.
5. Verifique permissões. Teste com utilizadores autorizados e não autorizados.
6. Mantenha o REST privado por predefinição. Ative show_in_rest apenas para um consumidor externo real.
7. Acrescente o que falta. Limites de taxa, registos de auditoria e aprovações pertencem à arquitetura do projeto.

O benefício prático é um contrato consistente entre componentes WordPress e automatização externa, útil mesmo sem nenhum agente de IA envolvido: os plugins passam a descobrir operações com nome próprio, a inspecionar esquemas e a chamá-las pelo mesmo registo.

Se está a preparar um plugin para este modelo, siga as boas práticas de desenvolvimento WordPress e trate a exposição REST como decisão de segurança. Para manutenção WordPress ou apoio na implementação, envie a versão do WordPress, a lista de plugins, a operação pretendida e os acessos a dados necessários através da página de contacto.

Verificado a 9 de agosto de 2026 contra o manual oficial da Abilities API do WordPress e as notas de programador do WordPress 7.0 e 7.1.