README

What does this package do?

This package offers an architectural pattern that sits on top of laravel/ai to provide a consistent, structured, and testable way to execute AI actions in your Laravel app.

If you're wiring AI calls directly into controllers or service classes, you're reinventing this. laravel-ai-action gives every AI capability in your app a consistent, discoverable home — the same way laravel/actions does for business logic.

Requirements

Installation

composer require pixelworxio/laravel-ai-action

Publish the config to customise defaults:

php artisan vendor:publish --tag=ai-action-config

Quick Start

php artisan make:ai-action SummarizePost

// app/Ai/Actions/SummarizePost.php
final class SummarizePost implements AgentAction
{
    use InteractsWithAgent;

    public function instructions(AgentContext $context): string
    {
        return 'You are a concise technical writer. Summarize in three sentences.';
    }

    public function prompt(AgentContext $context): string
    {
        return sprintf("Summarize:\n\n%s", $context->record->body);
    }

    public function handle(AgentContext $context): AgentResult
    {
        return app(RunAgentAction::class)->execute($this, $context);
    }
}

// In a controller or job
$context = AgentContext::fromRecord($post);
$result  = $this->runner->execute(new SummarizePost(), $context);

echo $result->text;         // "This post covers..."
echo $result->inputTokens;  // 320

MCP Bridge (opt-in)

Expose any AgentAction as a Laravel MCP tool — reachable from Claude Desktop, Cursor, and any MCP-aware client — with a few additional methods and one env flag.

composer require laravel/mcp

AI_ACTION_MCP_ENABLED=true

php artisan make:ai-action SummarizeInvoice --mcp

// In your AppServiceProvider::boot():
use Pixelworxio\LaravelAiAction\Mcp\Facades\AiActionMcp;

AiActionMcp::tool(\App\Ai\Actions\SummarizeInvoice::class);

See docs/mcp.md for the full guide including auth scoping, annotation forwarding, auto-discovery, and custom response formatting.

Documentation

• Actions — creating actions, contracts, and execution modes
• Context — AgentContext reference and usage
• Results — AgentResult reference and usage
• Testing — FakeAgentAction and fluent assertions
• Configuration — all config keys and environment variables
• Queue — background execution with RunAgentActionJob
• MCP Bridge — exposing actions as MCP tools (opt-in)

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.