PHPackages                             whilesmart/eloquent-agent-actions - 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. whilesmart/eloquent-agent-actions

ActiveLibrary

whilesmart/eloquent-agent-actions
=================================

DB-tracked agent action ledger with a handler registry and scheduler for Laravel applications.

1.0.0(1mo ago)0251MITPHPPHP ^8.2CI passing

Since Jul 14Pushed 1mo agoCompare

[ Source](https://github.com/whilesmartphp/eloquent-agent-actions)[ Packagist](https://packagist.org/packages/whilesmart/eloquent-agent-actions)[ RSS](/packages/whilesmart-eloquent-agent-actions/feed)WikiDiscussions dev Synced 1w ago

READMEChangelog (1)Dependencies (6)Versions (6)Used By (0)

whilesmart/eloquent-agent-actions
=================================

[](#whilesmarteloquent-agent-actions)

A DB-tracked ledger for actions an AI agent proposes or performs. Each action is persisted with a lifecycle (proposed, confirmed, executed, rejected, expired, failed), scoped to an owner (a workspace, organization, user) through [`whilesmart/eloquent-owner-access`](https://github.com/whilesmartphp/eloquent-owner-access), and executed by a handler resolved on its `action_type`. Actions can run immediately on confirm, or be scheduled for later with optional RRULE recurrence.

Install
-------

[](#install)

```
composer require whilesmart/eloquent-agent-actions
php artisan migrate

```

Routes register automatically under the `api` prefix with `auth:sanctum`. Set `AGENT_ACTIONS_REGISTER_ROUTES=false` to mount them yourself.

Owning model
------------

[](#owning-model)

Add the trait to whatever owns actions:

```
use Whilesmart\AgentActions\Traits\HasAgentActions;

class Workspace extends Model
{
    use HasAgentActions;
}

$workspace->agentActions()->create([
    'action_type' => 'send_mail',
    'payload' => ['to' => 'a@b.com', 'subject' => 'Hi'],
    'metadata' => ['agent_run_id' => 42],
    'summary' => 'Email the customer',
    'risk' => 'medium',
]);
```

`payload` is the execution input; `metadata` is a separate free-form column for an originating agent-run id, tags, or cost. An `idempotency_key` is generated per action when omitted.

An action can point back to whatever triggered it (a chat message, an inbound email, a webhook event) through the polymorphic `source`, alongside the `owner`it acts for and the `executed_resource` it produces:

```
$action->source()->associate($chatMessage)->save();
$action->source;   // the chat message, resolved back through morphTo
```

`source` carries no database foreign key (like `owner`), so cleaning up an action when its source is deleted is the host's choice, e.g. a model observer.

Handlers
--------

[](#handlers)

The package is host-agnostic: it does not know how to send mail or call a webhook. The host supplies that by registering handlers keyed on `action_type`.

```
use Whilesmart\AgentActions\Contracts\ActionHandler;
use Whilesmart\AgentActions\Models\AgentAction;

class SendMailHandler implements ActionHandler
{
    public function type(): string
    {
        return 'send_mail';
    }

    public function execute(AgentAction $action): mixed
    {
        // ... send the mail, optionally return the created record
    }
}
```

Register handlers in `config/agent-actions.php`:

```
'handlers' => [
    App\AgentActions\SendMailHandler::class,
],
```

The package ships one built-in handler, `NullActionHandler` (type `noop`), which marks an action executed without side effects. Return an Eloquent model from `execute()` to record it as the action's `executed_resource`; throw to mark the action failed with the message. Each run fires `AgentActionExecuted` or `AgentActionFailed` for the host to bridge.

Endpoints
---------

[](#endpoints)

MethodPathPurposeGET`/api/agent-actions`List (filter by `status`, `action_type`, owner)POST`/api/agent-actions`Create a proposed actionGET`/api/agent-actions/{action}`ShowPOST`/api/agent-actions/{action}/confirm`Confirm, then execute now or arm for the schedulerPOST`/api/agent-actions/{action}/reject`RejectGET`/api/agent-actions/batches/{batch}`Show a batch's membersPOST`/api/agent-actions/batches/{batch}/confirm`Confirm every pending memberPOST`/api/agent-actions/batches/{batch}/reject`Reject every pending memberAction batches
--------------

[](#action-batches)

When an agent proposes several actions from one instruction (say the line items of a receipt, or a set of transfers), batch them so the user confirms or rejects the set in one call instead of one round-trip per action. Batch with the trait:

```
$actions = $workspace->proposeActionBatch([
    ['action_type' => 'record_transaction', 'payload' => ['amount' => 12.5]],
    ['action_type' => 'record_transaction', 'payload' => ['amount' => 40.0]],
], ['risk' => 'low']);          // second arg: attributes shared by every member

$batch = $actions->first()->batch;
```

A batch is just a set of ordinary actions sharing a `batch` id. Confirming the batch applies the normal per-action rule to each member: an immediate one runs now, a future-scheduled one is armed. It is partial-safe and idempotent, one member failing does not block the rest, already-resolved members are skipped on a retry, and confirm returns a tally:

```
{ "executed": 2, "armed": 0, "failed": 0, "skipped": 0 }
```

Scheduling
----------

[](#scheduling)

Set `scheduled_at` / `next_trigger_at` in the future and the confirm endpoint arms the action instead of running it. The host schedules the sweep command:

```
// routes/console.php
Schedule::command('agent-actions:process-due')->everyMinute();
```

`agent-actions:process-due` runs every due action (`AgentAction::query()->due()`) through its handler. An action with a `repeat_rule` (RRULE, e.g. `FREQ=DAILY`) is rescheduled to its next occurrence after each run.

Status & risk
-----------------

[](#status--risk)

`ActionStatus`: `proposed`, `confirmed`, `executed`, `rejected`, `expired`, `failed`. `ActionRisk`: `low`, `medium`, `high`. Both are stored as plain strings and cast to enums on the model.

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance90

Actively maintained with recent releases

Popularity16

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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

Unknown

Total

1

Last Release

46d ago

### Community

Maintainers

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

---

Top Contributors

[![nfebe](https://avatars.githubusercontent.com/u/14317775?v=4)](https://github.com/nfebe "nfebe (6 commits)")

###  Code Quality

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/whilesmart-eloquent-agent-actions/health.svg)

```
[![Health](https://phpackages.com/badges/whilesmart-eloquent-agent-actions/health.svg)](https://phpackages.com/packages/whilesmart-eloquent-agent-actions)
```

###  Alternatives

[backpack/crud

Quickly build admin interfaces using Laravel, Bootstrap and JavaScript.

3.4k3.8M231](/packages/backpack-crud)[code16/sharp

Laravel Content Management Framework

79466.8k10](/packages/code16-sharp)[statamic-rad-pack/runway

Eloquently manage your database models in Statamic.

138249.0k8](/packages/statamic-rad-pack-runway)[duncanmcclean/statamic-cargo

Comprehensive e-commerce addon for Statamic. Build bespoke e-commerce sites without the complexity.

3622.8k](/packages/duncanmcclean-statamic-cargo)[ecotone/laravel

Ecotone for Laravel — CQRS, Event Sourcing, Sagas, Durable Workflows, and Outbox on top of Laravel Queue, via PHP attributes.

21336.4k4](/packages/ecotone-laravel)[api-platform/laravel

API Platform support for Laravel

58190.1k22](/packages/api-platform-laravel)

PHPackages © 2026

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