LarAgent: an Eloquent-style agent framework for Laravel applications
Power of AI Agents in your Laravel project
At a glance
- What is it?
- LarAgent packages AI agent construction into Laravel conventions: an artisan generator, an Agent base class, tool attributes and pluggable chat history. It fits teams already inside a Laravel codebase, and it is a poor fit if you need a language-agnostic runtime or a stable API surface.
- Who is it for?
- Adopt LarAgent if your agents live inside an existing Laravel application and you want them expressed as PHP classes with artisan scaffolding, tool attributes and Laravel's cache or queue layer underneath. Do not adopt it if you need a runtime that works outside PHP, if you require a frozen public API, or if you cannot accept that the README documents configuration but not failure behaviour.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 26 days ago.
- What is it written in?
- Mainly PHP, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem LarAgent targets: agents as application code, not scripts
Most agent code starts as a script. A prompt, a loop, a few function calls, and a file that grows until nobody wants to touch it. LarAgent's premise is that this belongs in the application layer, next to your models and controllers, and that the framework should supply the scaffolding rather than a separate service. The README frames it as an agent development framework for Laravel and states that agents should be created the way you create an Eloquent model.
The intended audience is narrow and specific. It is a PHP developer working in a Laravel codebase who already has users, authentication, a database and possibly a queue worker running. If that describes you, the appeal is that an agent becomes another class in App\AiAgents, reachable through the same dependency injection and configuration machinery as the rest of the app. If you are building an agent platform that must serve clients written in other languages, or you are prototyping in a language other than PHP, nothing here helps you.
What the Agent class actually holds
The generated class extends LarAgent\Agent and declares its behaviour through protected properties and two methods. The README example sets $model, $history, $provider and $tools, then defines instructions() returning the system text and prompt($message) returning the transformed user input. That is the whole contract shown in the material: properties for configuration, methods for content.
Configuration is per-agent and per-property. The README shows $history being switched from the string 'in_memory' to the class LarAgent\History\CacheChatHistory::class, $temperature set to 0.5, and $parallelToolCalls set to false to disable parallel tool calls. Each of these is a class-level declaration, which means changing an agent's memory backend or sampling temperature is a code change and a deploy, not a runtime flag. That is a deliberate trade-off in favour of readability, and it also means you cannot tune an agent per tenant without subclassing or overriding the property.
The provider property accepts more than a string. The README gives two forms: a flat array such as ['default', 'gemini', 'claude'] where the first entry is primary and the rest are fallbacks in order, and an array mixing plain names with per-provider overrides, for example 'gemini' => ['model' => 'gemini-2.0-flash']. Failover is therefore expressed as ordered configuration rather than as exception handling in your own code. What the README does not describe is what triggers a fallback, whether a rate limit and a malformed response are treated the same way, or whether a partially completed tool call is retried on the next provider. Those are the questions to answer before relying on the array for production resilience.
Tools are methods with an attribute
A tool is a public method carrying the #[Tool] attribute with a description string. The README example is a weather tool taking $location and an optional $unit defaulting to 'celsius', returning a formatted string. The description is the only metadata shown; parameter types and defaults are read from the PHP signature. This keeps tool definitions next to the code that implements them, which is a genuine advantage over registering tools in a separate manifest that drifts from the implementation.
The constraint is that everything the model can call must be a method on the agent class or reachable through one. If your tools are HTTP endpoints owned by another team, you are writing a thin PHP wrapper per endpoint. The README also points to a separate MCP client package, described as a modular client for managing tools and resources from MCP servers, and the 1.4.0 release notes mention an MCP client update. The README does not show the wiring between an MCP server and the $tools property, so treat MCP integration as something to verify against the linked package rather than something documented in the main repository.
Getting it running: the commands and the config surface
The README gives one command for scaffolding an agent: php artisan make:agent YourAgentName. It does not print the installation command in the excerpt, but the Packagist badge and the package name maestroerror/laragent indicate a Composer package, so installation follows the usual composer require path described in the documentation's Installation section. The README's own table of contents lists Requirements, Installation and Configuration as separate steps, which tells you the package documents prerequisites rather than assuming them. Read that Requirements section before you start, because the supported PHP and Laravel versions are exactly the kind of detail that changes between releases.
Running an agent is a static call. The README shows YourAgentName::forUser(auth()->user())->respond($message) for per-user history and YourAgentName::for("custom_history_name")->respond($message) for a named conversation. The history key is the argument to for(), which means conversation identity is your responsibility. Two users sharing a history name share a conversation. The configuration keys visible in the README are the protected properties themselves: $model, $history, $provider, $tools, $temperature and $parallelToolCalls. There is no separate config file shown, so if the documentation mentions a published config file, that is additional material not present in the README excerpt.
Memory, history and where conversations actually live
The $history property is the most consequential setting in the class. The README shows two values: the string 'in_memory' and the class LarAgent\History\CacheChatHistory::class. In-memory history does not survive the request, and in a typical PHP deployment it does not survive the worker either. Cache-backed history moves the conversation into Laravel's cache layer, which means the lifetime of a conversation is the lifetime of a cache entry, and eviction is a normal event rather than an error case.
That is a real design boundary. If you need conversation history that is queryable, auditable, exportable or subject to retention rules, the two drivers shown here are not obviously the right home for it. The README describes pluggable memory and context management as a feature, and the ability to point $history at a class implies you can write your own driver. Whether the interface for that is documented and stable is not visible in the material. Anyone who needs durable, inspectable transcripts should confirm the driver contract before designing around it, because a cache eviction mid-conversation is a silent loss of context, not an exception you can catch.
Release history and the maintenance you are signing up for
The repository is not archived and the most recent push is dated 2026-08-20. Three releases appear in the material: 1.2.2 on 2026-03-11 covering Gemini streaming and empty tool_use fixes, 1.3.0 on 2026-03-25 adding the OpenAI Responses API, and 1.4.0 on 2026-05-09 adding Laravel 13 support and an MCP client update. The pattern is a minor release roughly every six to seven weeks, with provider-specific work driving most of it.
Read that cadence as a cost, not a benefit. Provider APIs change, and a framework that abstracts several of them carries the update burden for you, but only while it is maintained. The 1.4.0 note about Laravel 13 support means the package tracks Laravel majors, so a Laravel upgrade is also a LarAgent upgrade, and a LarAgent upgrade can change agent behaviour if a provider integration was rewritten. The licence is MIT, which permits commercial use and modification, but the repository does not state a support policy or a versioning guarantee in the material provided. There is no legal advice to give here beyond noting that MIT places no copyleft obligation on your application code; check the LICENSE file and your own organisation's policy for the rest.
Where it is the wrong tool, and what to use instead
LarAgent is the wrong tool when the agent runtime is not a Laravel request. If your agents need to run as long-lived processes with their own scheduling, or serve SDK clients in Python and TypeScript, the framework's value is tied to the Laravel container and you will spend your time fighting that boundary. It is also the wrong tool if you need a frozen API: the class-level configuration shown here is convenient precisely because it is concrete, and concrete surfaces change between minors.
The alternative worth naming is a provider-agnostic SDK such as the official OpenAI or Anthropic PHP clients, or a general agent runtime that is not tied to a web framework. The difference is not feature count, it is where the abstraction sits. A provider SDK gives you the raw request and response objects and leaves agent structure, history and tool dispatch to you; you write the loop, you choose the storage, and you own the upgrade when the provider changes its API. LarAgent inverts that: it owns the loop and the storage abstraction, and you accept its release cycle as the price of not writing them. For a Laravel team with a handful of agents, that trade usually favours LarAgent. For a platform team with ten agents across three languages, it usually does not.
Editorial conclusion
Adopt LarAgent if your agents live inside an existing Laravel application and you want them expressed as PHP classes with artisan scaffolding, tool attributes and Laravel's cache or queue layer underneath. Do not adopt it if you need a runtime that works outside PHP, if you require a frozen public API, or if you cannot accept that the README documents configuration but not failure behaviour. Before committing, verify three things yourself: the requirements section of the installation docs for the PHP and Laravel versions you run, the actual release cadence against the versions listed on Packagist, and whether the chat history driver you intend to use is the in-memory one or a cache-backed class, because that choice determines whether conversations survive a deploy.
Community notes