Filament Agents Laravel Package

Product Decisions This Supports

• Roadmap acceleration: "AI assistant in the back-office" moves from a multi-quarter build to a scoped, reversible pilot. Chat, tool-calling, conversation storage, approval handling, budgets, and an audit surface are already built. The roadmap question stops being can we afford this? and becomes which records and which tools do we expose first, in what order, to whom? — which is a product question we can actually answer this quarter.
• Build vs. buy for agent plumbing. This is the concrete answer to the standing "do we build our own turn loop, tool registry, conversation store, budget enforcement, and approval flow?" The buy case is strongest precisely when our differentiation is which capabilities operators can reach and which records they touch — not how the loop runs. Book the saved engineering time against the adoption risk below; don't pretend the risk is zero.
• One tool surface, two delivery channels. A single tool list feeding both the in-panel assistant and an MCP server is a strategic decision, not an implementation detail. The capabilities we give operators also become available to external MCP clients (desktop AI clients, IDEs, other agents) with no second build. That makes "expose our admin toolset over MCP" a cheap follow-on bet rather than a separate workstream — plan it as one, with its own access and support story, or don't expose it at all.
• Security posture: the assistant inherits the panel's authorization, tenancy, and policies. Reusing the existing Filament guard, tenant context, and policies instead of standing up a parallel permission model is a compliance and audit decision, not a shortcut. Fewer surfaces to review, tenant isolation preserved, and a reviewer can reason about AI access using rules they already know. This is the most defensible thing in the package and the first thing I'd put in front of a security reviewer.
• Mutation risk becomes product policy we own. Committing to approve-before-write is what makes write actions (create/update records, trigger operations) offerable at all. The current semantics are fail-closed: a typed reply over a waiting proposal is read by an app-owned rule, per-locale word lists (extendable and replaceable in our app), and an opt-in classifier — and ambiguous or conditional replies ("Ok?", "Yes, but only Alpha.") no longer approve. Two PM implications: consent defaults to no, and approval UX must be localized and tested per locale we serve. That is a policy we ship, not a dependency we consume — budget product and QA time for it.
• Decision provenance as a first-class product surface. The AI turns page now carries a Decided by column — our rule, the word lists, or the classifier — with the classifier's reason on hover, the reading classifier and its lowest confidence once the engine reaches 1.10 ("Jev · 0.94"), and a filter on the column. "Why did the agent write that record?" becomes a filterable, auditable answer instead of a log dive. For a governed back-office, that's the difference between a demo and something a risk owner will sign.
• Answer format is a product decision: structured, not prose. Live tables and charts rendered through our own Filament resources — with our filters, pagination, and list controls — sets the expectation that an "answer" is the panel, not a markdown approximation of it. It also means answer quality is partly a function of how good our resources already are, which is a useful forcing function.
• Cost governance ships as a feature, not a footnote. Per-workspace budgets, an operator limits page, and model configuration make "who can spend what on AI" a configurable surface. This is what gets a finance owner to sign, and what lets us turn the assistant on for a pilot cohort without uncapped exposure.
• Database choice stops being an AI-feature constraint. Postgres parity for chat search (case-insensitive matching across search, snippets, and the "@" record picker), null-safe sorting of unclassified chats, and a guarded tenant lookup remove the "chat search is subtly broken on our fleet" line from the risk register. Teams standardized on Postgres can adopt without a caveat.
• Use cases, roughly in order of adoption ease: internal ops/admin back-offices; B2B SaaS tenant admins querying their own data in natural language; support and CS tooling; any Filament panel where operators already live and "ask the panel" beats "open a separate BI tool."
• Architectural boundary decision: we own the domain, the package owns the loop. Record shapes, filter vocabulary, prompt domain content, and now approval rules and locale word lists stay in our app behind AgentResource and the agent's slots. Deciding this up front keeps the AI surface refactorable and stops the assistant from becoming a shadow schema.

When to Consider This Package

Adopt when:

• The panel is Filament v5 on PHP 8.4+. Hard floors, no fallback path.
• You want both the in-panel assistant and the MCP server over one tool list. If you only need chat, the MCP half is unused scope you still maintain.
• You need approve-before-write semantics and will model mutating tools as approvable — and you accept ownership of the approval-reading policy (rule, per-locale word lists, optional classifier). Plan to write, localize, and test it in every locale you support.
• You want auditable decision provenance: the Decided by column, classifier reasons and confidence, and its filter. If nobody will ever ask "why did it do that?", this is overhead.
• You need per-workspace budgets and an operator limits page — the clearest place the package earns its keep versus rolling your own.
• You want answers to reuse existing Filament resources rather than bespoke rendering.
• You run Postgres, MySQL, or SQLite; all three are exercised in CI and the Postgres search/sort/tenant-lookup defects are fixed.
• You accept a lockstep dependency on the sibling engine (^1.9 as of v1.16; the confidence display lands with engine 1.10). Plugin and engine upgrade as a pair; tools, budget rules, migrations, and config live upstream and shape your upgrade path.
• You can tolerate early-stage maturity: 13 stars, 0 dependents, MIT, active release cadence. That means pinned versions, reading changelogs, and willingness to file or fix issues.

Look elsewhere when:

• You are not on Filament v5 or are below PHP 8.4.
• You need a vendor with an SLA, a completed security review, or a long support window. Single-maintainer, low-adoption packages are a real supply-chain consideration — require a code review and a fork/vendoring strategy before production.
• You need provider-agnostic model integration; you inherit the laravel/ai ecosystem's constraints.
• You want read-only assistance. The approval machinery, provenance tooling, and budget/limits pages are pure overhead.
• You need channels beyond panel + MCP (email, Slack, voice). The package is panel-centric by design.
• Your team won't own the domain layer behind AgentResource and agent slots — including, since v1.16, approval-reading rules and locale word lists. The package deliberately does not carry your record shapes, prompt content, or consent vocabulary.
• You need a stable approval contract with no behavioral change on minor upgrades. v1.16 changed what counts as consent; if operators were trained on the old behavior, that's a UX and documentation dependency, not just a version bump.
• You require battle-tested references. Zero dependents means we are an early adopter, not a follower — say so out loud in the business case.

How to Pitch It (Stakeholders)

For executives (one paragraph): This package puts an AI assistant inside our admin panel and, from the same tool list, exposes those capabilities as an MCP server — operators get natural-language access to the panel and external AI clients can use the same surface, without two builds. It reuses the panel's existing authorization and tenant isolation, requires explicit in-chat approval before any write, and that approval is fail-closed: ambiguous replies like "Ok?" or "Yes, but only Alpha." do not authorize a write, the reading rules and per-locale vocabulary are ours to own, and every decision is recorded in a filterable Decided by column with the classifier's reason and confidence. Answers render as our own live tables and charts, Postgres behaves the same as our other databases, and per-workspace budgets plus an operator limits page keep AI spend governed rather than open-ended. The business case is time-to-value on the AI roadmap plus avoided build cost on the plumbing — loop, tools, approvals, budgets, audit trail. The risk is maturity: MIT and actively released, but early-adoption (small install base, single maintainer). Mitigate by pinning versions, code-reviewing the dependency, and running the first deployment as a controlled pilot with a named owner and a documented exit path (fork or vendor).

For engineering (the short version): It's a thin Filament v5 plugin over a sibling engine. v1.16 requires packstub/agents ^1.9 — pin and upgrade them as a pair. One tool list feeds the panel chat (laravel/ai) and the MCP server (laravel/mcp). Panel authorization is the source of truth: FilamentContext binds panel, guard, and tenant, and TenantSet keeps firing. Writes go through the approvable-tool path; RunAgentTurn/AgentTurns/TurnController own the turn loop, with a poll route and an AgentTable Livewire component for embedded resource tables. Approval parsing changed: a reply typed over a waiting proposal is read by the app's rule, per-locale word lists (extendable/replaceable in-app), and an opt-in classifier; ambiguous or conditional replies no longer approve and instead land in the transcript with a Decided by value — so audit and telemetry read from that column rather than parsing transcripts. Postgres fixes: chat search, snippets, and the "@" record picker use case-insensitive matching; unclassified chats sort null-first ascending and null-last descending; tenant lookup no longer passes a slug into an integer key. CI runs Postgres and MySQL alongside SQLite. Budgets and an operator limits resource are built in. Boundary to respect: anything running without a panel — tools, budget rules, migrations, config — belongs in the engine repo; our domain logic (record shapes, filters, prompt domain block, approval vocabulary) stays in our app behind AgentResource and the agent's slots. Watch the coupling: plugin and engine versions move together, PHP 8.4+ and Filament v5 are hard floors, and upstream changes are expected to ship with tests and a changelog. Plan a spike against a staging panel on Postgres with a widget resource fixture, and explicitly exercise an ambiguous approval reply in a non-English locale, before committing.