ENDE
Back to home

WPAgently documentation

Architecture: four layers, one verification chain

The architecture separates connection, agent knowledge, and verification. That separation makes the boundaries visible.

WPAgently connects your assistant to WordPress and checks important results afterwards. You do not need to operate the technology behind it. This page only explains why the normal workflow creates a draft first and stops when a case is unclear.

For everyday work, Getting started is enough. This architecture page helps you understand safety messages and boundaries.

Four layers

WPAgently separates four jobs. This keeps one mistake from receiving too many permissions at once.

  1. WordPress tools

An ability is one clearly limited action, such as creating a draft or checking a post. WordPress provides only the functions enabled for your chosen profile.

The Companion plugin ships the MCP adapter in vendor/ and loads it through vendor/autoload.php. Its own MCP endpoint therefore does not depend on a third-party adapter host. The build disables Composer plugins so the runtime bootstrap uses only the reviewed autoloader.

  1. Your assistant

Claude Code, Claude Desktop, Codex, ChatGPT, and other supported assistants connect to these tools. They do not receive direct Administrator access to your website.

  1. The CLI and Skills

The optional Paid CLI makes repeatable terminal tasks easier. Skills are short guides for Claude Code or Codex. Both help with the workflow, but neither replaces the rules in WordPress.

  1. Chat inside WordPress

On WordPress 7.0 or newer, you can also use WPAgently > Chat and Preview. You configure your own AI provider under Settings > Connectors. Write suggestions appear as a plan and need your individual approval. The isolated preview allows same-origin resources, data: images, data: fonts, and bounded inline styles. External stylesheets, CSS imports, fonts, images, and media are blocked. Scripts and network connections are disabled in the preview.

What happens in a normal task

When you ask for an article or landing page, the normal path follows a fixed order.

  1. WPAgently checks the connection and the role of the agent user.
  2. Your assistant creates a new draft. A draft is not public yet.
  3. WordPress turns the content into real blocks and checks the rendering.
  4. WPAgently checks important follow-up work, such as rendering and, when needed, a cache refresh.
  5. You review the draft visibly in the WordPress dashboard and publish it there yourself.

Your assistant does not write made-up block code or HTML directly into your page. This stops new content from silently ending up in the old Classic Editor format.

Articles and landing pages

Abilities called by the ARTICLE and LANDING pipelines depend on the task, an existing slug, and the selected options. A slug is the last part of a web address, for example my-new-article.

  • wp-agent/create-post-from-markdown creates a new article as a draft.
  • wp-agent/upsert-pattern creates a landing page from clearly described sections.
  • wp-agent/render-verify checks the visible rendering after a change. wp-agent/render-check is a separate read-only Ability. It checks the block interpretation and reports a Classic Editor fallback among other signals.
  • wp-agent/refresh-hooks runs important follow-up work that WordPress otherwise often runs only when you save manually.

For a local featured image, the workflow can also use wp-agent/create-direct-media-upload, wp-agent/get-post, and wp-agent/set-featured-image. If direct-upload verification fails after saving, the attachment is preserved and the ability returns HTTP 409 with wpagent_direct_upload_recovery_required, recovery_required=true, and the attachment_id for manual inspection. For SEO, WPAgently reads the state with get-seo-meta. set-seo-meta and set-post-status deliberately stop with manual_only at the moment. Make SEO changes and publish in WordPress after your review.

For an existing slug, WPAgently reads the current state first. Multiple or non-exact results abort without selecting a post before any mutation. That way, automation does not simply overwrite the wrong content.

The five silent failure modes

WPAgently is designed to make these five problems visible before you publish a draft.

  1. Unformatted content: WordPress would save the content as a Classic block. WPAgently stops the workflow.
  2. SEO with no effect: An SEO plugin would not reliably apply the change. WPAgently stops, and you change the value in the SEO plugin.
  3. Old preview or sitemap: A cache or follow-up task is not current yet. WPAgently runs the relevant follow-up work.
  4. Unsafe or incomplete images: An image link points to a protected location, or alt text is missing. WPAgently rejects it.
  5. Duplicate article: A request could create the same post twice. WPAgently stops on an unclear match.

Find practical help for these cases in Troubleshooting.

Safety layer

The safety layer is the set of checks around normal WPAgently tasks. It is not a guarantee against every mistake. It is a set of concrete boundaries.

  • Bot-not-admin: Before a task, WPAgently checks that the agent user is only an Editor. If it has Administrator permissions, the workflow deliberately stops.
  • Draft first: CLI pipelines create new content as drafts by default. Even a requested publish command does not currently publish it automatically.
  • Safe image sources: WPAgently accepts only public image addresses and blocks local and private network addresses.
  • No silent duplicates: An already used or ambiguous slug stops creation before anything changes.
  • Limited tools: An ability that is turned off is not shown to your assistant at all.

BYO principle

BYO means “bring your own.” You choose your own AI provider and WordPress site. Your WordPress content and credentials are not routed through a WPAgently text service.

For an external connection, the credential stays with you, either in your local configuration file or in the browser sign-in you approved. With the optional WordPress chat, WordPress sends the request directly to the AI provider you configured under Settings > Connectors.

Licence checks and updates need technical connections. They do not send WordPress content or WordPress credentials.

Production note

Even with these boundaries, review every visible change yourself before publishing it. For normal content, use Companion and the Editor from the setup.

Power is deliberately not part of this path. It is a separate plugin for technical access to files, the database, and PHP. As a regular WordPress user, leave it turned off. If you need it for a test copy, read Power mode first.