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.

If you prefer article to get started, check it out Laravel AI Agent Development Made Easy

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
  • agent:chat:clear AgentName - Clear all chat histories for a specific agent while preserving keys
  • agent:chat:remove AgentName - Completely remove all chat histories and keys for a specific agent
  • 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
• Native Laravel events support - Support for Laravel events
• Debug mode - Should log all processes happening under the hood

Enhanced AI Capabilities 🧠

• Prism Package Integration - Additional LLM providers support
• Gemini Integration - Additional LLM provider
• Anthropic Integration - Additional LLM provider
• Usage abstraction - Abstraction for tokens usage
• 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.
• Transfer tool - One of the methods of agents chaining

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 (Function Calling)
  • Chat History
  • Structured Output
  • LLM Drivers
  • Usage without Laravel
• 🔥 Events
  • Agent
  • Engine
  • Using Laravel events with hooks
• 💬 Commands
  • Creating an Agent
  • Interactive Chat
  • Clear Chat History
  • Remove Chat History
• 🔍 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:

These are 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 three 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:

Note: You can set parallelToolCalls to null in case you want to remove from request, since some models do not support parallel tool calls property.

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 using the LarAgent\Tool class:

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 easily 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 in your Agent class.

reinjectInstructionsPer

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).

contextWindowSize

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.

storeMeta

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).

saveChatKeys

By default it is true, since it is required for chat history bunch clearing command to work.

developerRoleForInstructions

By default it is disabled, but you can turn it on by setting it to true in your agent.

Creating Custom Chat History

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

Check example implementations in src/History

There are two ways to register your custom chat history into an agent. If you use standard constructor only with $name parameter, you can define it 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 your agent class:

Pay attention to "required", "additionalProperties", and "strict" properties - it is recommended by OpenAI to set them when defining the schema to get the exact structure you need

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:

LLM Drivers

LarAgent provides a LlmDriver interface that allows you to implement custom LLM drivers for different providers. We have several built-in drivers that implement the interface and provide a simple way to use the API.

Using drivers

You can use the drivers by setting them in the configuration file:

Or by setting them per Agent in your agent class using $driver property:

Available drivers

OpenAiDriver

Default driver, which allows you easy start just by adding OPENAI_API_KEY in your .env file

OpenAiCompatible

Driver that can be used with any OpenAI-compatible provider. For example configuration with ollama provider would look like:

Or any other LLM API which uses the same standards as OpenAI, such as OpenRouter:

And then, set the $provider property in your agent class:

Usage in and outside of Laravel

Agent classes is powered by LarAgent's main class LarAgent\LarAgent, which often referred 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

LarAgent provides a comprehensive event system that allows you to hook into various stages of the agent's lifecycle and conversation flow. The event system is divided into two main types of hooks:

1. Agent Hooks: These hooks are focused on the agent's lifecycle events such as initialization, conversation flow, and termination. They are perfect for setting up agent-specific configurations, handling conversation state, and managing cleanup operations.

2. Engine Hooks: These hooks dive deeper into the conversation processing pipeline, allowing you to intercept and modify the behavior at crucial points such as message handling, tool execution, and response processing. Each engine hook returns a boolean value to control the flow of execution.

Nearly every aspect of LarAgent is hookable, giving you fine-grained control over the agent's behavior. You can intercept and modify:

• Agent lifecycle events
• Message processing
• Tool execution
• Chat history management
• Response handling
• Structured output processing

Table of Contents

• Agent
  • onInitialize - Agent initialization
  • onConversationStart - New conversation step started
  • onConversationEnd - Conversation step completed
  • onToolChange - Tool added or removed
  • onClear - Chat history cleared
  • onTerminate - Agent termination
• Engine
  • beforeReinjectingInstructions - Before system instructions reinjection
  • beforeSend & afterSend - Message handling
  • beforeSaveHistory - Chat history persistence
  • beforeResponse / afterResponse - LLM interaction
  • beforeToolExecution / afterToolExecution - Tool execution
  • beforeStructuredOutput - Structured output processing
• Using Laravel events with hooks

Agent

The Agent class provides several hooks that allow you to tap into various points of the agent's lifecycle. Each hook can be overridden in your agent implementation.

You can find an example implementation for each hook below.

onInitialize

The onInitialize hook is called when the agent is fully initialized. This is the perfect place to set up any initial state or configurations your agent needs. For example, use logic to set temperature dynamically based on the user type:

onConversationStart

This hook is triggered at the beginning of each respond method call, signaling the start of a new step in conversation. Use this to prepare conversation-specific resources or logging.

onConversationEnd

Called at the end of each respond method, this hook allows you to perform cleanup, logging or any other logic your application might need after a conversation ends.

onToolChange

This hook is triggered whenever a tool is added to or removed from the agent. It receives the tool instance and a boolean indicating whether the tool was added (true) or removed (false).

onClear

Triggered before the agent's chat history is cleared. Use this hook to perform any necessary logic before the chat history is cleared.

onTerminate

This hook is called when the agent is being terminated. It's the ideal place to perform final cleanup, save state, or close connections.

Engine

The Engine provides several hooks that allow fine-grained control over the conversation flow, message handling, and tool execution. Each hook returns a boolean value where true allows the operation to proceed and false prevents it.

In most cases, it's wise to throw and handle exception instead of just returning false, since returning false silently stops execution

You can override any engine level hook in your agent class.

You can find an example implementations for each hook below.

beforeReinjectingInstructions

The beforeReinjectingInstructions hook is called before the engine reinjects system instructions into the chat history. Use this to modify or validate the chat history before instructions are reinjected or even change the instructions completely.

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

beforeSend & afterSend

These hooks are called before and after a message is added to the chat history. Use them to modify, validate, or log messages.

beforeSaveHistory

Triggered before the chat history is saved. Perfect for validation or modification of the history before persistence.

beforeResponse / afterResponse

These hooks are called before sending a message (message is already added to the chat history) to the LLM and after receiving its response. Use them for request/response manipulation or monitoring.

beforeToolExecution / afterToolExecution

These hooks are triggered before and after a tool is executed. Perfect for tool-specific validation, logging, or result modification.

beforeStructuredOutput

This hook is called before processing structured output. Use it to modify or validate the response structure.

Using Laravel events with hooks

LarAgent hooks can be integrated with Laravel's event system to provide more flexibility and better separation of concerns. This allows you to:

• Decouple event handling logic from your agent class
• Use event listeners and subscribers
• Leverage Laravel's event broadcasting capabilities
• Handle events asynchronously using queues

Consider checking Laravel Events documentation before proceeding.

Here's how you can integrate Laravel events with LarAgent hooks.

Basic Event Integration

First, define your event classes:

Then, implement the hook in your agent class:

In case you want to pass agent in event handler, please use toDTO method: $this->toDTO()

Using Event Listeners

Create dedicated listeners for your agent events:

Register the event-listener mapping in your EventServiceProvider:

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

Clear Chat History

You can clear all chat histories for a specific agent using the agent:chat:clear command:

This command clears all chat histories for the specified agent while preserving the chat history structure and keys.

Remove Chat History

You can completely remove all chat histories and keys for a specific agent using the agent:chat:remove command:

This command removes all chat histories and their associated keys for the specified agent, effectively resetting the chat history.

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

Chaining Agents

// @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

Thanks to these people and projects, LarAgent would not be possible without them:

• maestroerror
• All Contributors
• openai-php/client

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.