Download the PHP package maestroerror/laragent without Composer

LarAgent

The easiest way to create and maintain AI agents in your Laravel projects.

Jump to Table of Contents

Need to use LarAgent outside of Laravel? Check out this Docs.

Introduction

LarAgent brings the power of AI agents to your Laravel projects with an elegant syntax. Create, extend, and manage AI agents with ease while maintaining Laravel's fluent API design patterns.

What if you can create AI agents just like you create any other Eloquent model?

Why not?! 👇

And it looks familiar, isn't it?

And you can tweak the configs, like history

Or add temperature:

Even disable parallel tool calls:

Oh, and add a new tool as well:

And run it, per user:

Or use a custom name for the chat history:

Let's find out more with documentation below 👍

Features

• Eloquent-like syntax for creating and managing AI agents
• Laravel-style artisan commands
• Flexible agent configuration (model, temperature, context window, etc.)
• Structured output handling
• Image input support
• Easily extendable, including chat histories and LLM drivers
• Multiple built-in chat history storage options (in-memory, cache, json, etc.)
  • Per-user chat history management
  • Custom chat history naming support
• Custom tool creation with attribute-based configuration
  • Tools via classes
  • Tools via methods of AI agent class (Auto)
  • Tool facade for shortened tool creation
  • Parallel tool execution capability (can be disabled)
• Extensive Event system for agent interactions (Nearly everything is hookable)
• Multiple provider support (Can be set per model)
• Support for both Laravel and standalone usage

Planned

Here's what's coming next to make LarAgent even more powerful:

Developer Experience 🛠️

• Artisan Commands for Rapid Development
  • make:agent:tool - Generate tool classes with ready-to-use stubs
  • make:agent:chat-history - Scaffold custom chat history implementations
  • make:llm-driver - Create custom LLM driver integrations

Enhanced AI Capabilities 🧠

• Prism Package Integration - Additional LLM providers support
• Streaming Support - Out-of-the-box support for streaming responses
• RAG & Knowledge Base
  • Built-in vector storage providers
  • Seamless document embeddings integration
  • Smart context management
• Ready-to-use Tools - Built-in tools as traits
• Structured Output at runtime - Allow defining the response JSON Schema at runtime.

Security & Storage 🔒

• Enhanced Chat History Security - Optional encryption for sensitive conversations

Advanced Integrations 🔌

• Provider Fallback System - Automatic fallback to alternative providers
• Laravel Actions Integration - Use your existing Actions as agent tools
• Voice Chat Support - Out of the box support for voice interactions with your agents

Stay tuned! We're constantly working on making LarAgent the most versatile AI agent framework for Laravel.

Table of Contents

• Introduction
• Getting Started
  • Requirements
  • Installation
  • Configuration
• Core Concepts
  • Agents
  • Tools
  • Chat History
  • Structured Output
  • Usage without Laravel
• Events
  • Using Events
• Commands
  • Creating an Agent
  • Interactive Chat
• Advanced Usage
  • AI Agents as Tools
  • Creating Custom Providers
  • Creating Custom Chat Histories
• Contributing
• Testing
• Security
• Credits
• License
• Roadmap

Getting Started

Requirements

• Laravel 10.x or higher
• PHP 8.3 or higher

Installation

You can install the package via composer:

You can publish the config file with:

This is the contents of the published config file:

Configuration

You can configure the package by editing the config/laragent.php file. Here is an example of custom provider with all possible configurations you can apply:

Provider just gives you the defaults. Every config can be overridden per agent in agent class.

Core Concepts

Agents

@todo Table of contents for Agents section

Agents are the core of LarAgent. They represent a conversational AI model that can be used to interact with users, systems, or any other source of input.

Creating Agent

You can create a new agent by extending the LarAgent\Agent class. This is the foundation for building your custom AI agent with specific capabilities and behaviors.

For rapid development, you can use the artisan command to generate a new agent with a basic structure:

This will create a new agent class in the App\AiAgents directory with all the necessary boilerplate code.

Configuring agent

Agents can be configured through various properties and methods to customize their behavior. Here are the core configuration options:

The agent also provides two core methods that you can override:

Example:

Using agent

There are two ways to interact with your agent: direct response or chainable methods.

Direct Response

The simplest way is to use the for() method to specify a chat history name and get an immediate response:

Chainable Methods

For more control over the interaction, you can use the chainable syntax:

The for() and forUser() method allows you to maintain separate conversation histories for different contexts or users:

Here are some chainable methods to modify the agents behavior on the fly:

Agent accessors

You can access the agent's properties using these methods on an instance of the agent:

Tools

Tools are used to extend the functionality of agents. They can be used to perform tasks such as sending messages, running jobs, making API calls, or executing shell commands.

Here's a quick example of creating a tool using the #[Tool] attribute:

Tools in LarAgent can be configured using these properties:

There are three ways to create and register tools in your agent:

1. Using the registerTools Method This method allows you to programmatically create and register tools:

2. Using the #[Tool] Attribute The #[Tool] attribute provides a simple way to create tools from class methods:

Agent will automatically register tool with given description as Tool attribute's first argument and other method info, such as method name, required and optional parameters.

Tool attribute also accepts a second argument, which is an array mapping parameter names to their descriptions for more precise control. Also, it can be used with Static methods and parameters with Enum as type, where you can specify the values for the Agent to choose from.

Enum

Agent class

So the tool registered for your LLM will define $unit as enum of "celsius" and "fahrenheit" and required parameter, but $location will be optional, of course with coresponding descriptions from Tool attribute's second argument.

Recommended to use #[Tool] attribute with static methods if there is no need for agent instance ($this)

3. Using Tool Classes You can create separate tool classes and add them to the $tools property:

It's recommended to use tool classes with any complex workflows as they provide more control over the tool's behavior, maintainability and reusability (can be used in different agents).

Tool creation command coming soon

Tool class example:

Chat History

Chat history is used to store the conversation history between the user and the agent. LarAgent provides several built-in chat history implementations and allows for custom implementations.

Built-in Chat Histories

In Laravel:

Outside Laravel:

Chat History Configuration

Chat histories can be configured using these properties.

Instructions are always injected at the beginning of the chat history, $reinjectInstructionsPer defined when to reinject the instructions. By default it is set to 0 (disabled).

After the context window is exceeded, the oldest messages are removed until the context window is satisfied or the limit is reached. You can implement custom logic for the context window management using events and chat history instance inside your agent.

Some LLM drivers such as OpenAI provide additional data with the response, such as token usage, completion time, etc. By default it is set to false (disabled).

Creating Custom Chat History

You can create your own chat history implementation by implementing the ChatHistoryInterface and extending the LarAgent\Core\Abstractions\ChatHistory abstract class.

There are two ways to register your chat history into an agent. If you use standard construction only with $name parameter, you can define it in by class in $history property or provider configuration:

Agent Class

Provider Configuration (config/laragent.php)

If you need any other configuration other than $name, you can override createChatHistory() method:

Using Chat History

Chat histories are automatically managed based on the chat session ID. You can use the for() or forUser() methods to specify different chat sessions:

You can access chat history instance with chatHistory() method from the agent instance:

Here are several methods you can use with Chat History:

The chat history is created with the following configuration:

Structured Output

Structured output allows you to define the exact format of the agent's response using JSON Schema. When structured output is enabled, the respond() method will return an array instead of a string, formatted according to your schema.

Defining Schema

You can define the response schema in your agent class using the $responseSchema property:

For defining more complex schemas you can add the structuredOutput method in you agent class:

The schema follows the JSON Schema specification and supports all its features including:

• Basic types (string, number, boolean, array, object)
• Required properties
• Nested objects and arrays
• Property descriptions
• Enums and patterns

Using Structured Output

When structured output is defined, the agent's response will be automatically formatted and returned as an array according to the schema:

The schema can be accessed or modified using the structuredOutput() method at runtime:

Usage in and outside of Laravel

Agent classes is powered by LarAgent's main class LarAgent\LarAgent, which often refered as "LarAgent engine".
Laragent engine is standalone part which holds all abstractions and doesn't depend on Laravel. It is used to create and manage agents, tools, chat histories, structured output and etc.

So you can use LarAgent's engine outside of Laravel as well. Usage is a bit different than inside Laravel, but the principles are the same.

Check out the Docs for more information.

Events

@todo list of event

Using Events

@todo Descriptions for driver and agent specific events

@todo usage examples

Commands

Creating an Agent

You can quickly create a new agent using the make:agent command:

This will create a new agent class in your app/AiAgents directory with the basic structure and methods needed to get started.

Interactive Chat

You can start an interactive chat session with any of your agents using the agent:chat command:

The chat session allows you to:

• Send messages to your agent
• Get responses in real-time
• Use any tools configured for the agent
• Type 'exit' to end the chat session

Advanced Usage

Ai agents as Tools

You can create tools which calls another agent and bind the result to the agent to create a chain or complex workflow.

// @todo add example

Creating Custom Providers

// @todo add example

Creating Custom chat histories

// @todo add example

Contributing

We welcome contributions to LarAgent! Whether it's improving documentation, fixing bugs, or adding new features, your help is appreciated. Here's how you can contribute:

Development Setup

1. Fork the repository

2. Clone your fork:

3. Install dependencies:

4. Create a new branch:

Guidelines

1. Code Style

   • Use type hints and return types where possible
   • Add PHPDoc blocks for classes and methods
   • Keep methods focused and concise

2. Testing

   • Add tests for new features

   • Ensure all tests pass before submitting:

   • Maintain or improve code coverage

3. Documentation

   • Update README.md for significant changes
   • Add PHPDoc blocks for new classes and methods
   • Include examples for new features
4. Commits
   • Use clear, descriptive commit messages
   • Reference issues and pull requests
   • Keep commits focused and atomic

Pull Request Process

1. Update your fork with the latest changes from main:

2. Push your changes:

3. Create a Pull Request with:
   • Clear title and description
   • List of changes and impact
   • Any breaking changes highlighted
   • Screenshots/examples if relevant

Getting Help

• Open an issue for bugs or feature requests
• Join discussions in existing issues (@todo add discord channel invite link)
• Reach out to maintainers for guidance

We aim to review all pull requests within a 2 weeks. Thank you for contributing to LarAgent!

Testing

Security

Please review our security policy on how to report security vulnerabilities.

Credits

• maestroerror
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Roadmap

Please see Planned for more information on the future development of LarAgent.