pixelworxio / laravel-ai-action

1.1.0 2026-07-31 13:10 UTC

Requires

• php: ^8.4
• laravel/ai: ^0.1 || ^0.2 || ^0.3 || ^0.4 || ^0.5 || ^0.6 || ^0.7 || ^0.8 || ^0.9 || ^0.10
• laravel/framework: ^12.0 || ^13.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/mcp: >=0.1
• laravel/pint: ^1.14
• laravel/pulse: ^1.7
• livewire/livewire: ^4.3
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^10.0 || ^11.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-arch: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0

Suggests

• laravel/mcp: Required to expose agent actions as MCP tools (>=0.1).
• laravel/pulse: Required for the bundled AgentActionRecorder and Pulse dashboard card.

MIT

• @whoisthisstud

• laravel
• actions
• ai
• mcp

Published on Packagist.org on 2026-07-31 13:11 UTC

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.

	laravel/ai	laravel-ai-action
Abstraction level	Agents, tools, streaming primitives	Single-responsibility action classes
Context passing	Manual	AgentContext DTO (record, meta, user instruction)
Output handling	Raw response objects	Typed AgentResult with token tracking
Structured output	StructuredAnonymousAgent	HasStructuredOutput + mapOutput()
Streaming	Iterator + event handling	HasStreamingResponse callbacks
Queue support	None built-in	RunAgentActionJob (unique, queueable)
Testing	Mock the SDK	FakeAgentAction + fluent assertions
Artisan scaffolding	None	php artisan make:ai-action
Resilience	Manual	HasMiddleware — retry, idempotency, provider fallback
Cost tracking	Manual	AgentResult::cost() from a configurable pricing table
Observability	None built-in	Opt-in Laravel Pulse card

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

Dependency	Version
PHP	^8.4
Laravel	^12.0 || ^13.0
laravel/ai	^0.1

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.

Middleware, Cost Tracking & Observability

Wrap any action's execution in a middleware pipeline — the same pattern Laravel uses for queued jobs — for retries, idempotency, and provider fallback:

public function middleware(): array
{
    return [
        new Idempotent(ttl: now()->addHour()),
        new FallbackProvider(['openai']),
        new RetryAgentCall(times: 3, backoffSeconds: [1, 5, 10]),
    ];
}

Every AgentResult can report its own USD cost via $result->cost(), computed from a configurable per-model pricing table. And when Laravel Pulse is installed, an opt-in <livewire:pulse.ai-actions /> card shows call volume, cost, latency, and token usage per action — no bespoke dashboard to maintain.

See docs/middleware.md, docs/cost-tracking.md, and docs/pulse.md.

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)
• Middleware — retries, idempotency, and provider fallback
• Cost Tracking — per-call USD cost from token usage
• Laravel Pulse — production observability dashboard (opt-in)

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.