PHPackages                             roots/acorn-ai - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. roots/acorn-ai

ActivePackage[Utility & Helpers](/categories/utility)

roots/acorn-ai
==============

WordPress Abilities API integration and AI support for Acorn.

v0.1.2(2mo ago)16141↓50%[1 PRs](https://github.com/roots/acorn-ai/pulls)MITPHPPHP ^8.4CI passing

Since Feb 21Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/roots/acorn-ai)[ Packagist](https://packagist.org/packages/roots/acorn-ai)[ GitHub Sponsors](https://github.com/roots)[ RSS](/packages/roots-acorn-ai/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (3)Versions (8)Used By (0)

Acorn AI
========

[](#acorn-ai)

[![Packagist Downloads](https://camo.githubusercontent.com/306409cb6a701af5b2b3fdb09f4359a12058aaf74f7a79c0270f10fa3c5b9921/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f726f6f74732f61636f726e2d61693f6c6162656c3d646f776e6c6f61647326636f6c6f72423d32623330373226636f6c6f72413d353235646463267374796c653d666c61742d737175617265)](https://packagist.org/packages/roots/acorn-ai)[![Follow Roots](https://camo.githubusercontent.com/222256dbdeac58e77f017d847dca30ff4cab027cdf3abfec8e5bfd59de240547/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f666f6c6c6f7725323040726f6f747377702d3164613166323f6c6f676f3d74776974746572266c6f676f436f6c6f723d666666666666266d6573736167653d267374796c653d666c61742d737175617265)](https://twitter.com/rootswp)[![Sponsor Roots](https://camo.githubusercontent.com/31e13361135ff96d01f1eb97157d052029e6f236249996072d8b6bd60b40e9cd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f73706f6e736f72253230726f6f74732d3532356464633f6c6f676f3d676974687562267374796c653d666c61742d737175617265266c6f676f436f6c6f723d666666666666266d6573736167653d)](https://github.com/sponsors/roots)

AI support for [Acorn](https://github.com/roots/acorn) — wraps [laravel/ai](https://github.com/laravel/ai) and adds first-class integration with the [WordPress Abilities API](https://make.wordpress.org/core/2025/07/17/abilities-api/).

Support us
----------

[](#support-us)

Roots is an independent open source org, supported only by developers like you. Your sponsorship funds [WP Packages](https://wp-packages.org/) and the entire Roots ecosystem, and keeps them independent. Support us by purchasing [Radicle](https://roots.io/radicle/) or [sponsoring us on GitHub](https://github.com/sponsors/roots) — sponsors get access to our private Discord.

Requirements
------------

[](#requirements)

- PHP 8.4+
- WordPress 6.9+ (for Abilities API)
- [Acorn](https://github.com/roots/acorn) 5.0+

Installation
------------

[](#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

[](#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
-------------------------

[](#ai-providers--agents)

`roots/acorn-ai` includes [laravel/ai](https://github.com/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

[](#creating-an-agent)

```
wp acorn make:agent SupportAgent
```

### Creating a tool

[](#creating-a-tool)

```
wp acorn make:tool SearchPosts
```

Refer to the [laravel/ai documentation](https://github.com/laravel/ai) for full usage of agents, tools, structured output, and providers.

Abilities
---------

[](#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](https://github.com/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

[](#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

[](#registering-abilities)

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

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

### Ability names

[](#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

[](#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

[](#mcp-adapter)

To expose an ability as an MCP tool when the [WordPress MCP Adapter](https://github.com/WordPress/mcp-adapter) plugin is active, set `mcp.public` in `meta()`:

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

### Listing abilities

[](#listing-abilities)

```
wp acorn ability:list
```

Example: Post summarization via AI
----------------------------------

[](#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](https://github.com/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
---------

[](#community)

Keep track of development and community news.

- Join us on Discord by [sponsoring us on GitHub](https://github.com/sponsors/roots)
- Join us on [Roots Discourse](https://discourse.roots.io/)
- Follow [@rootswp on Twitter](https://twitter.com/rootswp)
- Follow the [Roots Blog](https://roots.io/blog/)
- Subscribe to the [Roots Newsletter](https://roots.io/subscribe/)

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance89

Actively maintained with recent releases

Popularity22

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 84.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~4 days

Total

3

Last Release

69d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f3f71fa88954b93f55af5e121f1d8c38d240a0d17712c092a389bcccffa34415?d=identicon)[retlehs](/maintainers/retlehs)

![](https://www.gravatar.com/avatar/1ab26aec6b8f0812974172b493176399142f03701c0578a40a0636fc9851bfdc?d=identicon)[QWp6t](/maintainers/QWp6t)

![](https://avatars.githubusercontent.com/u/5745907?v=4)[Brandon](/maintainers/Log1x)[@Log1x](https://github.com/Log1x)

---

Top Contributors

[![retlehs](https://avatars.githubusercontent.com/u/115911?v=4)](https://github.com/retlehs "retlehs (11 commits)")[![QWp6t](https://avatars.githubusercontent.com/u/2104321?v=4)](https://github.com/QWp6t "QWp6t (2 commits)")

---

Tags

acornacorn-packageailaravellaravel-aiwordpresswordpress-abilities-apiwordpress-laravelwordpressaiabilitiesacorn

###  Code Quality

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/roots-acorn-ai/health.svg)

```
[![Health](https://phpackages.com/badges/roots-acorn-ai/health.svg)](https://phpackages.com/packages/roots-acorn-ai)
```

###  Alternatives

[aristath/kirki

Extending the WordPress customizer

1.3k73.0k4](/packages/aristath-kirki)[afragen/git-updater

A plugin to automatically update GitHub, Bitbucket, GitLab, or Gitea hosted plugins, themes, and language packs.

3.3k1.6k](/packages/afragen-git-updater)[log1x/acorn-disable-media-pages

Disable media attachment pages in WordPress.

23147.6k](/packages/log1x-acorn-disable-media-pages)[tiny-pixel/acorn-block-templates

Block templates for Sage 10

191.2k](/packages/tiny-pixel-acorn-block-templates)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)