Overview - Official LarAgent Documentation

Every agent in LarAgent has a Context that manages multiple storage instances — chat history, usage tracking, identity storage, and any custom storages you register. You can configure which storage drivers these use at the agent level.

Configuration Hierarchy

Storage drivers are resolved in the following order (highest priority first):

Storage-specific method (e.g., historyStorageDrivers())
Storage-specific property (e.g., $history)
Agent default method (defaultStorageDrivers())
Agent default property ($storage)
Provider configuration (config/laragent.php)
Global configuration (config/laragent.php)

Default Storage Drivers

Set default drivers for all storages in an agent’s context using the $storage property or defaultStorageDrivers() method.

Using Property

use LarAgent\Agent;
use LarAgent\Context\Drivers\CacheStorage;
use LarAgent\Context\Drivers\FileStorage;

class SupportAgent extends Agent
{
    protected $instructions = 'You are a helpful support agent.';
    
    // Default drivers for all storages (chat history, usage, custom, etc.)
    protected $storage = [
        CacheStorage::class,  // Primary
        FileStorage::class,   // Fallback
    ];
}

Using Method Override

For dynamic configuration, override the defaultStorageDrivers() method:

use LarAgent\Agent;
use LarAgent\Context\Drivers\CacheStorage;
use LarAgent\Context\Drivers\EloquentStorage;

class SupportAgent extends Agent
{
    protected $instructions = 'You are a helpful support agent.';
    
    protected function defaultStorageDrivers(): array
    {
        // Use database in production, cache in development
        if (app()->environment('production')) {
            return [
                new EloquentStorage(),
            ];
        }
        
        return [
            new CacheStorage('redis'),
        ];
    }
}

Storage-Specific Drivers

Override the default for specific storage types when you need different persistence strategies.

Chat History Storage

Use $history property or historyStorageDrivers() method:

Property
Method Override

class SupportAgent extends Agent
{
    // Default for all storages
    protected $storage = [CacheStorage::class];
    
    // Override for chat history only
    protected $history = 'database';
}

class SupportAgent extends Agent
{
    protected $storage = [CacheStorage::class];
    
    // Override for chat history with custom model
    protected function historyStorageDrivers(): string|array
    {
        return [
            new EloquentStorage(\App\Models\ChatMessage::class),
        ];
    }
}

For chat history-specific configuration like truncation strategies, metadata storage, and force read/save flags, see the Chat History documentation.

Usage Storage

Use $usageStorage property or usageStorageDrivers() method:

Property
Method Override

class SupportAgent extends Agent
{
    protected $storage = [CacheStorage::class];

    protected $trackUsage = true;
    
    // Override for usage tracking only
    protected $usageStorage = [EloquentStorage::class];
}

class SupportAgent extends Agent
{
    protected $storage = [CacheStorage::class];

    protected $trackUsage = true;
    
    protected function usageStorageDrivers(): array
    {
        return [
            new EloquentStorage(\App\Models\UsageRecord::class),
        ];
    }
}

For detailed usage tracking configuration, cost calculation, and custom models, see the Usage Tracking documentation.

String Aliases

Both $usageStorage and $history properties accept string aliases for convenience:

class SupportAgent extends Agent
{
    // Using alias for usage
    protected $usageStorage = 'cache';
    
    // Using alias for history
    protected $history = 'database';
}

Alias	Driver Class
`'in_memory'`	`InMemoryStorage`
`'session'`	`SessionStorage`
`'cache'`	`CacheStorage`
`'file'` or `'json'`	`FileStorage`
`'database'`	`EloquentStorage`
`'database-simple'`	`SimpleEloquentStorage`

For detailed information about each driver’s constructor arguments, custom model examples, and the fallback pattern, see the Storage Drivers reference.

Configuration Examples

Simple: Single Driver for Everything

use LarAgent\Context\Drivers\CacheStorage;
use LarAgent\Context\Drivers\EloquentStorage;

class SupportAgent extends Agent
{
    protected $instructions = 'You are a helpful support agent.';
    
    // All storages use cache and database drivers
    protected $storage = [
        CacheStorage::class,
        EloquentStorage::class,
    ];
}

Mixed: Different Drivers per Storage Type

use LarAgent\Context\Drivers\CacheStorage;
use LarAgent\Context\Drivers\EloquentStorage;

class SupportAgent extends Agent
{
    protected $instructions = 'You are a helpful support agent.';
    
    // Default: cache for most storages
    protected $storage = [CacheStorage::class];
    
    // Chat history: database for queryability
    protected $history = 'database';
    
    // Usage tracking: database for analytics
    protected $usageStorage = 'database-simple';
}

High Availability: Fallback Chain

use LarAgent\Context\Drivers\CacheStorage;
use LarAgent\Context\Drivers\FileStorage;
use LarAgent\Context\Drivers\EloquentStorage;

class SupportAgent extends Agent
{
    protected $instructions = 'You are a helpful support agent.';
    
    // Cache with file fallback for general storages
    protected $storage = [
        CacheStorage::class,
        FileStorage::class,
    ];
    
    // Database for chat history (no fallback needed)
    protected $history = [
        EloquentStorage::class
    ];
}

Dynamic: Environment-Based Configuration

class SupportAgent extends Agent
{
    protected $instructions = 'You are a helpful support agent.';
    
    protected function defaultStorageDrivers(): array
    {
        return match (app()->environment()) {
            'testing' => [new InMemoryStorage()],
            'local' => [new CacheStorage()],
            default => [
                new CacheStorage('redis'),
                new FileStorage('s3', 'agent_backup'),
            ],
        };
    }
    
    protected function historyStorageDrivers(): string|array
    {
        // Always use database for chat history in non-test environments
        if (app()->environment('testing')) {
            return [new InMemoryStorage()];
        }
        
        return [new EloquentStorage()];
    }

    protected function usageStorageDrivers(): string|array
    {
        // Always use database for chat history in non-test environments
        if (app()->environment('testing')) {
            return [new InMemoryStorage()];
        }
        
        return [new EloquentStorage()];
    }
}

How It Works

When a storage is created (e.g., ChatHistoryStorage), it resolves drivers in this order:

historyStorageDrivers() → $history → defaultStorageDrivers() → $storage → config

This allows you to:

Set sensible defaults at the agent level ($storage / defaultStorageDrivers())
Override specific storages when needed ($history / historyStorageDrivers())
Fall back to global config if nothing is specified

Use $storage for simple cases and defaultStorageDrivers() when you need dynamic logic like environment checks or custom driver instances.

Custom Storages

Beyond chat history and usage tracking, you can create custom storages for any data your agent needs to persist — customer notes, session metadata, conversation tags, and more. Custom storages use:

DataModel — Typed, structured data classes for your storage items
Storage — Abstract base class that handles persistence, lazy loading, and dirty tracking
Storage Drivers — Pluggable backends (cache, file, database, etc.)

Custom Storage

Create custom storages with DataModels for type-safe persistence.

Custom Storage Driver

Build custom storage drivers for specialized backends.

Next Steps

Storage Drivers

Learn about all available storage drivers and their configuration options.

Chat History

Configure chat history storage and truncation strategies.

Usage Tracking

Track token usage and costs across agent interactions.

Context Overview

Understand the Context and Identity system for storage isolation.

​Configuration Hierarchy

​Default Storage Drivers

​Using Property

​Using Method Override

​Storage-Specific Drivers

​Chat History Storage

​Usage Storage

​String Aliases

​Configuration Examples

​Simple: Single Driver for Everything

​Mixed: Different Drivers per Storage Type

​High Availability: Fallback Chain

​Dynamic: Environment-Based Configuration

​How It Works

​Custom Storages

Custom Storage

Custom Storage Driver

​Next Steps

Storage Drivers

Chat History

Usage Tracking

Context Overview

Configuration Hierarchy

Default Storage Drivers

Using Property

Using Method Override

Storage-Specific Drivers

Chat History Storage

Usage Storage

String Aliases

Configuration Examples

Simple: Single Driver for Everything

Mixed: Different Drivers per Storage Type

High Availability: Fallback Chain

Dynamic: Environment-Based Configuration

How It Works

Custom Storages

Next Steps