Skip to content

Feat[Experiment]: Add Agent Users, dedicated accounts for AI agents - #961

Closed
gziolo wants to merge 13 commits into
developfrom
add/agent-users-experiment
Closed

gziolo wants to merge 13 commits into
developfrom
add/agent-users-experiment

Conversation

@gziolo

@gziolo gziolo commented Aug 20, 2026 •

Copy link
Copy Markdown
Member

📢 Work continues in #1068.

What?

See #923.
Supersedes #211 by @Jameswlepage.

This PR adds the experimental Agent Users feature. It gives external software—AI agents, MCP clients, scheduled jobs, and similar tools—dedicated WordPress identities instead of requiring them to borrow a human account.

This PR covers the identity model. Richer audit trails and provenance can build on that identity separately.

Why?

An external agent currently has two poor identity choices: reuse a human credential, which mixes attribution and revocation, or run without a user, which loses authorship and produces surprising capability behavior.

An agent account reuses WordPress's existing user primitive. Roles, content ownership, revisions, comments, deletion with reassignment, and user-based logs therefore continue to work. The agent's access can be changed or revoked without modifying a human account.

How?

An agent is a regular WordPress user marked by wpai_agent user meta. The agent acts as its own principal: the creator is recorded as provenance in wpai_agent_created_by, not as the person the agent acts for. The marker changes the account's identity and authentication contract while preserving core user behavior:

  • Core user management surfaces. Users → Add Agent reuses the Add User form. The profile remains the canonical place to change the role and manage credentials. The Users list labels roles such as Editor (agent), provides account-type filtering, and replaces password reset with an Application Passwords shortcut.
  • Every agent username ends with _agent. Provisioning appends the suffix when it is missing, including for programmatic callers. That makes agents easy to spot wherever only the login is shown, such as WP-CLI output, author names, and logs.
  • Non-interactive authentication. Password login and password resets are blocked. Credentials are issued and revoked through core's REST-backed Application Password flows under their normal permission checks, preserving the one-time plaintext reveal. Other authentication mechanisms can participate when they resolve the request to the agent user.
  • The role defines authority. There are no agent-specific roles or hardcoded blocked capabilities. An agent receives the same capabilities WordPress grants a human with the assigned role. An Administrator agent is therefore fully trusted and carries the same operational risk as any other Administrator account; lower roles remain limited by WordPress's normal capability mapping.
  • Non-administrator agents cannot write unfiltered HTML. This is the one deliberate exception to role parity. Some roles below Administrator carry unfiltered_html, most notably Editor on single site, and model output stored with it becomes stored XSS (scripts saved into content). The capability is stripped from every agent without manage_options, so their content passes core's normal KSES filtering. The check matches the resolved primitive, which also covers meta capabilities such as edit_css.
  • Provisioning cannot widen the creator's access. Creating an agent requires create_users, promote_users, and the primitive edit_users capability needed to manage the resulting account. The selected role must be within the provisioner's effective capabilities. That comparison runs first while listing roles and again against the real marked agent after creation, so user-specific capability filters cannot give the agent a role capability denied to its provisioner. A failed final check rolls the account back before core's edit_user_created_user compatibility and notification action runs. Capabilities that are inert for the agent, such as the stripped unfiltered_html, do not count against the provisioner.
  • Agents stay visible. Normal user queries continue to return agents because they own content and participate in capability checks; hiding them is a display concern, never a query concern. REST user responses expose a read-only wpai_is_agent field, and the global wpai_is_agent_user() helper gives plugins one documented way to detect agent accounts.
  • Identity safeguards outlive the experiment UI. Provisioning and presentation follow the WordPress AI support check, the global AI features setting, and the experiment setting. Existing agents remain unable to log in interactively or reset passwords whenever the plugin is active, and the unfiltered HTML restriction stays in force even if those settings are later disabled.

Multisite model

WordPress stores user identity and Application Passwords across the network, while site memberships and roles are site-specific. Agent accounts follow that core model instead of adding a parallel boundary:

  • One agent can be a member of several sites, and its role on each site defines what it can do there.
  • The same credential identifies the network user everywhere. It authenticates the agent as a logged-in user on every site, like any WordPress credential, but a site the agent does not belong to only sees an authenticated user without capabilities there.
  • Agents are provisioned from a site so the initial role has site context. Adding an agent to another site, removing it, changing its role, and deciding who may manage it all use core's normal multisite permission and invitation flows.
  • Core lets only accounts with the network-level manage_network_users capability edit other users on multisite. The same rule decides who can provision agents and manage their credentials.
  • The only agent-specific multisite restriction is that agents cannot become super admins, because that status bypasses the role system.

The plugin must be network-activated when this experiment is used on multisite. The agent marker is network-wide, so every site has to enforce the login and password-reset safeguards.

Core hardcodes several user-screen labels and action positions. Small inline scripts progressively enhance those labels for agents; without JavaScript, the underlying core forms continue to work.

Out of scope: assistants running inside a logged-in human session, credential protocols such as OAuth and expiry, per-run audit correlation, trust tiers, and approval workflows.

Use of AI Tools

  • AI assistance: Yes
  • Tool(s): Claude Code, OpenAI Codex
  • Model(s): Claude Fable 5, Claude Opus 5, GPT-5 (Codex)
  • Used for: drafting and iterating on the implementation, tests, documentation, core-screen integration, security review, multisite behavior, capability safeguards, and validation in wp-env. I directed the scope and design decisions and reviewed the results.

Testing Instructions

Application Passwords require HTTPS or WP_ENVIRONMENT_TYPE set to local. With wp-env, add a git-ignored .wp-env.override.json containing {"config": {"WP_ENVIRONMENT_TYPE": "local"}} and restart.

Single site

  1. Enable AI features and the Agent Users experiment in Settings → AI.
  2. Go to Users → Add Agent, enter a username and unique email, select a role, and create the account. Confirm the stored username ends with _agent.
  3. On the agent profile, create and copy an Application Password.
  4. Authenticate through REST: curl -u 'USERNAME:PASSWORD' 'https://your-site/wp-json/wp/v2/users/me'.
  5. Confirm permissions match the selected role. For example, an Editor remains unable to administer the site, while an Administrator agent has normal Administrator authority and risk.
  6. Create content through REST and confirm the agent is the attributed author.
  7. As an Editor agent, save content containing a <script> tag and confirm KSES strips it. A human Editor keeps core's single-site behavior.
  8. Confirm interactive login and password reset are rejected.
  9. Confirm the Users list marker, account-type filter, and Application Passwords row action.

Multisite

  1. Network-activate the plugin, then enable AI features and the experiment on the site under test.
  2. As a network administrator, create an agent from that site's Users → Add Agent screen.
  3. Confirm its Application Password authenticates on that site through REST.
  4. Add the agent to a second site through core's Add Existing User flow and give it a role there. Confirm the same credential now works on both sites, each within that site's role.
  5. Remove the agent from one site and confirm it loses its authority there while keeping its role on the other site.
  6. Confirm a site administrator without network permissions cannot edit the agent, matching core's rule for human accounts.
  7. Confirm the agent cannot be granted super admin.

Run the focused suites:

npm run test:php -- --filter Agent_UsersTest
npx wp-env --config=.wp-env.test.json run cli --env-cwd=wp-content/plugins/ai bash -c "WP_MULTISITE=1 vendor/bin/phpunit -c phpunit.xml.dist --filter Agent_UsersTest"

Screenshots or screencast

Users screen with the Add Agent action, the (agent) marker, and the account-type filter:

Users screen with the Add Agent action, agents marked in the Role column, and the agents filter open

Users → Add Agent, using core's Add User form in agent mode:

Add Agent screen with username, email, names, website, and role fields

An agent profile with the account note and human-only sections hidden:

Edit Agent screen with the account note and the name, contact, and about sections

Changelog Entry

Added - New Experiment: Agent Users; provision dedicated accounts for external agents so their work is attributable and independently revocable.

Open WordPress Playground Preview

@gziolo gziolo self-assigned this Aug 20, 2026
@codecov

codecov Bot commented Aug 20, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 76.76190% with 122 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.60%. Comparing base (a7657e1) to head (dcae15b).
⚠️ Report is 39 commits behind head on develop.

Files with missing lines Patch % Lines
includes/Experiments/Agent_Users/Agent_Account.php 80.97% 39 Missing ⚠️
...cludes/Experiments/Agent_Users/New_User_Screen.php 71.65% 36 Missing ⚠️
...ncludes/Experiments/Agent_Users/Profile_Screen.php 55.00% 36 Missing ⚠️
includes/Experiments/Agent_Users/Agent_Users.php 59.25% 11 Missing ⚠️
Additional details and impacted files
@@              Coverage Diff              @@
##             develop     #961      +/-   ##
=============================================
+ Coverage      75.55%   75.60%   +0.05%     
- Complexity      3381     3562     +181     
=============================================
  Files            138      145       +7     
  Lines          13081    13606     +525     
=============================================
+ Hits            9883    10287     +404     
- Misses          3198     3319     +121     
Flag Coverage Δ
unit 75.60% <76.76%> (+0.05%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@github-actions

Copy link
Copy Markdown

✅ WordPress Plugin Check Report

✅ Status: Passed

📊 Report

All checks passed! No errors or warnings found.


🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds experimental dedicated WordPress accounts for external AI agents.

Changes:

  • Provisions agent accounts with Application Passwords and restricted capabilities.
  • Adds admin, Users screen, and REST identity surfaces.
  • Adds documentation and integration tests.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
includes/Experiments/Experiments.php Registers the experiment.
includes/Experiments/Agent_Users/Agent_Users.php Initializes agent-user services.
includes/Experiments/Agent_Users/Agent_Account.php Implements provisioning and identity restrictions.
includes/Experiments/Agent_Users/Admin_Page.php Adds provisioning and listing UI.
includes/Experiments/Agent_Users/Users_Screen.php Adds agent filtering and badges.
includes/Experiments/Agent_Users/REST_Field.php Exposes the agent marker through REST.
includes/Experiments/Agent_Users/README.md Documents behavior and limitations.
tests/Integration/Includes/Experiments/Agent_Users/Agent_UsersTest.php Tests core agent-account behavior.
Suppressed comments (2)

includes/Experiments/Agent_Users/Admin_Page.php:383

  • The result key is shared by every provisioning request from the same administrator. If two tabs submit before either redirect is rendered, the second result overwrites the first; one newly created agent's only plaintext credential is then never shown, and a redirect may display the other request's result. Correlate each redirect with a unique, unguessable one-time result identifier (or avoid the shared PRG storage entirely).
	private function store_result( array $result ): void {
		set_transient( self::RESULT_TRANSIENT_PREFIX . get_current_user_id(), $result, 5 * MINUTE_IN_SECONDS );

includes/Experiments/Agent_Users/Admin_Page.php:383

  • This transient contains the plaintext Application Password from the success result. On a standard WordPress install, set_transient() serializes it into wp_options (or sends it to the external object cache), contradicting the stated one-time, never-stored credential model and exposing a live secret to database/cache readers and transient hooks. Return the credential through a non-persistent one-time response such as core's Application Password flow, or protect it with an appropriately encrypted one-time channel.
	private function store_result( array $result ): void {
		set_transient( self::RESULT_TRANSIENT_PREFIX . get_current_user_id(), $result, 5 * MINUTE_IN_SECONDS );

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

@gziolo
gziolo force-pushed the add/agent-users-experiment branch from 600b7af to d822ecc Compare August 21, 2026 10:22
@gziolo
gziolo marked this pull request as ready for review August 21, 2026 10:23
@gziolo
gziolo requested a review from a team August 21, 2026 10:23
@github-actions

github-actions Bot commented Aug 21, 2026 •

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: jorgefilipecosta <jorgefilipecosta@git.wordpress.org>
Co-authored-by: artpi <artpi@git.wordpress.org>
Co-authored-by: webmyc <urbankidro@git.wordpress.org>
Co-authored-by: nerrad <nerrad@git.wordpress.org>
Co-authored-by: jeffpaul <jeffpaul@git.wordpress.org>
Co-authored-by: josephfusco <joefusco@git.wordpress.org>
Co-authored-by: JasonTheAdams <jason_the_adams@git.wordpress.org>
Co-authored-by: chubes4 <extrachill@git.wordpress.org>
Co-authored-by: nikolas4175-godaddy <nikskyverge@git.wordpress.org>
Co-authored-by: mathetos <webdevmattcrom@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@gziolo gziolo added the [Type] Proof of Concept PRs that explore new conceptual experiment functionality label Aug 21, 2026
@gziolo
gziolo requested a balanced review from Copilot August 21, 2026 10:24

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Suppressed comments (4)

includes/Experiments/Agent_Users/Agent_Account.php:297

  • map_meta_cap() is user-specific and filterable, so do_not_allow here does not prove that nobody can hold this capability. A plugin may deny a capability only to the provisioner but allow it for the new agent; skipping the subsequent current_user_can() check then permits exactly the escalation this method is meant to prevent. Only special-case capabilities known to be globally unavailable, rather than every do_not_allow result.
			// Skip capabilities nobody can hold on this site, such as `manage_links` without the Link Manager.
			// phpcs:ignore WordPress.WP.Capabilities.Undetermined -- Mapping every capability granted by the selected role.
			if ( in_array( 'do_not_allow', map_meta_cap( $capability, $current_user_id ), true ) ) {
				continue;

includes/Experiments/Agent_Users/Agent_Account.php:132

  • Provisioning does not require permission to edit the created user. The integration test's limited manager has create_users and promote_users but no edit_users, so it can create an agent, yet get_edit_user_link() returns no usable profile URL and core's Application Password endpoint denies managing that agent. Require the relevant edit permission or handle this supported role without redirecting it to an inaccessible credential screen.
	public static function current_user_can_provision(): bool {
		return current_user_can( 'create_users' ) && current_user_can( 'promote_users' );

includes/Experiments/Agent_Users/New_User_Screen.php:349

  • The second wp_die() argument is the page title, not the HTTP status. This renders 403 as the title while the response keeps the default error status. Pass the response code through the $args parameter so unauthorized submissions actually return HTTP 403.
			wp_die( esc_html__( 'Sorry, you are not allowed to create agent accounts.', 'ai' ), 403 );

includes/Experiments/Agent_Users/README.md:26

  • This contradicts the bootstrap implementation: Main::load() registers Agent_Account safeguards before Requirements::are_requirements_met() evaluates wp_supports_ai(). When AI support is disabled, provisioning/UI do not load, but login, reset, and capability safeguards still run. Document that distinction so operators do not assume the agent restrictions disappeared.
1. WordPress core reports AI support via `wp_supports_ai()`. When the environment disables AI, the plugin does not load at all, so none of this code runs.

@jorgefilipecosta jorgefilipecosta left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From the code/technical point of view this seems to be on a very good direction. I think multisite presents a whole set of challenges and we are not handling things to deal with multisite yet, It is probably better to disable this experiment on multisite and then have a follow up PR focused on multisite.

In terms of UX, we are forcing agents to have an email, I think email could be optional defaulting to the agent creator email, or even have the email field prefielled with the original author email. It may be tricky if emails are unique per user if that's the case I think it should be ok for agent users to not have an email.

@gziolo

gziolo commented Aug 24, 2026

Copy link
Copy Markdown
Member Author

Thank you for the review, @jorgefilipecosta!

Agreed on multisite. It brings its own set of questions, like the network Users screen, the network profile screen, and the fact that user meta is shared across the whole network. I will keep this PR focused on the general mechanism and handle multisite in a dedicated follow-up PR. To avoid a half-working state, this PR will disable the experiment when multisite is detected. The safeguards for existing agent accounts stay active either way.

On the email, it has to stay unique. WordPress enforces that in wp_insert_user() itself, so defaulting to the creator's email would fail on the second agent. We could auto-generate unique placeholder addresses, but I would rather not. The email gives us a communication layer for observing the agent: it is where notifications about its activity and account changes arrive. A placeholder address would silently drop all of that.

One idea for a follow-up: offer a button to fill or simply prefill the field with a plus-addressed suggestion based on the creator's email, for example you+agent-name@your-domain. It is unique, passes validation, and still delivers to the creator's inbox. For now, I would keep the field required and unchanged.

@gziolo

gziolo commented Aug 24, 2026

Copy link
Copy Markdown
Member Author

I changed direction from disabling the experiment on multisite to supporting site-bound agents in this PR. Each agent records the site where it was created and can authenticate only while it remains a member of that site. Roles on other sites do not expand access. Agents cannot be added elsewhere or become super admins, and site administrators can manage only agents assigned to their site. This is implemented and covered by multisite tests in a521681.

@gziolo

gziolo commented Aug 25, 2026 •

Copy link
Copy Markdown
Member Author

Summary of the latest changes after review:

  • Removed the agent-specific blocked-capability list. The assigned WordPress role now defines the agent's authority: an Administrator agent has normal Administrator access and risk, while lower roles remain limited by core's capability mapping.
  • Strengthened provisioning so it requires create_users, promote_users, and the primitive edit_users capability. The selected role cannot exceed the provisioner's effective access.
  • Added a final comparison against the real marked agent after creation. This catches user-specific capability filters that could otherwise grant the agent a role capability denied to its provisioner; failed authorization rolls the account back before edit_user_created_user runs.
  • Preserved core behavior by firing edit_user_created_user for successful creation and returning an actual HTTP 403 for unauthorized submissions.
  • Confirmed that agents may manage their own Application Passwords when core permits it.
  • Kept the multisite identity boundary: agents are bound to one site, require network activation for provisioning, cannot become super admins, and cannot authenticate or gain membership outside their assigned site.
  • Updated the UI copy, experiment documentation, tests, and PR description to reflect this model.

@artpi

artpi commented Aug 27, 2026

Copy link
Copy Markdown

All this sounds fantastic!

Membership alone would therefore allow the same agent credential to follow the user to every site where it receives a role. (....) Each multisite agent records one assigned site in wpai_agent_site_id.

I am not sure this is necessary and breaks some of the WordPress logic.
Roles are site-specific so that provides a boundary: you would have to explicitly add an agent to the site. this would follow established WP checks

One thing that I like in telegram is that when you are creating a telegram bo, the login has to end with _bot.
I think this would allow to quickly distinguish these accounts when browsing them in wpcli or somewhere.
KMy login:
arturpiszek
My. bot login
arturpiszek_mcp_agent

The other thing is that Linear makes it super explicit when something was done by the agent and on behalf of whom - I think this would be neat.
If we choose this route, we have to decide:

  • Is the agent working permanently on my "behalf"
  • Is the agent usrable by other people and acting "independently" and I am only its creator?

@gziolo

gziolo commented Aug 27, 2026

Copy link
Copy Markdown
Member Author

Thanks @artpi, all good points!

You are right about multisite. I picked the strict site binding because I did not know this area well enough. After checking core again, site roles already give the boundary we need. Only super admins can create an active user without email confirmation, and adding an existing user to another site sends an invitation that the agent's email owner has to confirm. So I will remove the site binding and treat agents as regular network users. Roles decide where an agent can act, and core decides who can manage the account. The only extra rule that stays is that an agent cannot become a super admin.

I like the _bot idea. Every agent login will end with _agent. It gets added on creation, so it also applies when agents are created from code. It should make agents easy to spot in WP-CLI, the post author name, and logs.

On "acting on behalf": as I noted earlier, I would keep two cases separate for now. Agent accounts always act on their own behalf, with their own role and attribution. That is what this PR covers. The person who creates the agent is only its creator, not the one the agent acts for. The other case is a human account used by an external agent. There the work belongs to the person, and we would mark it as agent assisted. That needs a different attribution model and fits better with the audit trail work.

@webmyc

webmyc commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

Compatibility note: agent users and code that assumes a principal is human

Following up on my #961 test with the compatibility note I offered. These are the ecosystem-side seams I have hit or reproduced where "an agent is a normal, queryable WordPress user" meets code that quietly assumed a principal was a person. None are defects in the experiment; they are the adjustments the surrounding code needs once agent users exist. I found all of these against real sites, most of them the hard way before agent users existed.

1. Resolving a principal by role can now resolve to an agent

Any code that answers "who should I act as" by querying for a role will, on some sites, get an agent. The canonical shape:

get_users( array( 'role' => 'administrator', 'number' => 1, 'orderby' => 'ID', 'order' => 'ASC' ) );

Reproduced against #961: with an Administrator agent whose ID is lower than any human administrator (original admin deleted or renamed, or the site provisioned agent-first via WP-CLI or a host), this returns the agent, and the caller adopts it as the content-owning principal. post_author then points at an agent, and any later "is this author human" check loops.

This is correct behaviour from the experiment (agents must stay queryable so ownership and capability code keeps working). The fix belongs in the resolver: exclude agents when picking a principal to act as.

// Before
get_users( array( 'role' => 'administrator', 'number' => 1, 'orderby' => 'ID', 'order' => 'ASC' ) );

// After: a human principal, not another agent
get_users( array(
    'role'       => 'administrator',
    'number'     => 1,
    'orderby'    => 'ID',
    'order'      => 'ASC',
    'meta_query' => array( array( 'key' => 'wpai_agent', 'compare' => 'NOT EXISTS' ) ),
) );

A stable WordPress\AI\...\Agent_Account::is_agent() (which #961 provides) is the thing every such resolver should consult. A raw meta check invites drift; a documented function does not.

2. Role-based user queries already miss admins; agents widen the blast radius

Two failures I shipped before agent users existed, both caused by a principal the query could not see. They matter here because agent users are one more principal these queries mishandle, and any resolver touched by note 1 above should account for both.

  • get_users( array( 'role' => 'administrator' ) ) only enumerates a site's own member list. A network super admin who runs a subsite without being explicitly added to it does not appear, so the query concludes there is no administrator.
  • On installs where the administrator comes from a custom role or a runtime user_has_cap / map_meta_cap filter rather than the stored role, the same query returns empty while the site plainly has an admin.

The guidance worth stating out loud for anyone touching user queries: hiding an agent is a display concern (author dropdowns, participant lists), never a query concern. Normal queries must keep returning agents; only the UI should omit them.

3. A single-site Editor agent carries unfiltered_html

On a single-site install, both Editor and Administrator hold unfiltered_html by default. Reproduced against #961: an Editor agent's REST write stored a <script> tag, a <style> block, and a third-party custom element verbatim, with no kses filtering. The README already names this ("model output combined with it means stored XSS"); the note is only that the current experiment does not strip the capability yet, and that the role default carries it, so closing it needs an adjustment tied to the agent flag rather than the choice of role.

The corollary matters for anyone whose agents write structured builder markup: stripping unfiltered_html from an agent is the right default, and it reintroduces the kses wall a minimal human hits, where allowed elements are filtered and <style> contents can be corrupted because kses reads CSS selectors as markup. An allowlist (wp_kses_allowed_html) says which tags are safe here, but it cannot be authored by the party doing the writing, because the safe set is whatever plugins that specific site has installed. Whatever ships, agents that produce site-specific markup will need a way for the site, not the agent, to declare the content shapes its agents may write, held separately from what the agent may do.

Verified positive controls (no action needed)

For completeness, against #961 these behaved exactly as designed: interactive login blocked, password reset blocked, Application Passwords issued and authenticated, wpai_agent_created_by recorded, is_agent() and the wpai_is_agent REST field correct, and agents correctly returned by ordinary user queries.

Happy to keep running patches against the fleet as this evolves and report back.

@gziolo

gziolo commented Aug 27, 2026

Copy link
Copy Markdown
Member Author

One finding while adding the _agent suffix. Agent provisioning uses wp_insert_user(), which allows _ in usernames, so the suffix works in this PR. But multisite validates signups with wpmu_validate_user_signup(), which only allows lowercase letters and digits (/[^a-z0-9]/). Any flow that goes through it, like the REST users endpoint on multisite, would reject _agent (and -agent too). That rule is very strict and may cause some friction for agents on multisite. I will keep it in mind for the multisite rework.

@gziolo

gziolo commented Aug 27, 2026

Copy link
Copy Markdown
Member Author

Thanks @webmyc for testing and for the detailed notes!

On unfiltered_html, this is a matter of decision. The reasoning you referred to is from an earlier revision. I removed the blocked capability list on purpose, so an agent now gets exactly what its role has. If you give an agent the Editor or Administrator role, unfiltered_html comes with it. We could remove this one capability for agents. In some cases, that is useful, because it stops scripts and styles in content. But it also blocks legitimate cases where the agent adds a safe script or style. And it would not remove the bigger risks, because an Administrator agent can still install a plugin or change the theme. I am open to either option, so more opinions are welcome.

The points about role queries need further investigation. Some of the reported cases look like expected WordPress behavior. An agent is a regular user with a role, so a query for that role will return it, and a super admin who is not a member of a site does not show up in that site's user list.

@webmyc

webmyc commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

@gziolo on unfiltered_html, since you asked for opinions: strip it from agents by default, and here is the reasoning from someone whose agents write scripts and styles for a living.

the Administrator-agent case is not the interesting one. an admin agent is fully trusted, can install plugins, and reasoning about one capability there is deck-chair arrangement, agreed. the interesting tier is below admin, because the whole promise of this proposal, in your words on #923, is a principal smaller than an administrator that can still own content. Editor is the natural role for that principal, and on single-site Editor ships unfiltered_html, so the smaller principal arrives with stored-XSS-grade caps by default. a site owner who provisions an "editor agent" is not expecting that.

the "blocks legitimate cases" concern is real, my fleet is the evidence: agents legitimately write builder markup, embeds, styles all day. but i have run both sides of this tradeoff in production, and the answer that worked is not a binary cap. it is: safe default, plus a site-owned escape hatch that is narrower than unfiltered_html. concretely, strip the cap on the agent flag, and give the experiment one filter through which the site (or its plugins) can extend the kses allowlist for agent writes, the way wp_kses_allowed_html works but scoped to agent principals. the set of safe tags is a property of what the site has installed, so the site is the only party that can author it. the agent never gets to grant itself scripts; the site can, deliberately, per element. that covers my builder-markup case without reopening the XSS default, and an admin who truly wants an unfiltered agent can still grant the cap explicitly and own that decision.

on the role queries, no disagreement: both behaviors are core semantics working as designed, which is what the note says too. i included them as integrator context, not as bugs, because the resolver-adoption case is code that exists in the wild today (mine included) and will misfire the day agent users ship. if it is useful, i am happy to reshape that section into a short "guidance for integrators" block for the experiment README: resolvers that pick a principal to act as should consult is_agent(), hiding is a UI concern never a query concern. that puts the guidance where plugin authors will actually find it.

the _agent login suffix helps here too: it gives resolvers a second, dependency-free way to skip agents even when the AI plugin is not active to provide is_agent(). worth documenting as part of the convention.

@gziolo
gziolo force-pushed the add/agent-users-experiment branch from 87be0bd to cf5555f Compare August 31, 2026 11:15
@gziolo

gziolo commented Aug 31, 2026

Copy link
Copy Markdown
Member Author

@artpi @webmyc thank you, both rounds of feedback are now in the branch:

  • Multisite follows core (80ea863). The site binding is gone. Site membership and roles are the boundary, and core decides who can manage agents through manage_network_users. The only extra rule left is that agents cannot become super admins. Network activation is still required, because the agent marker is shared across the network, so every site must block interactive login for the same accounts.
  • Usernames end with _agent (7d2210c). The suffix is added on creation, also when agents are created from code. The README documents it as a convention.
  • Agents below administrator lose unfiltered_html (2772edf, cf5555f). The capability is removed from every agent without manage_options, so their content goes through the normal KSES filtering. The check looks at the resolved primitive capability, so edit_css is covered as well. Administrator agents keep core behavior.
  • New wpai_is_agent_user() helper (e61e49b). It is an early entry point, the name may still change before the experiment settles. Code that picks a user to act as can call one documented function, instead of a raw meta query.

Two things I decided to postpone:

  • The site-owned KSES allowlist filter. The experiment adds no custom hooks until the identity model is confirmed, because a public filter is hard to remove later. It is the first hook I would consider after that.
  • Integrator guidance in the README. @webmyc, your offer to write that section still stands, and I would be happy to take it as a follow-up.

@jeffpaul jeffpaul linked an issue Sep 21, 2026 that may be closed by this pull request
1 task done
@jeffpaul jeffpaul modified the milestones: Future Release, 1.5.0 Sep 21, 2026
nerrad added a commit to nerrad/ai that referenced this pull request Sep 28, 2026
Brings in the Agent Users experiment exactly as proposed in WordPress#961 (head
dcae15b), rebased onto develop, so the
parent/child changes that follow can be reviewed as separate commits.

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
@nerrad

nerrad commented Sep 28, 2026

Copy link
Copy Markdown

I opened #1068 which builds on this PR to explore the "subuser" idea for these agent users.

@gziolo

gziolo commented Sep 29, 2026

Copy link
Copy Markdown
Member Author

@jeffpaul, I’ve updated the description to link to #211 and acknowledge @Jameswlepage’s prior work. I’ll also compare the approaches to see whether I missed anything important, and make sure James is credited when this is merged.

@nerrad, thank you for opening #1068 to make your suggestion more concrete. Am I understanding correctly that you see every agent account as acting on behalf of a specific human account, with that relationship being mandatory?

My initial thinking was to record who created the agent, but I hadn’t settled on how much that relationship should govern its behavior afterward. For example, on a site with multiple administrators, I imagined a shared agent account that authorized administrators could manage and use, with permissions defined by the agent’s own role.

Your proposal makes the parent relationship central: the agent’s permissions remain bounded by the parent’s current permissions, and its lifecycle is tied to that account. I can see the benefits for managing delegated access and attributing work as performed on someone’s behalf. Although, if multiple people use the same agent credentials, the parent relationship alone wouldn’t identify who initiated a particular action.

Do you think we should support both agents acting for an individual and shared agents managed at the site level, or should every agent require a human parent? I think clarifying that would help us decide whether parent ownership is fundamental to the identity model or an additional relationship we support.

@nerrad

nerrad commented Sep 29, 2026 •

Copy link
Copy Markdown

Am I understanding correctly that you see every agent account as acting on behalf of a specific human account, with that relationship being mandatory?

By default, yes. I think an important part of trust boundaries and audit trails is knowing who an agent acts on behalf of and any changes to that users authorization/capabilities should in turn apply to any agent(s) attached to them (which my PR does in a limited sense, would still need some work).

It gives site owners the ability to allow users to have agents act on their behalf on the site, while still controlling access and privileges primarily through the human user.

For example, on a site with multiple administrators, I imagined a shared agent account that authorized administrators could manage and use, with permissions defined by the agent’s own role.

I get the utility, but the audit trail for who directs the agent is less clear. If sites really wanted to operate with that model, they still could with my proposed approach, they'd just have to be more intentional about it (it's also why I left inline comments in my PR about addtional filters that could be added).

Also, have you thought through multi-site behaviour with the unattached agent model?

Although, if multiple people use the same agent credentials, the parent relationship alone wouldn’t identify who initiated a particular action

Sure, but that's an intentional choice by site owners to accept that dilution of the controls. Agent delegation has not removed that choice. It's the same in that case as if people share one login account.

Do you think we should support both agents acting for an individual and shared agents managed at the site level, or should every agent require a human parent?

I think we should start with every agent requiring a human parent. With the right extensibility around things like labelling, site owners could still use a shared credentials approach (for example create a "bot user" as the parent, and all agents are children of that user), but out of the gate we ship with a more secure, auditable, trust model. That gives space to evaluate the necessity for a standalone agent actor/user.

@josephfusco

Copy link
Copy Markdown

Could agents get a default avatar? Without a Gravatar, an agent gets the site default, so Presence API's admin bar shows a mystery person beside its Agent badge. A pre_get_avatar_data filter here could give them the plugin's flask icon instead, so every get_avatar() call would match. Gravatar only falls back to a public PNG, JPG or GIF, so it needs a raster copy, or the filter sets url directly.

@jeffpaul

jeffpaul commented Oct 4, 2026

Copy link
Copy Markdown
Member

A pre_get_avatar_data filter here could give them the plugin's flask icon instead, so every get_avatar() call would match.

Using the flask/beaker icon would be a nice touch :shipit:

@webmyc

webmyc commented Oct 5, 2026

Copy link
Copy Markdown
Contributor

One data point from production for @nerrad's sub-user idea in #1068, since it is the model Respira ships today: a connection is approved by a logged-in person in the browser, and the token is bound to that person and to the one site they approved. Revoking the person's access ends the agent's.

In practice agencies ask "which human let this agent in" more often than "which agent did this", so I lean toward the agent being tied to a parent by default, with the shared agent account @gziolo describes as the opt-in exception rather than the rule.

@gziolo

gziolo commented Oct 5, 2026 •

Copy link
Copy Markdown
Member Author

@webmyc, thank you for confirming that the proposal from @nerrad would be the preferred approach. I'm inclined to close this PR in favor of #1068 (@nerrad most likely can't push to this PR), as it builds on this work while ironing out a few important details around the parent user idea.

@josephfusco, great idea to change the default avatar. Let's ensure it gets integrated 👍🏻

@gziolo gziolo closed this Oct 5, 2026
@jeffpaul jeffpaul removed this from the 1.5.0 milestone Oct 5, 2026
nerrad added a commit to nerrad/ai that referenced this pull request Oct 9, 2026
WordPress#961 was closed in favor of this branch and never shipped, so no agents
exist from before the parent link. Describe parentless agents and the
multisite exception without pointing at it.
nerrad added a commit to nerrad/ai that referenced this pull request Oct 12, 2026
Brings in the Agent Users experiment exactly as proposed in WordPress#961 (head
dcae15b), rebased onto develop, so the
parent/child changes that follow can be reviewed as separate commits.

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
nerrad added a commit to nerrad/ai that referenced this pull request Oct 12, 2026
WordPress#961 was closed in favor of this branch and never shipped, so no agents
exist from before the parent link. Describe parentless agents and the
multisite exception without pointing at it.
nerrad added a commit to nerrad/ai that referenced this pull request Oct 25, 2026
Brings in the Agent Users experiment exactly as proposed in WordPress#961 (head
dcae15b), rebased onto develop, so the
parent/child changes that follow can be reviewed as separate commits.

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
nerrad added a commit to nerrad/ai that referenced this pull request Oct 25, 2026
WordPress#961 was closed in favor of this branch and never shipped, so no agents
exist from before the parent link. Describe parentless agents and the
multisite exception without pointing at it.
nerrad added a commit to nerrad/ai that referenced this pull request Oct 25, 2026
Gives external software a dedicated WordPress user, marked as an agent
and linked to a human parent it acts on behalf of (WordPress#923). An agent:

- authenticates only with Application Passwords: password login, resets,
  and password changes are blocked, and its password stays unknown;
- can never do more than its parent currently can, since every
  capability check is repeated for the parent after all other mapping;
- cannot hold a role that manages the site, change other users, or
  write unfiltered HTML;
- shares post ownership with its parent;
- is suspended, keeping its account and content, wherever its parent is
  missing, cannot have agents (`wpai_add_agents`), or is not a member.

Agent_Account answers who is an agent, who its parent is, and whether it
is suspended. Agent_Provisioner creates agents after checking the
provisioner, the parent, and that the role grants nothing either lacks.
Agent_Authentication and Agent_Capabilities enforce the rules, and Main
registers them whenever the plugin is active, independent of feature
toggles, since agent accounts outlive them. On multisite, provisioning
requires network activation, because the agent marker is network-wide.

Builds on the Agent Users experiment from WordPress#961.

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
nerrad added a commit to nerrad/ai that referenced this pull request Oct 25, 2026
Registers the Agent Users experiment, which loads provisioning and
presentation only while it and the AI features are enabled. Agent
management stays on core's user screens, because an agent is a user:

- Users → Add Agent reuses the Add User form, with a required parent
  field and without password or notification controls, then opens the
  agent's profile to create its first Application Password;
- the agent profile hides human-only settings and explains why an agent
  is suspended, and human profiles list their agents;
- the Users list labels agent roles with their parent, filters by
  account type, and swaps the password reset action for credentials;
- REST user responses expose read-only `wpai_is_agent` and
  `wpai_agent_parent` fields, for "agent on behalf of" bylines;
- agents fall back to the plugin's flask avatar.

On multisite without network activation, the Add Agent screen is
unavailable and the user screens explain why.

Builds on the Agent Users experiment from WordPress#961.

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
nerrad added a commit to nerrad/ai that referenced this pull request Nov 20, 2026
Gives external software a dedicated WordPress user, marked as an agent
and linked to a human parent it acts on behalf of (WordPress#923). An agent:

- authenticates only with Application Passwords: password login, resets,
  and password changes are blocked, and its password stays unknown;
- can never do more than its parent currently can, since every
  capability check is repeated for the parent after all other mapping;
- cannot hold a role that manages the site, change other users, or
  write unfiltered HTML;
- shares post ownership with its parent;
- is suspended, keeping its account and content, wherever its parent is
  missing, cannot have agents (`wpai_add_agents`), or is not a member.

Agent_Account answers who is an agent, who its parent is, and whether it
is suspended. Agent_Provisioner creates agents after checking the
provisioner, the parent, and that the role grants nothing either lacks.
Agent_Authentication and Agent_Capabilities enforce the rules, and Main
registers them whenever the plugin is active, independent of feature
toggles, since agent accounts outlive them. On multisite, provisioning
requires network activation, because the agent marker is network-wide.

Builds on the Agent Users experiment from WordPress#961.

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
nerrad added a commit to nerrad/ai that referenced this pull request Nov 20, 2026
Registers the Agent Users experiment, which loads provisioning and
presentation only while it and the AI features are enabled. Agent
management stays on core's user screens, because an agent is a user:

- Users → Add Agent reuses the Add User form, with a required parent
  field and without password or notification controls, then opens the
  agent's profile to create its first Application Password;
- the agent profile hides human-only settings and explains why an agent
  is suspended, and human profiles list their agents;
- the Users list labels agent roles with their parent, filters by
  account type, and swaps the password reset action for credentials;
- REST user responses expose read-only `wpai_is_agent` and
  `wpai_agent_parent` fields, for "agent on behalf of" bylines;
- agents fall back to the plugin's flask avatar.

On multisite without network activation, the Add Agent screen is
unavailable and the user screens explain why.

Builds on the Agent Users experiment from WordPress#961.

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Type] Proof of Concept PRs that explore new conceptual experiment functionality

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Introduce agent users to give AI agents an auditable identity

8 participants