README

AI support for Acorn — wraps laravel/ai and adds first-class integration with the WordPress Abilities API.

Support us

We're dedicated to pushing modern WordPress development forward through our open source projects, and we need your support to keep building. You can support our work by purchasing Radicle, our recommended WordPress stack, or by sponsoring us on GitHub. Every contribution directly helps us create better tools for the WordPress ecosystem.

Requirements

PHP 8.4+
WordPress 6.9+ (for Abilities API)
Acorn 5.0+

Installation

composer require roots/acorn-ai

Publish the config files:

# WordPress-specific config (abilities registration)
wp acorn vendor:publish --provider="Roots\AcornAi\AcornAiServiceProvider" --tag=ai-wordpress-config

# AI provider config (providers, API keys, defaults)
wp acorn vendor:publish --provider="Laravel\Ai\AiServiceProvider" --tag=ai-config

Add your provider API keys to .env:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

WordPress AI Connectors

API keys configured through laravel/ai are automatically passed to WordPress AI provider plugins via environment variables. This means you don't need to enter keys on the WordPress Connectors settings page, and your keys are never stored in wp_options.

Supported providers: OpenAI, Anthropic, and Gemini (Google).

AI Providers & Agents

roots/acorn-ai includes laravel/ai and makes it available inside WordPress via Acorn's container. You get the full laravel/ai feature set: agents, tools, embeddings, image generation, audio, transcription, and reranking — all configured through config/ai.php (published from laravel/ai).

Creating an agent

wp acorn make:agent SupportAgent

Creating a tool

wp acorn make:tool SearchPosts

Refer to the laravel/ai documentation for full usage of agents, tools, structured output, and providers.

Abilities

The WordPress Abilities API (WordPress 6.9+) provides a standardized way to define capabilities that AI agents can invoke — via REST API (wp-abilities/v1/abilities/{name}/run) and the WordPress MCP Adapter.

roots/acorn-ai wraps ability registration so that your ability classes are resolved through Laravel's service container, giving you full dependency injection.

Creating an ability

wp acorn make:ability CreatePost

This generates app/Ai/Abilities/CreatePostAbility.php:

namespace App\Ai\Abilities;

use Roots\AcornAi\Abilities\Ability;

class CreatePostAbility extends Ability
{
    public function __construct(private PostRepository $posts) {}

    public function label(): string
    {
        return 'Create Post';
    }

    public function description(): string
    {
        return 'Creates a new WordPress post with the given title and content.';
    }

    public function execute(array $input): mixed
    {
        return $this->posts->create($input['title'], $input['content'] ?? '');
    }

    public function inputSchema(): array
    {
        return [
            'type' => 'object',
            'properties' => [
                'title' => ['type' => 'string', 'description' => 'The post title.'],
                'content' => ['type' => 'string', 'description' => 'The post body.'],
            ],
            'required' => ['title'],
        ];
    }
}

Registering abilities

Add your ability classes to config/ai-wordpress.php:

'abilities' => [
    \App\Ai\Abilities\CreatePostAbility::class,
],

Ability names

The default name is derived from the root namespace and class name:

\App\Ai\Abilities\CreatePostAbility  →  "app/create-post"

Override name() to use a custom name:

public function name(): string
{
    return 'app/create-post';
}

Permissions

Override permission() to control access. Return true, false, or a WP_Error:

public function permission(): bool|\WP_Error
{
    return current_user_can('edit_posts');
}

MCP Adapter

To expose an ability as an MCP tool when the WordPress MCP Adapter plugin is active, set mcp.public in meta():

public function meta(): array
{
    return [
        'mcp' => ['public' => true],
    ];
}

Listing abilities

wp acorn ability:list

Example: Post summarization via AI

This example shows a realistic ability that uses laravel/ai under the hood to summarize a WordPress post, exposes it over REST, and makes it available as an MCP tool for AI agents like Claude or Cursor.

Generate the class:

wp acorn make:ability SummarizePost

app/Ai/Abilities/SummarizePostAbility.php:

namespace App\Ai\Abilities;

use Illuminate\Support\Facades\Cache;
use Laravel\Ai\AnonymousAgent;
use Roots\AcornAi\Abilities\Ability;

class SummarizePostAbility extends Ability
{
    public function name(): string
    {
        return 'app/summarize-post';
    }

    public function label(): string
    {
        return 'Summarize Post';
    }

    public function description(): string
    {
        return 'Generates a concise summary of a WordPress post given its ID. '
            . 'Use this when you need a brief overview of a post without retrieving its full content.';
    }

    public function execute(array $input): mixed
    {
        $post = get_post($input['post_id']);

        if (! $post || $post->post_status !== 'publish') {
            return new \WP_Error('not_found', 'Post not found.');
        }

        return Cache::remember("ai-summary-{$post->ID}", now()->addDay(), function () use ($post) {
            $content = wp_strip_all_tags($post->post_content);

            return AnonymousAgent::make(
                instructions: 'You are a helpful assistant that summarizes blog posts in 2-3 sentences.',
                messages: [],
                tools: [],
            )->prompt("Summarize this post:\n\n{$content}")->text;
        });
    }

    public function permission(): bool|\WP_Error
    {
        return is_user_logged_in();
    }

    public function inputSchema(): array
    {
        return [
            'type' => 'object',
            'properties' => [
                'post_id' => [
                    'type' => 'integer',
                    'description' => 'The ID of the post to summarize.',
                ],
            ],
            'required' => ['post_id'],
        ];
    }

    public function meta(): array
    {
        return [
            'mcp' => ['public' => true],
        ];
    }
}

Register it in config/ai-wordpress.php:

'abilities' => [
    \App\Ai\Abilities\SummarizePostAbility::class,
],

What this gives you:

REST API — any authenticated client can call POST /wp-json/wp-abilities/v1/abilities/app/summarize-post/run with {"post_id": 42}
MCP tool — when the WordPress MCP Adapter is active, the ability is surfaced to connected AI agents automatically
Caching — summaries are cached for 24 hours so repeated calls don't burn API credits
Container injection — swap AnonymousAgent for a dedicated agent class or any injected service by adding constructor dependencies to the ability

Community

Keep track of development and community news.

Join us on Discord by sponsoring us on GitHub
Join us on Roots Discourse
Follow @rootswp on Twitter
Follow the Roots Blog
Subscribe to the Roots Newsletter

roots / acorn-ai

Maintainers

Package info

Fund package maintenance!

Statistics

Security