Colocar um agente de IA diante do WordPress não é apenas conectar um modelo a um endpoint. Em produção, cada camada precisa limitar a seguinte: o agente propõe, o bridge valida, o WordPress autoriza e a Ability executa um contrato pequeno e auditável.
Este guia fecha a série WordPress para Agentes de IA com uma arquitetura de referência baseada no que testamos nas etapas anteriores: Abilities com schemas fechados, Application Passwords, bridge MCP com allowlist e plugins reais validados do WordPress 6.8.3 ao 7.1-RC1.
Arquitetura de referência
O fluxo recomendado tem quatro zonas de confiança:
| Zona | Responsabilidade | O que não deve fazer |
|---|---|---|
| cliente e agente | interpretar a intenção e solicitar uma ferramenta | armazenar a senha do WordPress no prompt |
| bridge MCP | descobrir ferramentas permitidas, validar entrada e aplicar limites | repassar credenciais recebidas do modelo |
| WordPress REST e Abilities API | autenticar a identidade e verificar permissões | confiar no nome ou na descrição da ferramenta |
| plugin e serviços | executar a operação de negócio e registrar o resultado | aceitar parâmetros fora do schema |
As fronteiras importam mais que o número de servidores. Um bridge local via stdio pode ser adequado para uma estação controlada. Um serviço remoto precisa de HTTPS, autorização própria, isolamento de tenants e proteção da rede de saída.
1. Mantenha segredos fora do modelo
A credencial do WordPress pertence ao processo do bridge, não ao contexto do agente. Use secret manager, variável injetada no runtime ou arquivo protegido pelo sistema operacional. Nunca inclua Application Passwords em prompts, histórico, descrição de ferramenta, retorno de erro ou repositório.
Crie um usuário técnico por integração e por ambiente. Uma Application Password pode ser revogada sem trocar a senha principal e não deve ser compartilhada entre desenvolvimento, homologação e produção. Se o bridge for comprometido, essa separação reduz o raio do incidente.
2. Autorize nas duas fronteiras
Autenticação responde quem fez a chamada. Autorização responde se essa identidade pode executar aquela Ability.
No bridge, use uma allowlist explícita de nomes como wp24/get-public-site-summary. No WordPress, preserve uma permission_callback que verifique a capability necessária. A allowlist não substitui o WordPress, e o WordPress não substitui a política do bridge.
'permission_callback' => static function (): bool {
return current_user_can( 'edit_posts' );
},
Não use __return_true para operações privadas só porque o endpoint está “escondido”. A exceção aceitável é uma leitura realmente pública, como a política de links externos que já é entregue a visitantes no front-end.
3. Separe leitura, escrita e destruição
Não coloque operações com riscos diferentes na mesma Ability. Prefira três contratos pequenos:
get_post_summary: somente leitura;update_post_excerpt: escrita reversível e restrita;delete_post: destrutiva, isolada e sujeita a aprovação humana.
Em produção, comece apenas com leitura. Libere escrita depois de observar chamadas reais e ter rollback. Ações destrutivas devem exigir confirmação fora do texto produzido pelo modelo, registrar quem aprovou e, quando possível, usar lixeira ou estado intermediário recuperável.
4. Trate schemas como barreiras de segurança
Defina tipos, campos obrigatórios, enumerações, limites de tamanho e additionalProperties: false. O callback também deve validar invariantes de negócio: um ID existente, um status permitido, um domínio autorizado ou um limite máximo de itens.
O schema reduz ambiguidade, mas não neutraliza instruções maliciosas presentes em páginas, comentários ou documentos. Conteúdo recuperado é dado não confiável. Ele não pode alterar a allowlist, pedir segredos nem conceder novas permissões.
5. Controle rede e transporte
Em produção, use TLS entre o bridge e o WordPress. Preserve o cabeçalho Authorization no proxy reverso e bloqueie logs que capturem seu valor. Restrinja a saída do bridge aos hosts necessários e valide URLs por allowlist quando uma Ability puder buscar recursos externos.
Para MCP local, stdio reduz a superfície de rede, mas o processo continua com os privilégios do cliente: fixe versões, revise o pacote e limite filesystem e rede. Para MCP remoto, implemente a autorização prevista pelo protocolo. Não aceite um token destinado a outro serviço para simplesmente encaminhá-lo ao WordPress; esse token passthrough quebra a separação de audiência e prejudica a auditoria.
6. Coloque limites antes da primeira chamada
Cada execução deve ter:
- timeout total e timeout de conexão;
- limite de payload e de itens processados;
- rate limit por identidade e por Ability;
- limite de concorrência para operações caras;
- no máximo poucas tentativas, apenas para erros transitórios;
- chave de idempotência ou identificador de operação para escritas repetíveis;
- circuit breaker quando WordPress ou um serviço dependente falhar.
Não repita automaticamente uma ação de escrita se o bridge não souber se a primeira tentativa foi concluída. Consulte o estado ou use uma chave de idempotência antes de tentar de novo.
7. Registre o suficiente, sem registrar segredos
Gere um correlation_id no início do pedido e propague-o pelo bridge e pelo WordPress. Registre horário, identidade técnica, Ability, versão do contrato, duração, resultado, código de erro e decisão de política.
Evite prompt completo, credencial, cabeçalho de autorização e conteúdo pessoal por padrão. Para entradas e saídas, prefira hashes, contagens, IDs internos e campos previamente classificados. Defina retenção, acesso aos logs e alertas para picos de negação, erros, latência e volume.
8. Implante com gates, não por confiança
Uma promoção segura passa por quatro ambientes ou estágios:
| Gate | Evidência mínima |
|---|---|
| contrato | schema válido, exemplos e erros documentados |
| segurança | testes de permissão permitida e negada, segredo ausente dos logs |
| integração | REST e bridge testados com timeout, falha e resposta inválida |
| produção | allowlist restrita, usuário técnico mínimo, métricas e rollback ativos |
Use uma matriz compatível com as versões suportadas do WordPress e do PHP. No nosso estudo, também testamos a ausência da Abilities API no WordPress 6.8.3 para garantir fallback sem fatal, além de validar registro, execução e REST no 7.0.2 e no 7.1-RC1.
Runbook de incidente
Se houver chamada inesperada, vazamento ou comportamento destrutivo:
- desative a Ability na allowlist do bridge;
- revogue a Application Password afetada;
- pause o usuário técnico ou reduza suas capabilities;
- preserve logs e identifique o
correlation_idinicial; - compare alterações com backup, revisão e trilha editorial;
- restaure ou reverta dados quando necessário;
- corrija contrato, política ou isolamento antes de reemitir a credencial;
- faça rotação de segredos relacionados e registre a causa raiz.
A ordem é deliberada: primeiro interrompa novas execuções, depois investigue. Não apague logs durante a contenção.
Checklist de lançamento
- [ ] usuário técnico exclusivo e com privilégio mínimo;
- [ ] Application Password exclusiva por ambiente;
- [ ] segredo fora do prompt, banco de conteúdo e repositório;
- [ ] allowlist do bridge em modo negar por padrão;
- [ ]
permission_callbacktestada para permitir e negar; - [ ] schemas fechados, limites e enums definidos;
- [ ] leitura, escrita e destruição em Abilities separadas;
- [ ] confirmação humana para ações de alto impacto;
- [ ] HTTPS, proxy e cabeçalho de autorização validados;
- [ ] egress restrito e proteção contra URLs internas;
- [ ] timeouts, concorrência, rate limit e idempotência configurados;
- [ ] logs estruturados, sem segredos, com
correlation_id; - [ ] alertas, backup, rollback e runbook exercitados;
- [ ] versões do bridge e dependências fixadas e auditadas;
- [ ] teste ponta a ponta executado antes de cada promoção.
Uma regra simples para decidir
Se uma chamada equivocada puder causar dano material, não deixe a decisão apenas com o modelo. Transforme intenção em proposta, passe por política determinística e exija autorização ou aprovação proporcional ao impacto.
A Abilities API oferece a camada de descoberta e contrato. MCP pode oferecer a ponte para clientes e agentes. A segurança de produção nasce da composição consciente das duas camadas com identidades mínimas, limites, evidência e mecanismos de revogação.
Próximo passo para sua empresa
Se você mantém um plugin, integração editorial ou operação WordPress e quer avaliar o caminho até produção, conheça a Auditoria de prontidão para agentes. O trabalho começa pelo inventário de operações e termina com uma prova de conceito, matriz de risco e plano de implantação.
