Agents API

The shared foundation for building AI agents in WordPress.

If you're building a plugin that needs an AI agent — one that can hold a conversation, call tools, run workflows, remember things between sessions, or talk to users through Slack, Telegram, or email — you shouldn't have to reinvent the plumbing every time. Agents API gives you that plumbing.

It's a small, focused WordPress package maintained by Automattic. Think of it as the layer that sits underneath your product: it owns the boring-but-important parts (agent identity, runtime contracts, tool mediation, sessions, transcripts, memory, workflow scaffolding), so your plugin can focus on what makes it special.

What you get out of the box: a way to register agents, a fallback provider-agnostic agents/chat runtime, a messaging channel base class that plugs into any transport, value objects for the agent lifecycle, contracts for tools and memory and consent, and lightweight workflow plumbing (spec, validator, runner, default ability, agent, foreach, and parallel step handlers, three abilities, and optional Action Scheduler-backed async branch execution).

What you don't get — and shouldn't expect: durable workflow history, a workflow editor UI, admin screens, or any provider-specific AI client. Those belong to your product. Agents API is the substrate, not the application.

New here? Start with the Introduction — it breaks down the core concepts and vocabulary in plain language — then browse the developer documentation.

Layer Boundary

wp-ai-client -> provider/model prompt execution and provider capabilities
Agents API   -> identity, runtime contracts, orchestration contracts, tool mediation contracts, memory/transcripts/sessions
Consumers    -> product UX, concrete tools, workflows, prompt policy, storage/materialization policy

Agents API sits between tool/action discovery and product-specific automation. It owns the reusable agent runtime contracts; product plugins own the user-facing product experience.

What Agents API Owns

• Agent registration and lookup.
• Messaging channel base class (WP_Agent_Channel) that maps an external transport (Telegram, Slack, WhatsApp, Email, …) onto the Abilities-API chat surface, with shared session continuity and lifecycle hooks.
• Runtime message, request, result, and completion value objects.
• Agent execution principal/context value objects.
• Agent access grant, token, token authenticator, authorization policy, and capability ceiling contracts.
• Multi-turn orchestration contracts.
• Opt-in mediated tool result truncation for oversized transcript payloads.
• Opt-in between-turn interrupt sources for cancel, redirect, or additional instruction messages.
• Canonical chat run-control contracts for run IDs, run status, best-effort cancellation, and queued messages.
• Canonical ability discovery and dispatch meta-abilities for large tool surfaces.
• Agent package and package-artifact contracts.
• Shared wp_guideline / wp_guideline_type storage substrate polyfill when Core/Gutenberg do not provide it.
• Agent memory store contracts and value objects.
• Generic memory/context source registry, context section registry, injection policy vocabulary, and composable context value object.
• Conversation compaction policy and transcript transformation contracts.
• Generic multi-turn conversation loop sequencing around caller-owned adapters.
• Iteration budget primitives for bounded execution across configurable dimensions.
• Tool-call mediation contracts and runtime tool declaration value objects.
• Generic tool visibility policy and action policy resolver contracts.
• Conversation transcript store contracts.
• Consent policy contracts for memory, transcripts, sharing, and escalation.
• Tool source registration, parameter normalization, tool-call mediation, and execution result contracts.
• Session and persistence contracts where they are provider-neutral.
• Retrieved context authority vocabulary, context item shape, and conflict resolution contracts.
• Workflow spec value object, structural validator, in-memory registry, runner with default ability, agent, foreach, and parallel step handlers, Store and Run_Recorder interfaces, optional Action Scheduler bridge and branch executor, and three canonical abilities (agents/run-workflow, agents/validate-workflow, agents/describe-workflow).
• Runtime package workflow execution request/result contracts and the canonical dispatcher ability (agents/run-runtime-package) for consumer-owned package materialization and execution adapters.

What Agents API Does Not Own

• Provider-specific request code. wp-ai-client owns provider/model prompt execution.
• Durable workflow / run history, scheduling adapters beyond the optional Action Scheduler bridge and branch executor, workflow editor UI, and product-specific step types (branch, nested workflow). The substrate provides default in-process step execution plus an optional Action Scheduler path for async parallel branches; consumers ship the persistence and product UX.
• Product UI such as admin pages, settings screens, dashboards, or onboarding.
• Product CLI commands beyond generic substrate needs.
• Public REST controllers in v1 unless they are separately designed.
• Product runner adapters that assemble prompts, choose concrete tools, materialize storage, or decide product policy.
• Concrete runtime package materialization, package source checkout, delegated-runtime provisioning, provider mapping, run polling, or evidence artifact upload. The package run contract only defines the request/result envelope and dispatcher seam.
• Concrete tool execution adapters, prompt assembly policy, or product storage/materialization policy.
• Product-specific consent UX, support routing, escalation targets, or transcript-sharing policy.
• Concrete memory retrieval, file projection, convention-path writing, or filesystem layout adapters.

Products can require Agents API because they build on the substrate. Agents API must not depend on any product plugin, import product classes, mirror a product source tree, or encode product vocabulary as generic runtime API.

Requirements

Agents API requires WordPress 7.0 or higher. The substrate itself is provider-agnostic and loads on earlier versions, but every realistic consumer needs an AI provider. The only WordPress-native provider story is wp-ai-client, which ships in WordPress 7.0 core. Sites running 6.8–6.9 can install Agents API without errors but won't have a working AI provider unless they manually install the deprecated wp-ai-client plugin.

Quality Gates

Agents API runs repository checks directly through Composer scripts:

• composer phpstan runs PHPStan at max level with WordPress stubs.
• composer smoke runs the current PHP smoke-test suite.

These checks keep the package self-contained for Core-candidate review while proving the runtime wiring and static contracts still behave as expected.

Core-Candidate API Naming

Agents API intentionally exposes WordPress-shaped public APIs such as wp_register_agent(), wp_get_agent(), wp_agents_api_init, and wp_agent_* hooks.

These names are not accidental plugin globals. They are the public API surface being evaluated for possible WordPress Core alignment, following existing Core naming conventions for substrate APIs. Plugin Check may report prefix warnings for these symbols; those warnings are expected for this Core-candidate package and should be reviewed in that context.

Installation

Agents API supports the same two delivery shapes used by other shared WordPress runtime packages such as Action Scheduler: install it as a normal WordPress plugin, or require it through Composer and load Composer's autoloader from the host project.

Both paths load the same agents-api.php bootstrap. The bootstrap is idempotent, so loading it through Composer and WordPress in the same request is safe.

WordPress Plugin

Install and activate the Agents API plugin through the normal WordPress plugin mechanism. This is the recommended path for site owners and plugins that declare Agents API as a plugin dependency.

Composer

Require the package from a host plugin, mu-plugin, or Composer-managed WordPress project:

composer require wordpress/agents-api:^0.1

Composer autoloads agents-api.php through the package files autoload entry. The consuming project must load Composer's generated vendor/autoload.php during WordPress bootstrap. After that, the same public API is available as in the plugin activation path.

Public agent package definitions are classmapped, so Composer-aware IDEs and static analyzers discover their concrete types without executing the WordPress runtime bootstrap.

Pin released tags (^0.1, 0.1.x, or an exact 0.1.0 tag) for reproducible production installs. Track main only for active substrate development.

Consumer Integration

Product plugins should treat Agents API as an optional or required runtime dependency depending on their feature surface.

For hard requirements, declare the plugin dependency using normal WordPress/plugin-distribution mechanisms and fail clearly when Agents API is unavailable.

For optional integrations, feature-detect the public API before registering agent-backed features inside the registration hook:

add_action(
    'wp_agents_api_init',
    static function () {
        if ( function_exists( 'wp_register_agent' ) ) {
            wp_register_agent( 'example-agent', array( /* ... */ ) );
        }
    }
);

Register agent definitions from inside a wp_agents_api_init callback. Reads such as wp_get_agent() and wp_has_agent() are safe after WordPress init has fired.

Agents can declare source provenance in meta so registration diagnostics can identify which plugin or package owns a slug:

wp_register_agent(
    'example-agent',
    array(
        'label' => 'Example Agent',
        'meta'  => array(
            'source_plugin'  => 'example-plugin/example-plugin.php',
            'source_type'    => 'bundled-agent',
            'source_package' => 'example-package',
            'source_version' => '1.2.3',
        ),
    )
);