Laragent

https://github.com/maestroerror/laragent
Admin
LarAgent is a Laravel package that simplifies the creation and management of AI agents with an...
Tokens:235,977
Snippets:1,605
Trust Score:8.6
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Basic LarAgent setup and run example

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Complete example of setting up an agent with the OpenAI driver, in-memory chat history, and running a message with instructions. Uses `LarAgent::setup`, `withInstructions`, `withMessage`, and `run`.

```php
use LarAgent\LarAgent;
use LarAgent\Drivers\OpenAi\OpenAiDriver;
use LarAgent\History\InMemoryChatHistory;
use LarAgent\Core\DTO\DriverConfig;

$driver = new OpenAiDriver(new DriverConfig(
    model: 'gpt-4o-mini',
    apiKey: 'sk-...'
));
$history = new InMemoryChatHistory('session-key', []);

$agent = LarAgent::setup($driver, $history, [
    'temperature' => 0.5,
    'maxCompletionTokens' => 500,
]);

$response = $agent->withInstructions('You are a poet.')
    ->withMessage(\LarAgent\Message::user('Write a haiku'))
    ->run();

echo (string) $response;
```

--------------------------------

### Direct Driver Usage Example

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/drivers.md

Example of instantiating an OpenAiDriver, registering a tool, and sending a message to get a response.

```APIDOC
## Direct Driver Usage

### Description
Demonstrates how to create a driver instance, register a tool, and send a message using the Laragent SDK.

### Example Code
```php
use LarAgent\Drivers\OpenAi\OpenAiDriver;
use LarAgent\Core\DTO\DriverConfig;
use LarAgent\Message;

$driver = new OpenAiDriver(new DriverConfig(
    model: 'gpt-4o-mini',
    apiKey: env('OPENAI_API_KEY'),
    temperature: 0.7,
));

$driver->registerTool(Tool::create('get_weather', 'Get weather')
    ->addProperty('location', 'string', 'City')
    ->setRequired('location')
    ->setCallback(fn ($location) => "20°C"));

$response = $driver->sendMessage([
    Message::system('You are helpful.'),
    Message::user('Weather in Paris?'),
]);

echo $response->getContentAsString();
```

### Notes
- The `OpenAiDriver` constructor accepts a `DriverConfig` object.
- `registerTool` adds a tool definition with properties and a callback.
- `sendMessage` accepts an array of `Message` objects and returns a response object with `getContentAsString()`.
```

--------------------------------

### Example Controller Wiring

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/completions.md

Example of how to subclass SingleAgentController and wire it to routes.

```APIDOC
## Example Controller Wiring

### Description
Shows how to create a custom controller by extending SingleAgentController and defining agent class and models.

### Code Example
```php
use LarAgent\API\Completion\Controllers\SingleAgentController;

class MyCompletionsController extends SingleAgentController
{
    protected ?string $agentClass = \App\AiAgents\MyAgent::class;
    protected ?array $models = ['gpt-4o-mini', 'claude-3-7-sonnet-latest'];

    // app/routes/api.php:
    // Route::post('/v1/chat/completions', [MyCompletionsController::class, 'completion']);
    // Route::get('/v1/models', [MyCompletionsController::class, 'models']);
}
```
```

--------------------------------

### UsageStorage usage example

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/usage.md

Shows how to instantiate UsageStorage with a cache driver, add a Usage object, and aggregate the records to get total token counts.

```php
$storage = new UsageStorage($identity, [CacheStorage::class], 'gpt-4o-mini', 'openai');
$storage->addUsage(new Usage(100, 50, 150));
$stats = $storage->aggregate(); // ['total_tokens' => 150, ...]
```

--------------------------------

### Class-based tool example

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/tool.md

Complete example of a class-based tool that extends Tool and implements ToolInterface, demonstrating constructor setup and handle method override.

```APIDOC
## Class-based tool example

### Description
A complete example of a class-based tool that extends the Tool class and implements the ToolInterface. It demonstrates how to set up the tool's name, description, properties, and required parameters in the constructor, and how to override the handle method to provide the tool's logic.

### Example
```php
use LarAgent\Tool;
use LarAgent\Core\Contracts\Tool as ToolInterface;

class GetWeatherTool extends Tool implements ToolInterface
{
    public function __construct()
    {
        parent::__construct('get_weather', 'Get the current weather in a location');
        $this->addProperty('location', 'string', 'City and state')
             ->setRequired('location');
    }

    protected function handle(array|DataModelContract $input): mixed
    {
        return WeatherService::for($input['location']);
    }
}
```
```

--------------------------------

### getInstructions()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Get the agent instructions.

```APIDOC
## getInstructions()

### Description
Get the agent instructions.

### Method
GET (configuration)

### Returns
- `?string` - The instructions or null if not set.
```

--------------------------------

### Class-based tool example

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/tool.md

Example of a class-based tool that extends Tool and implements ToolInterface, defining a get_weather tool with a required location property.

```php
use LarAgent\Tool;
use LarAgent\Core\Contracts\Tool as ToolInterface;

class GetWeatherTool extends Tool implements ToolInterface
{
    public function __construct()
    {
        parent::__construct('get_weather', 'Get the current weather in a location');
        $this->addProperty('location', 'string', 'City and state')
             ->setRequired('location');
    }

    protected function handle(array|DataModelContract $input): mixed
    {
        return WeatherService::for($input['location']);
    }
}
```

--------------------------------

### Context Facade - Full Agent-Based Access

Source: https://github.com/maestroerror/laragent/blob/main/MIGRATION.md

Shows the Context::of() entry point for full agent-based context access, including getting keys, fluent filtering, iteration, clearing, and getting the first agent.

```php
use LarAgent\Facades\Context;
use LarAgent\Context\Storages\ChatHistoryStorage;
use App\AiAgents\MyAgent;

// ========================================
// Entry Point 1: Context::of(AgentClass::class)
// Full agent-based context access (creates temporary agent)
// ========================================

// Get all chat keys for an agent
$chatKeys = Context::of(MyAgent::class)->getChatKeys();
$storageKeys = Context::of(MyAgent::class)->getStorageKeys();

// Fluent filtering API
$count = Context::of(MyAgent::class)
    ->forUser('user-123')
    ->forStorage(ChatHistoryStorage::class)
    ->count();

// Iterate with full agent access
Context::of(MyAgent::class)
    ->forUser('user-123')
    ->each(function ($identity, $agent) {
        // $identity is SessionIdentityContract
        // $agent is fully initialized Agent instance
        $agent->chatHistory()->clear();
    });

// Clear/remove operations
Context::of(MyAgent::class)->clearAllChats();           // Clear all chat data
Context::of(MyAgent::class)->removeAllChats();          // Remove all chat entries
Context::of(MyAgent::class)->clearAllChatsByUser('user-123');
Context::of(MyAgent::class)->removeAllChatsByUser('user-123');

// Get first matching agent
$agent = Context::of(MyAgent::class)->forUser('user-123')->firstAgent();
```

--------------------------------

### Custom Provider Configuration Example

Source: https://github.com/maestroerror/laragent/blob/main/README.md

Example of a custom provider configuration with all possible settings, including model, API URL, driver, chat history, and parallel tool calls. This is a snippet from the config file, not a complete file.

```php
    // Example custom provider with all possible configurations
    'custom_provider' => [
        // Just name for reference, changes nothing
        'label' => 'mini',
        'model' => 'gpt-3.5-turbo',
        'api_key' => env('CUSTOM_API_KEY'),
        'api_url' => env('CUSTOM_API_URL'),
        // Default driver and chat history
        'driver' => \LarAgent\Drivers\OpenAi\OpenAiDriver::class,
        'chat_history' => \LarAgent\History\InMemoryChatHistory::class,
        'default_truncation_threshold' => 15000,
        'default_max_completion_tokens' => 100,
        'default_temperature' => 1,
        // Enable/disable parallel tool calls
        'parallel_tool_calls' => true,
        // Store metadata with messages
        'store_meta' => true,
        // Save chat keys to memory via chatHistory
        'save_chat_keys' => true,
    ],
```

--------------------------------

### setup(LlmDriverInterface $driver, ChatHistoryInterface $chatHistory, DriverConfig|array $configs = []): self

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Preferred constructor that creates an instance and calls initializeConfigs with the provided configuration.

```APIDOC
## setup(LlmDriverInterface $driver, ChatHistoryInterface $chatHistory, DriverConfig|array $configs = []): self

### Description
Preferred constructor: creates an instance and calls `initializeConfigs($configs)`.

### Method
Static method

### Signature
```php
public static function setup(LlmDriverInterface $driver, ChatHistoryInterface $chatHistory, DriverConfig|array $configs = []): self
```

### Parameters
- **$driver** (LlmDriverInterface) - Required - The LLM driver.
- **$chatHistory** (ChatHistoryInterface) - Required - The chat history store.
- **$configs** (DriverConfig|array) - Optional - Configuration for the driver, defaults to empty array.

### Returns
- **self** - A new LarAgent instance.

```

--------------------------------

### Install Laragent via Composer

Source: https://github.com/maestroerror/laragent/blob/main/README.md

Run this command to install the Laragent package via Composer.

```bash
composer require maestroerror/laragent
```

--------------------------------

### for usage example

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/agent.md

Creates an agent with a custom chat history name and sends a message.

```php
YourAgentName::for("custom_history_name")->respond($message);
```

--------------------------------

### Creating a tool with properties and callback

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/tool.md

Example of using Tool::create to define a tool named 'get_weather' with a location property and a callback that returns a temperature string.

```php
use LarAgent\Tool;

$tool = Tool::create('get_weather', 'Get the current weather')
    ->addProperty('location', 'string', 'The city and state, e.g. San Francisco, CA', )
    ->setRequired('location')
    ->setCallback(fn ($location) => "20°C in $location");
```

--------------------------------

### Event Listener Registration Example

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/events.md

Example of registering a listener for the AfterResponse event in a Laravel application's EventServiceProvider.

```APIDOC
## Event Listener Registration Example

### Description
This example shows how to register a listener for the `LarAgent\Events\AfterResponse` event in a Laravel application's `EventServiceProvider`.

### Code Example
```php
// app/Providers/EventServiceProvider.php
protected $listen = [
    \LarAgent\Events\AfterResponse::class => [
        MyResponseListener::class,
    ],
];
```
```

--------------------------------

### Example controller wiring for SingleAgentController

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/completions.md

Shows how to subclass SingleAgentController, set the agent class and allowed models, and wire routes for chat completions and models endpoints.

```php
use LarAgent\API\Completion\Controllers\SingleAgentController;

class MyCompletionsController extends SingleAgentController
{
    protected ?string $agentClass = \App\AiAgents\MyAgent::class;
    protected ?array $models = ['gpt-4o-mini', 'claude-3-7-sonnet-latest'];

    // app/routes/api.php:
    // Route::post('/v1/chat/completions', [MyCompletionsController::class, 'completion']);
    // Route::get('/v1/models', [MyCompletionsController::class, 'models']);
}
```

--------------------------------

### Set temperature to 0.5

Source: https://github.com/maestroerror/laragent/blob/main/README.md

Shows how to set the temperature property for the agent. The example uses a value of 0.5.

```php
// ...
protected $temperature = 0.5;
// ...
```

--------------------------------

### getAudio() / setAudio()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Get or set audio generation options.

```APIDOC
## getAudio() / setAudio()

### Description
Get or set audio generation options.

### Method
GET/SET (configuration)

### Parameters
- **audio** (?array) - Required for setter - Audio generation options.

### Returns
- `getAudio(): ?array` - The current audio options or null.
- `setAudio(?array $audio): self` - The agent instance for chaining.
```

--------------------------------

### Context Facade - Lightweight Named Access

Source: https://github.com/maestroerror/laragent/blob/main/MIGRATION.md

Shows the Context::named() entry point for lightweight access without agent initialization, including getting keys, custom driver configuration, and clearing chats.

```php
// ========================================
// Entry Point 2: Context::named('AgentName')
// Lightweight access (no agent initialization)
// ========================================

// Get keys without creating agent instances
$chatKeys = Context::named('MyAgent')->getChatKeys();
$storageKeys = Context::named('MyAgent')->getStorageKeys();

// Custom driver configuration
$count = Context::named('MyAgent')
    ->withDrivers([CacheStorage::class])
    ->forUser('user-123')
    ->count();

// Clear chats (lightweight - no agent needed)
Context::named('MyAgent')->clearAllChats();
Context::named('MyAgent')->removeAllChats();
```

--------------------------------

### GET /models

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/completions.md

Lists the configured models for the completion API.

```APIDOC
## GET /models

### Description
Lists the configured models for the completion API.

### Method
GET

### Endpoint
/models

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **object** (string) - Always "list".
- **data** (array) - Array of model objects, each with:
  - **id** (string) - Model identifier.
  - **object** (string) - Always "model".
  - **created** (int) - Creation timestamp.
  - **owned_by** (string) - Owner name from config.

#### Response Example
{
  "object": "list",
  "data": [
    {
      "id": "gpt-4",
      "object": "model",
      "created": 1753357877,
      "owned_by": "laragent"
    }
  ]
}
```

--------------------------------

### Custom StorageDriver implementation (PHP)

Source: https://github.com/maestroerror/laragent/blob/main/MIGRATION.md

Example of a custom storage driver implementing the StorageDriver contract. Includes methods for reading, writing, removing, and a static make method.

```php
use LarAgent\Context\Contracts\StorageDriver;
use LarAgent\Context\Contracts\SessionIdentity;

class MyStorageDriver implements StorageDriver
{
    public function readFromMemory(SessionIdentity $identity): ?array
    {
        // Your read logic
    }
    
    public function writeToMemory(SessionIdentity $identity, array $data): bool
    {
        // Your write logic
    }
    
    public function removeFromMemory(SessionIdentity $identity): bool
    {
        // Your remove logic
    }
    
    public static function make(?array $config = null): static
    {
        return new static();
    }
}
```

--------------------------------

### Call setupAttributeStorages() in Constructor

Source: https://github.com/maestroerror/laragent/blob/main/plans/attribute-based-storage-registration.md

Calls setupAttributeStorages() after context setup and before chatHistory in the Agent constructor.

```php
$this->setupContext($defaultStorageDrivers);

$this->setupAttributeStorages();  // NEW - after context, before chatHistory

if ($this->forceReadContext) {
    $this->readContext();
}
```

--------------------------------

### Add a tool with #[Tool] attribute

Source: https://github.com/maestroerror/laragent/blob/main/README.md

Shows how to add a tool method to the agent class using the #[Tool] attribute. The example defines a weather tool that returns a string.

```php
// ...
#[Tool('Get the current weather in a given location')]
public function exampleWeatherTool($location, $unit = 'celsius')
{
    return 'The weather in '.$location.' is '.'20'.' degrees '.$unit;
}
// ...
```

--------------------------------

### getUseDeveloperForInstructions() / useDeveloperRole()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Get or set whether to use the 'developer' role instead of 'system' for instructions.

```APIDOC
## getUseDeveloperForInstructions() / useDeveloperRole()

### Description
Get or set whether to use the 'developer' role instead of 'system' for instructions.

### Method
GET/SET (configuration)

### Parameters
- **useDeveloperRole** (bool) - Required for setter - Whether to use the developer role.

### Returns
- `getUseDeveloperForInstructions(): bool` - The current flag.
- `useDeveloperRole(bool $useDeveloperRole): self` - The agent instance for chaining.
```

--------------------------------

### Enable usage tracking and get total tokens

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/agent.md

Enables usage tracking on the agent, retrieves usage records filtered by date, and echoes the total token count. Requires the agent to have usage tracking enabled and storage configured.

```php
$agent->trackUsage();
$usage = $agent->getUsage(['date_from' => '2025-01-01']);
echo $usage->getTotalTokens();
```

--------------------------------

### forUser usage example

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/agent.md

Creates an agent for the authenticated user and sends a message. The user's getAuthIdentifier() is used as the user ID.

```php
YourAgentName::forUser(auth()->user())->respond($message);
```

--------------------------------

### Custom truncation strategy with SummarizationStrategy

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/truncation.md

Example of enabling truncation and setting a custom summarization strategy in an Agent subclass. Requires setting enableTruncation to true and truncationThreshold, and returning a SummarizationStrategy instance with keep_messages and summary_agent options.

```php
use LarAgent\Context\Truncation\SummarizationStrategy;

class MyAgent extends Agent
{
    protected $enableTruncation = true;
    protected $truncationThreshold = 32000;

    protected function truncationStrategy(): ?TruncationStrategy
    {
        return new SummarizationStrategy([
            'keep_messages' => 8,
            'summary_agent' => \App\AiAgents\MySummarizer::class,
        ]);
    }
}
```

--------------------------------

### Replace chat key management with Context facade and Agent methods

Source: https://github.com/maestroerror/laragent/blob/main/MIGRATION.md

Provides multiple options for retrieving chat keys and managing chat histories in v1.0, replacing the removed saveKeyToMemory(), loadKeysFromMemory(), and removeChatFromMemory() methods. Includes examples for inside and outside Agent usage, clearing/removing chats, and filtering identities.

```php
// ❌ BEFORE (v0.8)
$chatHistory->saveKeyToMemory();
$keys = $chatHistory->loadKeysFromMemory();
$chatHistory->removeChatFromMemory($key);

// ✅ AFTER (v1.0)
// Use the new Context facade or Agent methods:
use LarAgent\Facades\Context;
use App\AiAgents\MyAgent;

// Option 1: Inside Agent - get chat keys via Agent methods
$agent = MyAgent::for('user-123');
$chatKeys = $agent->getChatKeys();           // Get all chat history keys for this agent
$allStorageKeys = $agent->getStorageKeys();  // Get all storage keys (including usage, state, etc.)
$chatIdentities = $agent->getChatIdentities(); // Get chat identities as SessionIdentityArray

// Option 2: Inside Agent - get current session key
$sessionKey = $this->context()->getIdentity()->getKey(); // Full storage key
$chatName = $this->context()->getIdentity()->getChatName(); // Chat name portion

// Option 3: Outside Agent - use Context facade with agent class
$chatKeys = Context::of(MyAgent::class)->getChatKeys();
$storageKeys = Context::of(MyAgent::class)->getStorageKeys();

// Option 4: Outside Agent - use Context facade with agent name (lightweight)
$chatKeys = Context::named('MyAgent')->getChatKeys();
$storageKeys = Context::named('MyAgent')->getStorageKeys();

// Clear/remove chat histories
Context::of(MyAgent::class)->clearAllChats();                    // Clear all chats (keeps keys tracked)
Context::of(MyAgent::class)->removeAllChats();                   // Remove all chats (deletes entirely)
Context::of(MyAgent::class)->forUser('user-123')->clear();       // Clear chats for specific user
Context::of(MyAgent::class)->forChat('support')->remove();       // Remove specific chat

// Filter and iterate over identities
Context::of(MyAgent::class)
    ->forStorage(ChatHistoryStorage::class)
    ->forUser('user-123')
    ->each(fn($identity, $agent) => $agent->chatHistory()->clear());

// Get identities with filters
$identities = Context::of(MyAgent::class)->getIdentities();        // All tracked identities
$userChats = Context::of(MyAgent::class)->forUser('user-123')->getChatIdentities();
```

--------------------------------

### instructions()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/agent.md

Returns the system/developer instructions for the agent. Override this method to customize the agent's behavior.

```APIDOC
## instructions()

### Description
Returns the system/developer instructions for the agent. Override this method to customize the agent's behavior.

### Method
`public function instructions()`

### Parameters
None

### Returns
- **string** - The system/developer instructions.

### Example
```php
public function instructions()
{
    return "You are a helpful support assistant.";
}
```
```

--------------------------------

### Basic Storage Attribute Usage

Source: https://github.com/maestroerror/laragent/blob/main/plans/attribute-based-storage-registration.md

Declares storage properties with the #[Storage] attribute. The first example uses default tools, the second specifies tools. Access via magic methods like $this->preferences()->add($item).

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

--------------------------------

### GroqDriver::__construct

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/drivers.md

Initializes the Groq driver. Throws an exception if the API key is missing.

```APIDOC
## `GroqDriver::__construct`

### Description
Initializes the Groq driver with the provided settings. Requires an API key.

### Method
Constructor

### Parameters
- (not specified in source)

### Exceptions
- `\Exception('API key is required to use the Groq driver.')` - Thrown when no API key is provided.

### Example
```php
$driver = new GroqDriver(['api_key' => 'your-key']);
```
```

--------------------------------

### List models response (200)

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/endpoints.md

Example JSON response for the GET /v1/models endpoint. The owned_by field is set from the config value laragent.app_name.

```json
{
  "object": "list",
  "data": [
    { "id": "gpt-4o-mini", "object": "model", "created": 1753357877, "owned_by": "<config laragent.app_name>" }
  ]
}
```

--------------------------------

### Polymorphic DataModelArray subclass example

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/data-model.md

Example subclass defining allowedModels() and discriminator() for polymorphic resolution.

```php
class MessageArray extends DataModelArray
{
    public static function allowedModels(): array
    {
        return [
            'user' => UserMessage::class,
            'assistant' => [ToolCallMessage::class, AssistantMessage::class],
        ];
    }

    public function discriminator(): string
    {
        return 'role';
    }
}
```

--------------------------------

### getTools()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Get the registered tools.

```APIDOC
## getTools()

### Description
Get the registered tools.

### Method
GET (configuration)

### Returns
- `array` - The registered tools.
```

--------------------------------

### Create a Tool with DataModel properties and callback

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/tool.md

Creates a Tool instance named 'create_task' with a description, adds properties from a DataModel class, and sets a callback that saves the task. The callback receives a TaskDataModel instance.

```php
use LarAgent\Tool;

$tool = Tool::create('create_task', 'Create a new task')
    ->addDataModelAsProperties(TaskDataModel::class)
    ->setCallback(fn (TaskDataModel $task) => $task->save());
```

--------------------------------

### prepareExecution(): bool (protected)

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Protected helper that injects instructions when history is empty or on reinjection cadence, registers tools on the driver, sets the response schema, and fires the beforeSend hook.

```APIDOC
## prepareExecution(): bool (protected)

### Description
Injects instructions when history is empty (or on reinjection cadence), registers tools on the driver, sets the response schema, fires `beforeSend`. Returns `false` to abort.

### Method
prepareExecution

### Signature
```php
protected function prepareExecution(): bool
```

### Return Value
- `bool` - Returns `false` to abort execution.
```

--------------------------------

### getStreamCallback()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Get the chunk callback.

```APIDOC
## getStreamCallback()

### Description
Get the chunk callback.

### Method
GET (configuration)

### Returns
- `?callable` - The chunk callback or null.
```

--------------------------------

### make

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/context.md

Instantiates and registers a storage class with optional driver configuration.

```APIDOC
## make

### Description
Instantiates and registers a storage class with optional driver configuration.

### Method
`public function make(string $storageClass, array $driversConfig = []): StorageContract`

### Parameters
- `$storageClass` (string) - Required - The storage class name to instantiate.
- `$driversConfig` (array) - Optional - Driver configuration. Default: `[]`.

### Returns
- `StorageContract` - The created storage instance.
```

--------------------------------

### getCurrentMessage() / withMessage()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Get or set the message to send.

```APIDOC
## getCurrentMessage() / withMessage()

### Description
Get or set the message to send.

### Method
GET/SET (configuration)

### Parameters
- **message** (MessageInterface) - Required for setter - The message to send.

### Returns
- `getCurrentMessage(): ?MessageInterface` - The current message or null.
- `withMessage(MessageInterface $message): self` - The agent instance for chaining.
```

--------------------------------

### getPresencePenalty() / setPresencePenalty()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Get or set the presence penalty.

```APIDOC
## getPresencePenalty() / setPresencePenalty()

### Description
Get or set the presence penalty.

### Method
GET/SET (configuration)

### Parameters
- **presencePenalty** (?float) - Required for setter - The presence penalty value.

### Returns
- `getPresencePenalty(): ?float` - The current value or null if unset.
- `setPresencePenalty(?float $presencePenalty): self` - The agent instance for chaining.
```

--------------------------------

### ClaudeDriver::__construct

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/drivers.md

Initializes the Claude driver with configuration settings. Throws an exception if the API key is missing.

```APIDOC
## `ClaudeDriver::__construct`

### Description
Initializes the Claude driver with the provided settings. Requires an API key.

### Method
Constructor

### Signature
`public function __construct(DriverConfig|array $settings = [])`

### Parameters
- **$settings** (DriverConfig|array) - Optional - Configuration settings for the driver.

### Exceptions
- `\Exception('API key is required to use the Claude driver.')` - Thrown when no API key is provided.

### Example
```php
$driver = new ClaudeDriver(['api_key' => 'your-key']);
```
```

--------------------------------

### getFrequencyPenalty() / setFrequencyPenalty()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Get or set the frequency penalty.

```APIDOC
## getFrequencyPenalty() / setFrequencyPenalty()

### Description
Get or set the frequency penalty.

### Method
GET/SET (configuration)

### Parameters
- **frequencyPenalty** (?float) - Required for setter - The frequency penalty value.

### Returns
- `getFrequencyPenalty(): ?float` - The current value or null if unset.
- `setFrequencyPenalty(?float $frequencyPenalty): self` - The agent instance for chaining.
```

--------------------------------

### getTemperature() / setTemperature()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Get or set the sampling temperature.

```APIDOC
## getTemperature() / setTemperature()

### Description
Get or set the sampling temperature.

### Method
GET/SET (configuration)

### Parameters
- **temperature** (float) - Required for setter - The sampling temperature.

### Returns
- `getTemperature(): ?float` - The current value or null if unset.
- `setTemperature(float $temperature): self` - The agent instance for chaining.
```

--------------------------------

### setTruncationStrategy / getTruncationStrategy

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/context.md

Sets or gets the truncation strategy.

```APIDOC
## setTruncationStrategy / getTruncationStrategy

### Description
Sets or gets the truncation strategy.

### Methods
- `setTruncationStrategy` - Sets the truncation strategy.
- `getTruncationStrategy` - Gets the truncation strategy.
```

--------------------------------

### Context Facade Usage

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/facades-provider.md

Shows the three documented entry points for the Context facade: of(), agent(), and named().

```APIDOC
## LarAgent\Facades\Context

### Description
Resolves `LarAgent\Context\ContextManager` from the container. Provides three documented entry points via `@method` annotations.

### Methods

#### `Context::of(string $agentClass)`
- **Target:** `ContextManager`
- **Description:** Full agent-based context access (creates a temp agent).

#### `Context::agent(string $agentClass)`
- **Target:** `ContextManager`
- **Description:** Alias of `of()`.

#### `Context::named(string $agentName)`
- **Target:** `NamedContextManager`
- **Description:** Lightweight context access by agent name.

### Usage Example
```php
use LarAgent\Facades\Context;

Context::of(MyAgent::class)->forUser($userId)->clear();
Context::named('MyAgent')->withDrivers([CacheStorage::class])->clearAllChats();
```

```

--------------------------------

### getResponseSchema() / structured()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Get or set the structured output schema.

```APIDOC
## getResponseSchema() / structured()

### Description
Get or set the structured output schema.

### Method
GET/SET (configuration)

### Parameters
- **responseSchema** (array) - Required for setter - The structured output schema.

### Returns
- `getResponseSchema(): ?array` - The current schema or null.
- `structured(array $responseSchema): self` - The agent instance for chaining.
```

--------------------------------

### Create an agent tool with make:agent:tool

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/commands.md

Validates the name against /^[A-Z][a-zA-Z0-9]*$/ (PascalCase); returns Command::FAILURE otherwise. Creates app/AgentTools/{Name}.php from stubs/agent-tool.stub (tool name converted to snake_case). Returns Command::FAILURE if the file exists.

```bash
php artisan make:agent:tool GetWeatherTool
```

--------------------------------

### getTopP() / setTopP()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Get or set the nucleus sampling parameter.

```APIDOC
## getTopP() / setTopP()

### Description
Get or set the nucleus sampling parameter.

### Method
GET/SET (configuration)

### Parameters
- **topP** (?float) - Required for setter - The nucleus sampling value.

### Returns
- `getTopP(): ?float` - The current value or null if unset.
- `setTopP(?float $topP): self` - The agent instance for chaining.
```

--------------------------------

### Create a truncation strategy with make:truncation-strategy

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/commands.md

Appends 'Strategy' to the name if missing. Creates app/TruncationStrategies/{Name}.php from stubs/truncation-strategy.stub. Returns 1 if it already exists.

```bash
php artisan make:truncation-strategy MyCustomStrategy
```

--------------------------------

### getN() / setN()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Get or set the number of choices to generate.

```APIDOC
## getN() / setN()

### Description
Get or set the number of choices to generate.

### Method
GET/SET (configuration)

### Parameters
- **n** (?int) - Required for setter - The number of choices.

### Returns
- `getN(): ?int` - The current value or null if unset.
- `setN(?int $n): self` - The agent instance for chaining.
```

--------------------------------

### setTruncationThreshold / getTruncationThreshold

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/context.md

Sets or gets the token threshold for truncation.

```APIDOC
## setTruncationThreshold / getTruncationThreshold

### Description
Sets or gets the token threshold for truncation.

### Methods
- `setTruncationThreshold` - Sets the token threshold.
- `getTruncationThreshold` - Returns `?int` - The token threshold.
```

--------------------------------

### create(string $name, string $description): Tool

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/tool.md

Fluent factory method to create a new Tool instance. Note that PhantomTool::create() is overridden to return a PhantomTool instance.

```APIDOC
## create(string $name, string $description): Tool

### Description
Fluent factory method to create a new Tool instance. Note that PhantomTool::create() is overridden to return a PhantomTool instance.

### Method
create

### Signature
```php
public static function create(string $name, string $description): Tool
```

### Parameters
- **$name** (string) - Required - Tool name.
- **$description** (string) - Required - Tool description.

### Returns
- **Tool** - A new Tool instance.

### Example
```php
use LarAgent\Tool;

$tool = Tool::create('get_weather', 'Get the current weather')
    ->addProperty('location', 'string', 'The city and state, e.g. San Francisco, CA', )
    ->setRequired('location')
    ->setCallback(fn ($location) => "20°C in $location");
```
```

--------------------------------

### Create DynamicStorage Class

Source: https://github.com/maestroerror/laragent/blob/main/plans/attribute-based-storage-registration.md

Implements a dynamic storage class that uses an instance prefix for registration. It sets up the identity with the prefix and initializes the storage manager with drivers.

```php
<?php

namespace LarAgent\Context\Storages;

use LarAgent\Context\Abstract\Storage;
use LarAgent\Context\Contracts\SessionIdentity as SessionIdentityContract;
use LarAgent\Context\StorageManager;

class DynamicStorage extends Storage
{
    protected string $instancePrefix;
    protected string $dataModelArrayClass;
    
    public function __construct(
        SessionIdentityContract $identity,
        array|string|null $driversConfig,
        string $prefix,
        string $dataModelArrayClass
    ) {
        $this->instancePrefix = $prefix;
        $this->dataModelArrayClass = $dataModelArrayClass;
        
        // Set identity with instance prefix
        $this->identity = $identity->withScope($prefix);
        
        // Setup driver
        if ($driversConfig === null) {
            $driversConfig = $this->defaultDrivers;
        } elseif (!is_array($driversConfig)) {
            $driversConfig = [$driversConfig];
        }
        
        $this->storageManager = new StorageManager($driversConfig);
        $this->resetItems();
    }
    
    protected function getDataModelClass(): string
    {
        return $this->dataModelArrayClass;
    }
    
    public static function getStoragePrefix(): string
    {
        return 'dynamic';
    }
    
    public function getRegistrationKey(): string
    {
        return $this->instancePrefix;
    }
}
```

--------------------------------

### GET /v1/models (MultiAgent)

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/endpoints.md

Lists the available models for the multi-agent controller.

```APIDOC
## GET /v1/models

### Description
Lists the available models for the multi-agent controller.

### Method
GET

### Endpoint
/v1/models

### Response
#### Success Response (200)
Same list shape as single-agent controller.
```

--------------------------------

### GET /v1/models

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/endpoints.md

Lists the available models for the single agent controller.

```APIDOC
## GET /v1/models

### Description
Lists the available models for the single agent controller.

### Method
GET

### Endpoint
/v1/models

### Response
#### Success Response (200)
- **object** (string) - "list"
- **data** (array) - List of model objects, each with `id`, `object`, `created`, `owned_by`

#### Response Example
{
  "object": "list",
  "data": [
    { "id": "gpt-4o-mini", "object": "model", "created": 1753357877, "owned_by": "<config laragent.app_name>" }
  ]
}
```

--------------------------------

### Override instructions() and registerTools()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/agent.md

Shows how to override the instructions() and registerTools() hooks. The instructions() method returns a system prompt string, and registerTools() returns an array of Tool instances with a callback.

```php
public function instructions()
{
    return "You are a helpful support assistant.";
}

public function registerTools()
{
    return [
        Tool::create("user_location", "Returns the user's current location")
            ->setCallback(fn () => $user->location()->city),
    ];
}
```

--------------------------------

### Constructor

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/tool.md

Creates a new Tool instance with optional name and description. If a child class defines a dataModelClass, properties are automatically populated from the DataModel schema.

```APIDOC
## Constructor

### Description
Creates a new Tool instance with optional name and description. If a child class defines a dataModelClass, properties are automatically populated from the DataModel schema.

### Method
__construct

### Signature
```php
public function __construct(?string $name = null, ?string $description = null)
```

### Parameters
- **$name** (?string) - Optional - Tool name. Defaults to class default `$name`.
- **$description** (?string) - Optional - Tool description. Defaults to class default `$description`.

### Notes
If a child class defines `protected ?string $dataModelClass`, the constructor automatically populates all properties from that DataModel's schema via `initializeDataModelProperties()`.
```

--------------------------------

### getParallelToolCalls() / setParallelToolCalls()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Get or set the parallel tool calls flag.

```APIDOC
## getParallelToolCalls() / setParallelToolCalls()

### Description
Get or set the parallel tool calls flag.

### Method
GET/SET (configuration)

### Parameters
- **parallelToolCalls** (?bool) - Required for setter - Whether parallel tool calls are enabled.

### Returns
- `getParallelToolCalls(): ?bool` - The current value or null.
- `setParallelToolCalls(?bool $parallelToolCalls): self` - The agent instance for chaining.
```

--------------------------------

### Create Storage Tools (createStorageAllTool and createStorageClearTool)

Source: https://github.com/maestroerror/laragent/blob/main/plans/attribute-based-storage-registration.md

These methods create tools for listing and clearing attribute storage. They use the agent's getAttributeStorage method and return success/error responses.

```php
protected function createStorageAllTool(
        string $storageName,
        string $toolPrefix,
        ?string $description
    ): \LarAgent\Tool {
        $agent = $this;
        
        return \LarAgent\Tool::create("list_{$toolPrefix}", $description ?? "List all items in {$storageName}")
            ->setCallback(function () use ($agent, $storageName) {
                $storage = $agent->getAttributeStorage($storageName);
                
                return [
                    'success' => true,
                    'count' => $storage->count(),
                    'items' => $storage->get()->toArray()
                ];
            });
    }
```

```php
protected function createStorageClearTool(
        string $storageName,
        string $toolPrefix,
        ?string $description
    ): \LarAgent\Tool {
        $agent = $this;
        
        return \LarAgent\Tool::create("clear_{$toolPrefix}", $description ?? "Clear all items from {$storageName}")
            ->setCallback(function () use ($agent, $storageName) {
                $storage = $agent->getAttributeStorage($storageName);
                $storage->clear();
                $storage->save();
                
                return ['success' => true, 'message' => "Cleared all items from {$storageName}"];
            });
    }
```

--------------------------------

### getMaxCompletionTokens() / setMaxCompletionTokens()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Get or set the maximum number of completion tokens.

```APIDOC
## getMaxCompletionTokens() / setMaxCompletionTokens()

### Description
Get or set the maximum number of completion tokens.

### Method
GET/SET (configuration)

### Parameters
- **maxTokens** (int) - Required for setter - The maximum completion tokens.

### Returns
- `getMaxCompletionTokens(): ?int` - The current value or null if unset.
- `setMaxCompletionTokens(int $maxTokens): self` - The agent instance for chaining.
```

--------------------------------

### Configure storage drivers

Source: https://github.com/maestroerror/laragent/blob/main/MIGRATION.md

Shows how to set the default storage drivers in your Agent class. The built-in history drivers can still be used with the $history property.

```php
// In your Agent class:
protected $storage = [
    \LarAgent\Context\Drivers\CacheStorage::class,
];

// Or use the built-in history drivers:
protected $history = 'cache';  // Still works
```

--------------------------------

### getModalities() / setModalities()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Get or set the output modalities (e.g. ['text', 'audio']).

```APIDOC
## getModalities() / setModalities()

### Description
Get or set the output modalities (e.g. ['text', 'audio']).

### Method
GET/SET (configuration)

### Parameters
- **modalities** (array) - Required for setter - The output modalities.

### Returns
- `getModalities(): ?array` - The current modalities or null.
- `setModalities(array $modalities): self` - The agent instance for chaining.
```

--------------------------------

### Replace context window methods with truncation configuration

Source: https://github.com/maestroerror/laragent/blob/main/MIGRATION.md

Shows how to replace the removed setContextWindow(), exceedsContextWindow(), and truncateOldMessages() methods with the new truncation configuration properties in the Agent class.

```php
// ❌ BEFORE (v0.8)
$chatHistory->setContextWindow(50000);
if ($chatHistory->exceedsContextWindow($tokens)) {
    $chatHistory->truncateOldMessages(5);
}

// ✅ AFTER (v1.0)
// Configure truncation in Agent class or config:
protected $enableTruncation = true;
protected $truncationThreshold = 50000;
// Truncation is handled automatically by the truncation strategy
```

--------------------------------

### NamedContextManager::isEmpty / last

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/context.md

Queries to check if empty and get the last item.

```APIDOC
## NamedContextManager::isEmpty / last

### Description
Queries to check if empty and get the last item.

### Method
instance

### Signatures
- `public function isEmpty()`
- `public function last()`

### Returns
- Various query return types.
```

--------------------------------

### Constructor

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/agent.md

Constructs an Agent instance with a chat/session key, optionally bound to a user ID and/or a group. Resolves provider configuration, builds the driver, and sets up context, storage, chat history, usage tracking, truncation, tool caching, and MCP client.

```APIDOC
## Constructor

### Description
Constructs an Agent instance with a chat/session key, optionally bound to a user ID and/or a group. Resolves provider configuration, builds the driver, and sets up context, storage, chat history, usage tracking, truncation, tool caching, and MCP client.

### Method
`__construct`

### Signature
```php
public function __construct($key, bool $usesUserId = false, ?string $group = null)
```

### Parameters
- **$key** (mixed) - Required - Chat/session key. When `$usesUserId` is `true`, this is the user ID.
- **$usesUserId** (bool) - Optional - Default: `false` - When `true`, the key is treated as a user identifier (`LarAgent\Context\Contracts\SessionIdentity::$userId`).
- **$group** (?string) - Optional - Default: `null` - Group identifier used in identity key generation and context filtering.

### Notes
Most consumers never call the constructor directly — use the static factories. The constructor calls `$this->callEvent('onInitialize')` after full setup.
```

--------------------------------

### getReinjectInstructionsPer() / setReinjectInstructionsPer()

Source: https://github.com/maestroerror/laragent/blob/main/_autodocs/api-reference/laragent.md

Get or set how often to reinject instructions. Defaults to 0 (never).

```APIDOC
## getReinjectInstructionsPer() / setReinjectInstructionsPer()

### Description
Get or set how often to reinject instructions. Defaults to 0 (never).

### Method
GET/SET (configuration)

### Parameters
- **n** (int) - Required for setter - Reinject instructions every N messages.

### Returns
- `getReinjectInstructionsPer(): int` - The current value.
- `setReinjectInstructionsPer(int $n): self` - The agent instance for chaining.
```

--------------------------------

### Replace Message::create with typed factory methods

Source: https://github.com/maestroerror/laragent/blob/main/MIGRATION.md

Shows the before and after for migrating from Message::create() to the new typed factory methods like Message::user(), Message::assistant(), and Message::system().

```php
// ❌ BEFORE (v0.8)
$message = Message::create('user', 'Hello');
$message = Message::create('assistant', 'Hi there');
$message = Message::create('system', 'You are helpful');

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