nataondev / laravel-agent-native

v1.0.2 2026-09-23 14:49 UTC

Requires

• php: ^8.2
• illuminate/container: ^11.0|^12.0
• illuminate/contracts: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0

Requires (Dev)

• laravel/mcp: ^1.0
• laravel/pint: ^1.18
• livewire/livewire: ^3.0|^4.0
• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-laravel: ^3.0

Suggests

• laravel/mcp: Expose your #[AgentAction] methods as a standard MCP server (web + stdio) via the optional bridge (docs/mcp.md).
• livewire/livewire: Enable the Livewire bridge (InteractsWithAgent, AgentBridge) for in-app agent reactivity (v3+ or v4+).

MIT

• laravel
• agents
• ai
• mcp
• livewire
• llm
• tool-calling

Published on Packagist.org on 2026-09-23 14:50 UTC

README

Inspired by the Agent-Native architecture pioneered by Builder.io, brought natively to the Laravel & Livewire ecosystem.

Define an action once — a plain PHP method with an attribute. Your Livewire UI calls it, and LLM agents get it as a standards-compliant tool. No duplicated schemas, no manual tool registries.

#[AgentAction(description: 'Add a product to the shopping cart')]
public function addItem(int $productId, int $quantity = 1): void
{
    $this->items[] = compact('productId', 'quantity');
}

→ auto-compiled to OpenAI/MCP tool JSON, validated and executed through the container, with Livewire state/events in sync.

Install

composer require nataondev/laravel-agent-native
php artisan vendor:publish --tag=agent-native-config

• PHP 8.2+ · Laravel 11+ · Livewire 3+ or 4+ (optional)

How it works

1. Annotate — #[AgentAction] on any public method (service or Livewire component).
2. Compile — reflection builds the tool schema from native types, enums, and docblocks.
3. Execute — ActionExecutor validates arguments, resolves the class via the container, invokes, and returns a structured ActionResult.
4. React — AgentBridge notifies your app (and listening components) that the agent acted.

Documentation

Guide	What's inside
Installation	Requirements, setup, registering classes
Defining actions	#[AgentAction], #[AgentParam], #[AgentExpose], docblocks
Type mapping	Scalars, arrays, backed/pure enums, nullability → JSON Schema
Executing actions	ActionExecutor, ActionResult, error codes
Livewire integration	InteractsWithAgent, AgentBridge, component state
HTTP endpoint	AgentToolsController routes, security, payloads
MCP server	Optional laravel/mcp bridge — actions as standard MCP tools
Artisan commands	agent:inspect, agent:cache, agent:clear, agent:mcp
Caching	Zero-reflection production boot

Quick example

php artisan agent:inspect --json   # tool schemas, ready for your LLM

use AgentNative\Laravel\Engine\ActionExecutor;

$result = app(ActionExecutor::class)->call('addItem', ['productId' => 42]);

$result->ok;     // true
$result->output; // JSON-safe return value

Testing

composer test   # Pest — 35 tests
composer lint   # Pint

License

MIT