1. Go to this page and download the library: Download maestroerror/laragent library. Choose the download type require.
2. Extract the ZIP file and open the index.php.
3. Add this code to the index.php.
<?php
require_once('vendor/autoload.php');
/* Start to develop here. Best regards https://php-download.com/ */
maestroerror / laragent example snippets
namespace App\AiAgents;
use LarAgent\Agent;
class YourAgentName extends Agent
{
protected $model = 'gpt-4';
protected $history = 'in_memory';
protected $provider = 'default';
protected $tools = [];
public function instructions()
{
return "Define your agent's instructions here.";
}
public function prompt($message)
{
return $message;
}
}
// ...
#[Tool('Get the current weather in a given location')]
public function exampleWeatherTool($location, $unit = 'celsius')
{
return 'The weather in '.$location.' is '.'20'.' degrees '.$unit;
}
// ...
Use App\AiAgents\YourAgentName;
// ...
YourAgentName::forUser(auth()->user())->respond($message);
Use App\AiAgents\YourAgentName;
// ...
YourAgentName::for("custom_history_name")->respond($message);
// Example custom provider with all possible configurations
'custom_provider' => [
// Just name for reference, changes nothing
'name' => '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_context_window' => 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,
],
namespace App\AiAgents;
use LarAgent\Agent;
class MyAgent extends Agent
{
// Your agent implementation
}
/** @var string - Define the agent's behavior and role */
protected $instructions;
/** @var string - Create your or Choose from built-in chat history: "in_memory", "session", "cache", "file", or "json" */
protected $history;
/** @var string - Specify which LLM driver to use */
protected $driver;
/** @var string - Select the AI provider configuration from your config file */
protected $provider = 'default';
/** @var string - Choose which language model to use */
protected $model = 'gpt-4o-mini';
/** @var int - Set the maximum number of tokens in the completion */
protected $maxCompletionTokens;
/** @var float - Control response creativity (0.0 for focused, 2.0 for creative) */
protected $temperature;
/** @var string|null - Current message being processed */
protected $message;
/**
* Define the agent's system instructions
* This sets the behavior, role, and capabilities of your agent
* For simple textual instructions, use the `instructions` property
* For more complex instructions or dynamic behavior, use the `instructions` method
*/
public function instructions()
{
return "Define your agent's instructions here.";
}
/**
* Customize how messages are processed before sending to the AI
* Useful for formatting, adding context (RAG), or standardizing input
*/
public function prompt(string $message)
{
return $message;
}
/**
* Decide which model to use dynamically with custom logic
* Or use property $model to statically set the model
*/
public function model()
{
return $this->model;
}
class WeatherAgent extends Agent
{
protected $model = 'gpt-4';
protected $history = 'cache';
protected $temperature = 0.7;
public function instructions()
{
return "You are a weather expert assistant. Provide accurate weather information.";
}
public function prompt(string $message)
{
return "Weather query: " . $message;
}
}
// Using a specific chat history name
echo WeatherAgent::for('test_chat')->respond('What is the weather like?');
$response = WeatherAgent::for('test_chat')
->message('What is the weather like?') // Set the message
->temperature(0.7) // Optional: Override temperature
->respond(); // Get the response
// Different histories for different users
echo WeatherAgent::for('user_1_chat')->respond('What is the weather like?');
echo WeatherAgent::for('user_2_chat')->respond('How about tomorrow?');
echo WeatherAgent::forUser(auth()->user())->respond('How about tomorrow?');
/**
* Set the message for the agent to process
*/
public function message(string $message);
/**
* Add images to the agent's input (message)
* @param array $imageUrls Array of image URLs
*/
public function withImages(array $imageUrls);
/**
* Decide model dynamically in your controller
* @param string $model Model identifier (e.g., 'gpt-4o', 'gpt-3.5-turbo')
*/
public function withModel(string $model);
/**
* Add custom message to the chat history with a needed role
* @param MessageInterface Easily created with message class: Message::system('Your message here')
*/
public function addMessage(MessageInterface $message);
/**
* Clear the chat history
* This removes all messages from the chat history
*/
public function clear();
/**
* Set other chat history instance
*/
public function setChatHistory(ChatHistoryInterface $chatHistory);
/**
* Add tool to the agent's registered tools
*/
public function withTool(ToolInterface $tool);
/**
* Remove tool for this specific call
*/
public function removeTool(string $name);
/**
* Override the temperature for this specific call
*/
public function temperature(float $temp);
/**
* Get the current chat session ID
* String like "[AGENT_NAME]_[MODEL_NAME]_[CHAT_NAME]"
* CHAT_NAME is defined by "for" method
* Example: WeatherAgent_gtp-4o-mini_test-chat
*/
public function getChatSessionId(): string;
/**
* Returns the provider name
*/
public function getProviderName(): string;
/**
* Returns an array of registered tools
*/
public function getTools(): array;
/**
* Returns current chat history instance
*/
public function chatHistory(): ChatHistoryInterface;
/**
* Returns the current message
*/
public function currentMessage(): ?string;
/**
* Returns the last message
*/
public function lastMessage(): ?MessageInterface;
/**
* Get all chat keys associated with this agent class
*/
public function getChatKeys(): array;
use LarAgent\Attributes\Tool;
// ...
#[Tool('Get the current weather')]
public function getWeather(string $city)
{
return WeatherService::getWeather($city);
}
/** @var bool - Controls whether tools can be executed in parallel */
protected $parallelToolCalls;
/** @var array - List of tool classes to be registered with the agent */
protected $tools = [];
use LarAgent\Tool;
// ...
public function registerTools()
{
return [
$user = auth()->user();
Tool::create("user_location", "Returns user's current location")
->setCallback(function () use ($user) {
return $user->location()->city;
}),
Tool::create("get_current_weather", "Returns the current weather in a given location")
->addProperty("location", "string", "The city and state, e.g. San Francisco, CA")
->setCallback("getWeather"),
];
}
use LarAgent\Attributes\Tool;
// Basic tool with parameters
#[Tool('Get the current weather in a given location')]
public function weatherTool($location, $unit = 'celsius')
{
return 'The weather in '.$location.' is '.'20'.' degrees '.$unit;
}
namespace App\Enums;
enum Unit: string
{
case CELSIUS = 'celsius';
case FAHRENHEIT = 'fahrenheit';
}
use LarAgent\Attributes\Tool;
use App\Enums\Unit;
// ...
#[Tool(
'Get the current weather in a given location',
['unit' => 'Unit of temperature', 'location' => 'The city and state, e.g. San Francisco, CA']
)]
public static function weatherToolForNewYork(Unit $unit, $location = 'New York')
{
return WeatherService::getWeather($location, $unit->value);
}
class WeatherTool extends LarAgent\Tool
{
protected string $name = 'get_current_weather';
protected string $description = 'Get the current weather in a given location';
protected array $properties = [
'location' => [
'type' => 'string',
'description' => 'The city and state, e.g. San Francisco, CA',
],
'unit' => [
'type' => 'string',
'description' => 'The unit of temperature',
'enum' => ['celsius', 'fahrenheit'],
],
];
protected array $
protected $history = 'in_memory'; // Stores chat history temporarily in memory (lost after request)
protected $history = 'session'; // Uses Laravel's session storage
protected $history = 'cache'; // Uses Laravel's cache system
protected $history = 'file'; // Stores in files (storage/app/chat-histories)
protected $history = 'json'; // Stores in JSON files (storage/app/chat-histories)
LarAgent\History\InMemoryChatHistory::class // Stores chat history in memory
LarAgent\History\JsonChatHistory::class // Stores in JSON files
/** @var int - Number of messages after which to reinject the agent's instructions */
protected $reinjectInstructionsPer;
/** @var int - Maximum number of tokens to keep in context window */
protected $contextWindowSize;
/** @var bool - Whether to store additional metadata with messages */
protected $storeMeta;
/** @var bool - Store chat keys in memory */
protected $saveChatKeys;
/** @var bool - Use developer role for instructions */
protected $developerRoleForInstructions;
public function createChatHistory($name)
{
return new \App\ChatHistories\CustomChatHistory($name, ['folder' => __DIR__.'/history']);
}
// Using specific chat history name
$agent = WeatherAgent::for('weather-chat');
// Using user-specific chat history
$agent = WeatherAgent::forUser(auth()->user());
// Clear chat history
$agent->clear();
// Get last message
$lastMessage = $agent->lastMessage();
// Access chat history instance
$history = $agent->chatHistory();
public function addMessage(MessageInterface $message): void;
public function getMessages(): array;
public function getIdentifier(): string;
public function getLastMessage(): ?MessageInterface;
public function count(): int;
public function clear(): void;
public function toArray(): array;
public function toArrayWithMeta(): array;
public function setContextWindow(int $tokens): void;
public function exceedsContextWindow(int $tokens): bool;
$historyInstance = new $historyClass($sessionId, [
'context_window' => $this->contextWindowSize, // Control token limit
'store_meta' => $this->storeMeta, // Store additional message metadata
]);
// Get current schema
$schema = $agent->structuredOutput();
// Check if structured output is enabled
if ($agent->structuredOutput()) {
// Handle structured response
}
// File: config/laragent.php
// ...
'providers' => [
'openrouter' => [
'name' => 'some-label', // Name is only for internal use like a label, you can use any name
'driver' => \LarAgent\Drivers\OpenAi\OpenAiCompatible::class,
'api_key' => env('OPENROUTER_API_KEY'),
'api_url' => "https://api.openrouter.ai/api/v1",
'default_context_window' => 50000,
'default_max_completion_tokens' => 100,
'default_temperature' => 1,
],
],
// ...
protected $provider = 'openrouter';
// ...
protected function onInitialize()
{
if (auth()->check() && auth()->user()->prefersCreative()) {
$this->temperature(1.4);
}
}
// Log agent class and message
protected function onConversationStart()
{
Log::info(
'Starting new conversation',
[
'agent' => self::class,
'message' => $this->currentMessage()
]
);
}
/** @param MessageInterface|array|null $message */
protected function onConversationEnd($message)
{
// Clean the history
$this->clear();
// Save the last response
DB::table('chat_histories')->insert(
[
'chat_session_id' => $this->chatHistory()->getIdentifier(),
'message' => $message,
]
);
}
/**
* @param ChatHistoryInterface $history
* @param MessageInterface|null $message
*/
protected function beforeResponse($history, $message)
{
// Add context to the message
if ($message) {
Log::info('User message: ' . $message->getContent());
}
return true;
}
/**
* @param MessageInterface $message
*/
protected function afterResponse($message)
{
// Process or validate the LLM response
if (is_array($message->getContent())) {
Log::info('Structured response received');
}
return true;
}
/**
* @param ToolInterface $tool
* @return bool
*/
protected function beforeToolExecution($tool)
{
// Check tool permissions
if (!$this->hasToolPermission($tool->getName())) {
Log::warning("Unauthorized tool execution attempt: {$tool->getName()}");
return false;
}
return true;
}
/**
* @param ToolInterface $tool
* @param mixed &$result
* @return bool
*/
protected function afterToolExecution($tool, &$result)
{
// Modify or format tool results
if (is_array($result)) {
// Since tool result is reference (&$result), we can safely modify it
$result = array_map(fn($item) => trim($item), $result);
}
return true;
}
protected function beforeStructuredOutput(array &$response)
{
// Return false if response contains something unexpected
if (!$this->checkArrayContent($response)) {
return false; // After returning false, the method stops executing and 'respond' will return `null`
}
// Add additional data to output
$response['timestamp'] = now()->timestamp;
return true;
}
// app/Events/AgentMessageReceived.php
class AgentMessageReceived
{
use Dispatchable, InteractsWithSockets, SerializesModels;
public function __construct(
public ChatHistoryInterface $history,
public MessageInterface $message
) {}
}