LarAgent Documentation

The Context facade provides two ways to manage storage and chat history outside of individual agent instances:

1. Context::of(AgentClass::class): Provides full agent-based access. This creates a temporary agent instance, allowing you to use full agent methods like chatHistory() and ask(). Use this when you need to interact with fully initialized agents.
2. Context::named('AgentName'): Provides lightweight access. This does not initialize agent instances, making it faster for operations like retrieving keys or clearing chats. Use this for administrative tasks or when you only need to manage storage metadata.

use LarAgent//Facades//Context;
use LarAgent//Context//://Storages//ChatHistoryStorage;
use App//AiAgents//MyAgent;

// Full agent-based access
$chatKeys = Context::of(MyAgent::class)->getChatKeys();
$count = Context::of(MyAgent::class)
    ->forUser('user-123')
    ->forStorage(ChatHistoryStorage::class)
    ->count();

Context::of(MyAgent::class)
    ->forUser('user-123')
    ->each(function ($identity, $agent) {
        $agent->chatHistory()->clear();
    });

// Lightweight access
$chatKeys = Context::named('MyAgent')->getChatKeys();
$count = Context::named('MyAgent')
    ->withDrivers([CacheStorage::class])
    ->forUser('user-123')
    ->count();

Context::named('MyAgent')->clearAllChats();

LarAgent v1.0 uses a unified Context System to manage storages like chat history, state, and identities.

Accessing Chat History

Instead of accessing $this->chatHistory directly, use the chatHistory() method or access it via the context object:

• $this->chatHistory()->addMessage($message);
• $this->context()->getStorage(ChatHistoryStorage::class)->addMessage($message);

New Context Properties

• $storage: Array of default storage drivers for context.
• $forceReadHistory / $forceSaveHistory: Control history persistence.
• $forceReadContext: Force read context on construction.
• $trackUsage: Enable token usage tracking.
• $usageStorage: Storage drivers for usage data.
• $enableTruncation: Enable automatic truncation.

// ✅ AFTER (v1.0) - Accessing chat history through context
$this->chatHistory()->addMessage($message);

// Or via the context object
$this->context()->getStorage(\LarAgent\Context\Storages\ChatHistoryStorage::class)->addMessage($message);

You can register storage for an Agent using the #[Storage] PHP 8 attribute. This allows you to define how specific properties should be persisted by mapping them to a storage class. Once registered, these properties are accessible via magic methods that return a Storage instance.

Basic Syntax:

• Apply #[Storage] to a protected property.
• The property value must be the class name of the storage implementation (e.g., PreferencesArray::class).
• Access the storage using $this->propertyName().

class MyAgent extends Agent
{
    #[Storage]
    protected $preferences = PreferencesArray::class;
    
    #[Storage(['add', 'read', 'all'])]
    protected $memories = MemoriesArray::class;
    
    public function example()
    {
        // Access via magic method - returns Storage instance
        $this->preferences()->add($item);
        $this->memories()->save();
    }
}

When upgrading to v1.0, perform the following breaking changes:

Message API

• Replace Message::create() with typed factory methods.
• Replace Message::fromArray() with specific message class fromArray() methods.

Tool Messages

• Update ToolResultMessage constructor calls to include the $toolName parameter.
• Update ToolCallMessage constructor calls to remove the $message parameter.

Agent Configuration

• Replace $contextWindowSize with $truncationThreshold.
• Remove $saveChatKeys (this is now handled automatically by the Context system).
• Remove $includeModelInChatSessionId and any related method calls.

Provider Configuration

• Rename default_context_window to default_truncation_threshold.
• Rename chat_history to history.

Custom Implementations

• Custom Drivers: Update constructors to call parent::__construct($settings).
• Custom Chat History: Refactor to use ChatHistoryStorage with a custom driver.

When upgrading from v0.8 to v1.0, several Agent properties and methods have been removed or renamed.

Renamed Methods

Use the new names for clarity. While old names are deprecated and still work, they should be replaced:

• getChatSessionId() $\rightarrow$ getSessionId() (Returns the full storage key, e.g., AgentName_chatHistory_user-123)
• getChatKey() $\rightarrow$ getSessionKey() (Returns the session key portion, e.g., user-123)

Removed Features

• Model in Session ID: The property $includeModelInChatSessionId and methods withModelInChatSessionId() / withoutModelInChatSessionId() are removed. To achieve model-specific sessions, manually include the model in your chat key: YourAgent::for($userId . '-' . $model).
• Chat Key Saving: $saveChatKeys is now automatic via the new Context system's IdentityStorage.

Context Window & Truncation

Replace $contextWindowSize with $truncationThreshold and ensure $enableTruncation is set to true.

// ✅ AFTER (v1.0) - new method names
$fullKey = $this->getSessionId();     // Full storage key: "AgentName_chatHistory_user-123"
$sessionKey = $this->getSessionKey(); // Session key portion: "user-123"
$userId = $this->getUserId();         // User ID if using forUser()
$agentName = $this->getAgentName();   // Agent class name

// ✅ Replace contextWindowSize with truncationThreshold
protected $truncationThreshold = 50000;
protected $enableTruncation = true;

The ChatHistory interface has been streamlined in v1.0. Manual context window management and memory-based key management have been removed in favor of an automated truncation system and a new Context facade.

1. Message Retrieval

getMessages() now returns a MessageArray instead of a plain array. MessageArray implements Countable and IteratorAggregate, so existing foreach loops will still work, but you can now use helper methods like ->all(), ->first(), and ->last().

2. Context Truncation

Instead of manually calling setContextWindow() or truncateOldMessages(), configure truncation directly on the Agent class:

• $enableTruncation = true
• $truncationThreshold = 50000

3. Chat Key and Identity Management

Manual memory management methods (like saveKeyToMemory()) are removed. Use the LarAgent\Facades\Context facade or Agent methods to manage chat identities and storage.

Using the Context Facade:

• Context::of(MyAgent::class)->getChatKeys(): Get all chat history keys for a specific agent class.
• Context::named('MyAgent')->getChatKeys(): Lightweight access by agent name.
• Context::of(MyAgent::class)->forUser('user-123')->clear(): Clear chats for a specific user.
• Context::of(MyAgent::class)->removeAllChats(): Deletes all chats entirely.

// ✅ AFTER (v1.0) - Handling MessageArray
$messages = $chatHistory->getMessages(); // returns MessageArray
foreach ($messages as $msg) { ... } 
$first = $messages->first();

// ✅ AFTER (v1.0) - Context Management via Facade
use LarAgent\Facades\Context;

Context::of(MyAgent::class)->forUser('user-123')->clear(); // Clear specific user chats
Context::of(MyAgent::class)->removeAllChats();           // Delete everything

In v1.0, the Message class has become a pure factory class. The generic create(), fromArray(), and fromJSON() methods have been removed in favor of specific, typed factory methods. This change improves type safety and clarity.

Replacement Mapping

Available Factory Methods

• Message::user($content, $metadata)
• Message::assistant($content, $metadata)
• Message::system($content, $metadata)
• Message::developer($content, $metadata)
• Message::toolCall($toolCalls, $metadata)
• Message::toolResult($content, $toolCallId, $toolName, $metadata)

// ✅ AFTER (v1.0)
$message = Message::user('Hello');
$message = Message::assistant('Hi there');
$message = Message::system('You are helpful');

// For collections:
$messages = MessageArray::fromArray($arrayOfMessages);