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:
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:
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
- 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.)
Next Steps
