README

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, 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

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

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 source, originating agent-run id, tags, or cost. An idempotency_key is generated per action when omitted.

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

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

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