WordPress mostra como unir Abilities, AI Client e MCP em um plugin
Dante Testa
09/08/2026 · 12 min de leitura · 29 visualizações
Um plugin mostra como as peças de IA do WordPress se encaixam
O WordPress Developer Blog publicou em 30 de julho de 2026 um tutorial que reúne, no mesmo plugin, três componentes antes explicados separadamente: Abilities API, WordPress AI Client e MCP Adapter. O projeto de demonstração recebe a URL de uma foto, pede a um modelo de visão que a descreva, gera título e conteúdo e cria um post em rascunho com a imagem destacada. O valor jornalístico está na arquitetura: uma ação escrita uma vez pode servir ao painel, à REST API e a um agente de IA.
O tutorial não anuncia que todo site WordPress passou a ter esse fluxo pronto. Ele oferece código de exemplo, um plugin inicial e uma sequência de implementação. Para acompanhar, a fonte pede WordPress 7.0 ou superior, PHP 8.1 ou mais recente, Composer, Node.js e credenciais de um provedor com modelo capaz de analisar imagens.
Também não há autorização para publicar conteúdo automaticamente. O exemplo usa post_status => 'draft'. Quem adaptar o projeto precisa manter revisão editorial, procedência da imagem, validação da resposta do modelo e limites de permissão como requisitos do produto, não como detalhes posteriores.
O fluxo “Photo to Post” em três abilities
O plugin de oficina registra três unidades de trabalho:
| Ability | Entrada e resultado | Papel no fluxo |
|---|---|---|
describe-image | URL de imagem → descrição | chama um modelo de visão |
generate-post-from-description | descrição → título e corpo | chama geração de texto |
create-post-from-photo | URL e orientação → rascunho | compõe as duas anteriores |
A terceira não chama o modelo diretamente. Ela busca as duas abilities menores com wp_get_ability() e executa cada uma por meio de WP_Ability::execute(). Só depois entrega título, conteúdo e URL a uma função que cria o rascunho e envia a imagem para a biblioteca de mídia.
Essa composição evita concentrar tudo em um callback enorme. A descrição de imagem pode ser usada por outra tela; a geração de texto pode receber descrições de outra origem; o orquestrador decide a ordem e trata falhas. Para plugins de WordPress com IA, o padrão ajuda a testar partes isoladas e a conceder permissões diferentes para leitura, geração e gravação.
Há uma consequência prática: cada ability precisa de contrato claro. O tutorial registra rótulo, descrição, categoria, esquema de entrada, esquema de saída, callback de execução e permission_callback. Um agente não deveria depender de adivinhação sobre formato ou efeito da ferramenta.
O AI Client separa o plugin do provedor
O WordPress AI Client é uma biblioteca PHP com API uniforme para modelos de diferentes fornecedores. No exemplo, wp_ai_client_prompt() recebe instrução e arquivo e retorna texto. O plugin não chama diretamente um endpoint específico de OpenAI, Anthropic ou Google.
Essa abstração não significa que todos os modelos se comportam da mesma forma. A própria fonte aponta uma diferença de transporte: provedores com visão podem exigir que a imagem seja enviada em linha, como data URI, em vez de aceitar uma URL remota. Para manter o callback mais portátil, o exemplo baixa a imagem com wp_remote_get(), verifica resposta e tipo MIME, codifica o corpo em base64 e o anexa ao prompt.
O site ainda precisa de um provedor configurado. Desde o WordPress 7.0, a tela de Connectors oferece um lugar central para credenciais de serviços externos. Plugins de conector existem para provedores como OpenAI, Anthropic, Google, Ollama, OpenRouter e Mistral. A escolha deve incluir um modelo com visão para a etapa de descrição.
Centralizar conectores reduz páginas de configuração duplicadas, mas não remove responsabilidade por segredos. Chaves não devem aparecer em repositórios, logs, prompts, tickets ou conteúdo do post. Administradores precisam saber qual plugin armazena a credencial, quais capacidades ele oferece e como revogar o acesso.
O repositório oficial do PHP AI Client descreve geração de texto, tratamento uniforme de capacidades e eventos antes e depois da geração. Esses eventos podem sustentar observabilidade, mas logs devem excluir prompt sensível, arquivo privado e resposta que contenha dados pessoais.
A primeira fronteira é buscar a imagem com segurança
O callback de visão começa com uma URL fornecida pelo usuário ou agente. Esse ponto merece atenção porque uma URL não é apenas conteúdo: ela faz o servidor realizar uma requisição. O exemplo usa wp_remote_get(), timeout de 30 segundos, valida o status HTTP, rejeita corpo vazio e tenta determinar um MIME de imagem.
Ao adaptar, acrescente uma política de origem. Restrinja esquemas a HTTP e HTTPS, use funções de validação segura do WordPress, limite tamanho do download, aceite apenas formatos necessários e recuse endereços internos ou destinos que possam virar SSRF. Não confie apenas na extensão do arquivo ou no cabeçalho enviado pelo servidor remoto.
Também defina procedência editorial. Uma URL tecnicamente acessível não concede licença para reutilizar a imagem. O fluxo precisa registrar autor, página de origem, licença, finalidade e alt text. Se a imagem for privada, confirme base legal e controle de acesso antes de enviá-la a um provedor externo.
O tutorial transforma a imagem original em imagem destacada por meio de media_sideload_image(). Essa decisão é adequada ao exemplo, mas um produto real deve checar duplicidade, tamanho, metadados e direitos de uso antes de persistir o arquivo.
A segunda fronteira é tratar a saída como dado não confiável
O callback que gera o post pede um objeto JSON com duas chaves: title e content. Mesmo com a instrução para não usar cercas Markdown, a implementação remove cercas caso o modelo as acrescente e tenta extrair um objeto antes de chamar json_decode().
Esse tratamento reconhece que modelos são probabilísticos. Ainda assim, conseguir decodificar JSON não confirma qualidade ou segurança. Antes de salvar, valide tipos, comprimento, marcação permitida, URLs, blocos, idioma e alegações factuais. Um objeto sintaticamente correto pode conter título enganoso, HTML inadequado ou informação inventada.
O AI Client retorna WP_Error em falhas no wrapper usado pelo tutorial, e cada callback verifica is_wp_error(). O orquestrador interrompe a sequência quando uma ability não existe ou devolve erro. Esse comportamento evita criar um post a partir de uma descrição ausente, mas mensagens expostas ao usuário não devem revelar chave, payload completo ou detalhes internos do provedor.
No último passo, o exemplo aplica sanitize_text_field() ao título e cria o post como rascunho. O corpo precisa de política própria. Sanitização deve respeitar o conjunto de blocos e HTML aceitos pelo produto, sem confiar no fato de a resposta ter sido solicitada em marcação do Editor de Blocos.
Uma ability, três portas de entrada
Depois de registrar show_in_rest => true, o tutorial consulta o catálogo autenticado em /wp-json/wp-abilities/v1/abilities. Uma Application Password permite testar a REST API. Descoberta não elimina autorização: o exemplo usa current_user_can( 'edit_posts' ) nas três abilities.
No painel, o JavaScript carrega @wordpress/core-abilities, espera a promessa ready e usa getAbility() e executeAbility(). A mesma ação que respondeu ao REST passa a atender a tela em Ferramentas. O módulo evita duplicar uma rota específica apenas para a interface administrativa.
Para MCP, o tutorial adiciona meta.mcp.public => true ao orquestrador e instala o MCP Adapter. O cliente recebe endpoint, usuário e Application Password e pode descobrir a ação de criação do rascunho. Em 4 de agosto, o WordPress 7.1 ganhou o metadado geral meta.public; quando Core e MCP Adapter instalados suportarem a herança, ele poderá reduzir configuração duplicada. A versão do ambiente precisa ser verificada antes de trocar o formato mostrado no tutorial.
Essa portabilidade é útil, porém aumenta o alcance do callback. Um erro que antes afetava apenas uma tela passa a ser acionável por REST e agentes. Por isso, regras de autorização, idempotência, limites e auditoria devem morar na própria ability ou em serviços compartilhados, não somente na interface.
Timeout não é o mesmo que processamento robusto
O fluxo faz duas chamadas de IA em sequência e depois baixa uma imagem. A fonte alerta que isso pode ultrapassar o timeout HTTP padrão e adiciona o filtro wp_ai_client_default_request_timeout com 120 segundos.
Aumentar o limite ajuda a oficina, mas não resolve todos os problemas de produção. Uma requisição longa mantém recursos ocupados e pode ser repetida pelo cliente se a conexão cair. Para uso frequente, avalie fila assíncrona, identificador idempotente, progresso, cancelamento e retomada. O agente precisa saber se uma tentativa falhou antes ou depois de criar o rascunho.
Registre estados como pending, describing, generating, saving, review e failed. Se o download da imagem falhar depois que o post foi criado, o tutorial retorna o ID com aviso. Um produto deve mostrar esse estado parcial claramente e oferecer correção segura, sem criar duplicata a cada nova tentativa.
Checklist para transformar a oficina em produto
Separe permissões por efeito
Ler uma imagem, gerar texto e criar post não precisam compartilhar a mesma capacidade. Considere uma ability de geração sem gravação e uma etapa humana que autorize persistência. Publicação deve ser uma ação separada e, de preferência, fora do catálogo padrão do agente.
Trabalhe em rascunho e staging
Mantenha post_status => 'draft' e teste em site não crítico. O agente não deve atualizar conteúdo existente sem alvo explícito, hash ou versão esperada. Para edição, compare estado antes de salvar e preserve histórico.
Defina limites operacionais
Restrinja tamanho e formato da imagem, quantidade por usuário, comprimento de prompt e de resposta, modelos permitidos, custo por chamada e frequência. Um esquema sem máximos deixa o servidor e a conta do provedor expostos a uso acidental ou abusivo.
Valide fatos e direitos
Uma descrição visual pode errar objetos, pessoas e texto. A geração de artigo pode inventar contexto. Exija revisão factual e editorial. Não publique uma imagem apenas porque o modelo conseguiu descrevê-la.
Torne as tentativas auditáveis
Guarde ID da operação, usuário, ability, modelo, tempos, status e custo quando disponível. Não armazene chave nem payload sensível. Para conteúdo jornalístico, registre também fontes usadas para validar o texto final.
Teste recusas
Use uma conta sem edit_posts, uma URL inválida, uma imagem grande demais, um MIME incorreto, resposta que não seja JSON, modelo sem visão e falha no sideload. Confirme que cada caso termina sem publicação, sem segredo na mensagem e sem rascunhos duplicados.
Uma matriz mínima de testes
| Cenário | Resultado esperado |
|---|---|
| usuário autorizado e imagem válida | cria apenas um rascunho revisável |
| usuário sem capacidade | execução recusada antes da gravação |
| URL privada ou arquivo excessivo | download bloqueado por política |
| provedor devolve texto fora do contrato | resposta rejeitada, sem post |
| segunda tentativa com mesmo ID | retoma ou informa resultado existente |
| sideload falha após criar post | estado parcial visível, sem duplicata |
Não é preciso afirmar que esses testes passaram se eles não foram executados. A utilidade da matriz é orientar implementação e revisão. O artigo oficial demonstra o caminho feliz e alguns tratamentos de erro; cada produto precisa construir sua evidência no ambiente real.
Onde Dante ajuda na revisão humana
Em um fluxo editorial, um explicador humano ou personagem pode indicar visualmente que a automação termina em revisão, não em publicação. Isso não muda permissões nem torna conteúdo correto. A presença de Dante nas imagens deste artigo cumpre função didática: separar os blocos e destacar o ponto de decisão humana.
O mesmo princípio vale para a interface. Em vez de um botão genérico “Gerar”, mostre o que será enviado, qual provedor será usado, que post ficará em rascunho e qual etapa depende de aprovação. Clareza visual reduz a chance de o usuário confundir geração com publicação.
Perguntas frequentes
O WordPress 7.0 já cria posts por IA sozinho?
Não. O tutorial monta um plugin de demonstração com bibliotecas e integrações. O site precisa instalar e implementar os componentes, configurar um provedor e definir permissões.
O AI Client escolhe qualquer modelo automaticamente?
Ele abstrai fornecedores e capacidades, mas o ambiente precisa de um conector e de um modelo compatível. Para o exemplo, a etapa de descrição exige visão.
Expor a ability por MCP publica o post?
Não. O callback do exemplo cria rascunho. Publicação seria outra decisão e deve exigir autorização e revisão próprias.
Aumentar o timeout para 120 segundos basta?
É a adaptação mostrada para a oficina. Fluxos frequentes ou críticos devem avaliar execução assíncrona, idempotência e recuperação de estados parciais.
Posso usar qualquer imagem encontrada na web?
Não. Acesso técnico e licença são assuntos diferentes. Confirme origem, permissão e privacidade antes de baixar, enviar ao modelo ou salvar na biblioteca.
O aprendizado é arquitetural
O tutorial de 30 de julho oferece um mapa concreto para plugins WordPress com IA: abilities descrevem tarefas, AI Client abstrai modelos, composição organiza o fluxo, REST e JavaScript reutilizam o contrato, e MCP permite que um agente descubra a mesma ação.
A arquitetura fica útil quando seus limites são preservados. URLs precisam de política segura, respostas de modelo são dados não confiáveis, gravação deve terminar em rascunho e exposição não substitui autorização. Com essas fronteiras, a oficina deixa de ser apenas uma demonstração chamativa e vira uma base compreensível para automações revisáveis.
