Download the PHP package whilesmart/eloquent-agent-actions without Composer

whilesmart/eloquent-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, 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

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:

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:

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

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.

Register handlers in config/agent-actions.php:

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

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:

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:

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:

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.