Um agente de IA só consegue usar uma função de forma confiável quando entende três coisas: o que ela faz, quais dados deve enviar e o que receberá como resposta. É justamente essa ponte que a Abilities API começa a construir dentro do WordPress.
Introduzida no WordPress 6.9 e ampliada no WordPress 7.1, a API permite que plugins registrem suas funcionalidades como capacidades padronizadas e legíveis por máquinas. Cada capacidade — chamada de ability — pode ter descrição, esquema de entrada, esquema de saída, regra de permissão e função de execução.
Na prática, uma função que antes existia apenas como código interno de um plugin passa a poder ser descoberta, compreendida e, quando autorizado, executada por automações, outros plugins e agentes de IA.
Isso não coloca um chatbot dentro do WordPress automaticamente. A mudança é mais fundamental: o WordPress passa a oferecer uma linguagem comum para descrever o que o site e seus plugins sabem fazer.
O problema que a Abilities API resolve
Imagine um plugin de e-commerce com funções para consultar estoque, calcular frete e cancelar pedidos. Outro sistema interessado nessas ações normalmente precisaria conhecer classes PHP específicas, endpoints próprios ou uma documentação escrita exclusivamente para aquela integração.
Com a Abilities API, o plugin pode registrar capacidades como:
minha-loja/consultar-estoque;minha-loja/calcular-frete;minha-loja/cancelar-pedido.
Cada uma pode declarar os dados aceitos e retornados. A capacidade de cancelamento também pode informar que é destrutiva e exigir uma permissão diferente daquela usada para uma simples consulta.
Essa estrutura cria um catálogo de ações. Um agente não precisa adivinhar que função chamar nem inventar o formato dos argumentos: ele pode consultar a definição disponibilizada pelo próprio site.
Abilities não são as capabilities de usuários
Os nomes são parecidos, mas representam conceitos diferentes.
As capabilities tradicionais do WordPress, como edit_posts e manage_options, fazem parte do sistema de papéis e permissões. Elas respondem se um usuário pode realizar determinada classe de ação.
Uma ability descreve uma unidade executável de funcionalidade. Sua permission_callback pode usar current_user_can() para consultar as capabilities tradicionais antes de autorizar a execução.
Em resumo:
- capability: permissão atribuída a um usuário;
- ability: ação registrada, descrita e potencialmente executável;
permission_callback: regra que liga a ação ao sistema de autorização.
Anatomia de uma ability
Uma ability é registrada com um nome no formato namespace/nome-da-acao. A definição normalmente contém:
label: nome curto apresentado a pessoas e ferramentas;description: explicação precisa do que a ação faz;input_schema: formato dos argumentos aceitos;output_schema: formato da resposta;execute_callback: código que realiza a ação;permission_callback: código que decide se o usuário pode executá-la;- metadados, incluindo exposição pela REST API e anotações de comportamento.
Os esquemas usam JSON Schema. Além de documentar a interface, eles permitem validar entrada e saída. Para agentes, isso reduz ambiguidades. Para desenvolvedores, ajuda a detectar contratos quebrados antes que uma resposta inconsistente se espalhe pela integração.
Criando a primeira ability
O exemplo abaixo registra uma ação somente de leitura que retorna informações públicas básicas do site. Ele requer WordPress 6.9 ou mais recente.
<?php
/**
* Plugin Name: WP24Horas Abilities Demo
* Description: Exemplo introdutório de uso da Abilities API.
* Requires at least: 6.9
*/
add_action( 'wp_abilities_api_categories_init', 'wp24_register_ability_category' );
function wp24_register_ability_category(): void {
wp_register_ability_category(
'wp24-site',
array(
'label' => __( 'Informações do site', 'wp24-abilities-demo' ),
'description' => __( 'Ações de consulta sobre o site WordPress.', 'wp24-abilities-demo' ),
)
);
}
add_action( 'wp_abilities_api_init', 'wp24_register_site_summary_ability' );
function wp24_register_site_summary_ability(): void {
wp_register_ability(
'wp24/site-summary',
array(
'label' => __( 'Resumo do site', 'wp24-abilities-demo' ),
'description' => __( 'Retorna o nome, a URL e o idioma do site.', 'wp24-abilities-demo' ),
'category' => 'wp24-site',
'input_schema' => array(),
'output_schema' => array(
'type' => 'object',
'additionalProperties' => false,
'required' => array( 'name', 'url', 'language' ),
'properties' => array(
'name' => array( 'type' => 'string' ),
'url' => array( 'type' => 'string', 'format' => 'uri' ),
'language' => array( 'type' => 'string' ),
),
),
'execute_callback' => 'wp24_get_site_summary',
'permission_callback' => '__return_true',
'meta' => array(
'show_in_rest' => true,
'annotations' => array(
'readonly' => true,
'destructive' => false,
'idempotent' => true,
),
),
)
);
}
function wp24_get_site_summary(): array {
return array(
'name' => get_bloginfo( 'name' ),
'url' => home_url( '/' ),
'language' => get_bloginfo( 'language' ),
);
}O registro acontece nos hooks próprios da API. Isso garante que categorias e abilities sejam adicionadas depois que seus respectivos registros estiverem disponíveis.
O exemplo usa __return_true porque retorna informações públicas. Não copie essa permissão para ações administrativas, privadas ou destrutivas.
Descoberta e execução pela REST API
Quando show_in_rest está habilitado, sistemas externos autenticados podem descobrir abilities no namespace wp-abilities/v1.
Para listar as ações expostas:
GET /wp-json/wp-abilities/v1/abilitiesPara consultar a definição de uma ação:
GET /wp-json/wp-abilities/v1/abilities/wp24/site-summaryE, por ser uma ação marcada como somente leitura, sua execução usa GET:
GET /wp-json/wp-abilities/v1/abilities/wp24/site-summary/runOs endpoints da Abilities API exigem usuário autenticado. A execução também passa pela permission_callback definida para cada ação. A documentação oficial apresenta Application Passwords como uma opção para acesso externo, além dos demais métodos de autenticação suportados pela REST API do WordPress.
Por padrão, uma ability não é exposta pela REST API. O desenvolvedor precisa optar por isso com show_in_rest => true. Essa escolha deve ser deliberada: uma ação útil internamente não precisa necessariamente estar disponível para clientes externos.
O que muda no WordPress 7.1
A base da Abilities API chegou no WordPress 6.9. O WordPress 7.1 não cria a API, mas torna seu ciclo de execução mais extensível com quatro novos filtros:
| Filtro | Papel no ciclo de execução |
|---|---|
wp_pre_execute_ability |
Interrompe antecipadamente a execução e pode devolver um resultado próprio |
wp_ability_normalize_input |
Transforma a entrada normalizada antes da validação |
wp_ability_permission_result |
Ajusta ou substitui o resultado da verificação de permissão |
wp_ability_execute_result |
Transforma ou recupera o resultado antes da validação da saída |
Esses pontos de extensão são especialmente relevantes para sistemas que ficam entre o agente e a função final. Um plugin pode, por exemplo, adicionar auditoria, uma política de aprovação, normalização específica de um protocolo ou tratamento padronizado de falhas.
Também aumentam a responsabilidade do desenvolvedor. Alterar globalmente entrada, permissão ou resultado pode afetar abilities registradas por outros plugins. Filtros devem verificar a identidade da ability e retornar cedo quando a ação não estiver dentro de seu escopo.
Por que isso é útil para agentes de IA
Um agente precisa de ferramentas bem definidas. Para cada ferramenta, ele precisa saber:
- quando deve usá-la;
- quais parâmetros são válidos;
- que resposta receberá;
- quais restrições se aplicam;
- se a ação apenas consulta ou modifica alguma coisa.
A Abilities API fornece boa parte desse contrato dentro do próprio WordPress. Um adaptador pode converter abilities em ferramentas disponíveis para um agente ou protocolo externo sem exigir uma integração artesanal para cada função.
Isso não elimina a camada de integração. A API não decide qual modelo usar, não cria um agente completo e não substitui autenticação, confirmação humana ou políticas de negócio. Ela padroniza a superfície de capacidades sobre a qual essas camadas podem ser construídas.
Segurança: o agente não deve receber um cheque em branco
Expor funções de um site a automações exige mais cuidado do que escrever uma boa descrição. Algumas regras devem ser tratadas como obrigatórias:
- use a
permission_callbackmais restritiva compatível com a ação; - não confie no schema como substituto de autorização e sanitização;
- marque corretamente ações somente de leitura, destrutivas e idempotentes;
- mantenha
show_in_restdesativado quando o acesso externo não for necessário; - use credenciais próprias para a integração, com privilégios mínimos;
- registre tentativas, autorizações e resultados de ações sensíveis;
- exija confirmação humana para exclusão, publicação, compra, reembolso e outras ações de alto impacto;
- não envie segredos ou dados pessoais desnecessários ao modelo de IA.
Uma descrição como “remove um pedido” não é controle de segurança. Quem decide se a ação pode ocorrer é o WordPress, por meio da identidade autenticada, da permission_callback e das regras adicionais da aplicação.
Onde estão as oportunidades para plugins
A primeira onda de adoção provavelmente não será composta apenas por plugins “de IA”. Plugins tradicionais também podem tornar suas operações mais interoperáveis.
Alguns exemplos:
- e-commerce: consultar estoque, preparar cupom, calcular frete ou solicitar reembolso;
- SEO: analisar metadados, encontrar páginas sem descrição ou propor atualizações;
- formulários: listar envios, classificar solicitações ou iniciar um fluxo de atendimento;
- membros: consultar plano, renovar acesso ou suspender uma assinatura;
- conteúdo: localizar rascunhos, montar briefing, criar uma revisão ou agendar publicação;
- manutenção: executar diagnóstico, limpar um cache específico ou verificar integridade.
O valor não está em registrar toda função interna. Está em selecionar unidades de trabalho estáveis, específicas e seguras, com contratos que continuem compreensíveis mesmo fora da interface original do plugin.
Checklist para uma ability preparada para agentes
Antes de publicar uma capacidade, confirme:
- o nome representa uma única ação, e não um comando genérico;
- a descrição explica o efeito e as limitações;
- entrada e saída têm schemas completos;
- a resposta não inclui dados desnecessários;
- a permissão é verificada no momento da execução;
- os metadados descrevem corretamente efeitos colaterais;
- erros são previsíveis e não revelam informações sensíveis;
- a ação pode ser auditada;
- operações destrutivas exigem uma etapa de confirmação;
- a REST API só foi habilitada quando realmente necessária.
A camada de descoberta chegou; o ecossistema ainda será construído
A Abilities API é uma peça de infraestrutura, não um produto final de IA. Sua importância está em tornar funções do WordPress mais fáceis de descrever, descobrir e executar de maneira padronizada.
Para desenvolvedores de plugins, este é um bom momento para mapear quais operações fariam sentido como abilities. Para agências e empresas, é a oportunidade de preparar integrações antes que cada plataforma crie seu próprio conector incompatível.
No próximo artigo da série, construiremos um plugin completo com uma ability parametrizada, validação, autenticação pela REST API e testes de execução.
Nota de versão: este artigo foi preparado durante o ciclo de Release Candidate do WordPress 7.1. O plugin de demonstração e o filtro
wp_ability_execute_resultforam validados em ambiente isolado com WordPress 7.1-RC1 e PHP 8.3. O lançamento final permanece programado para 19 de agosto de 2026; confirme eventuais alterações no calendário e nas Dev Notes antes da publicação.
