Create & Configure - Official LarAgent Documentation

Creating an Agent

The recommended way to create a new agent is using the artisan command:

php artisan make:agent MyAgent

This generates a new agent class in the App\AiAgents directory with all the necessary boilerplate:

App/AiAgents/MyAgent.php

<?php

namespace App\AiAgents;

use LarAgent\Agent;

class MyAgent extends Agent
{
    protected $model = 'gpt-4o-mini';

    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;
    }
}

Name your agents descriptively based on their purpose. CustomerSupportAgent is clearer than Agent1 or MyAgent.

Core Methods

Override these methods to customize your agent’s behavior:

instructions()

The system prompt that shapes how your agent responds. This defines the agent’s personality, role, and guidelines.

public function instructions()
{
    return "You are an expert financial advisor. Provide clear, 
            actionable advice while always recommending users 
            consult with a certified professional for major decisions.";
}

For simple, static instructions you can use the $instructions property instead of the method.

For complex or dynamic instructions, consider using Blade template files. This keeps your agent class clean and allows you to leverage Blade’s templating features like conditionals and loops.

prompt()

Process or augment the user’s message before sending it to the LLM. Useful for adding context, formatting, or implementing RAG patterns.

public function prompt($message)
{
    $context = $this->retrieveRelevantContext($message);
    
    return "Context: {$context}\n\nUser question: {$message}";
}

model()

Dynamically determine which model to use based on custom logic:

public function model()
{
    // Use a more powerful model for complex queries
    if ($this->isComplexQuery()) {
        return 'gpt-4o';
    }
    
    return 'gpt-4o-mini';
}

API Key and URL

Override these methods to dynamically set API credentials:

public function getApiKey()
{
    // Use different API keys per tenant
    return auth()->user()->team->openai_api_key;
}

public function getApiUrl()
{
    return config('services.openai.url');
}

Configuration Properties

Model & Provider

Property	Type	Description
`$model`	`string`	The LLM model to use (e.g., `gpt-4o-mini`, `gpt-4o`)
`$provider`	`string`	Provider configuration name from `config/laragent.php`
`$driver`	`string`	Driver class for LLM communication

class MyAgent extends Agent
{
    protected $model = 'gpt-4o';
    protected $provider = 'openai';
    protected $driver = \LarAgent\Drivers\OpenAi\OpenAiDriver::class;
}

LarAgent supports multiple AI providers including OpenAI, Anthropic, Gemini, Groq, and Ollama. See LLM Drivers for setup instructions and available options.

Response Settings

Control how the LLM generates responses:

$temperature — Control creativity

Controls randomness in responses. Range: 0.0 (focused/deterministic) to 2.0 (creative/random).

protected $temperature = 0.7; // Balanced

$maxCompletionTokens — Limit response length

Maximum number of tokens in the AI’s response.

protected $maxCompletionTokens = 2000;

$n — Multiple responses

Generate multiple completion choices. Note: You’ll be charged for all generated tokens.

protected $n = 3; // Returns array of 3 responses

$topP — Nucleus sampling

Alternative to temperature. The model considers tokens with top_p probability mass.

protected $topP = 0.1; // Only top 10% probability tokens

Use either $temperature or $topP, not both.

$frequencyPenalty — Reduce repetition

Penalizes tokens based on their frequency in the text. Range: -2.0 to 2.0.

protected $frequencyPenalty = 0.5; // Reduces verbatim repetition

$presencePenalty — Encourage new topics

Penalizes tokens based on whether they’ve appeared. Range: -2.0 to 2.0.

protected $presencePenalty = 0.5; // Encourages discussing new topics

All configuration properties can also be set via the provider settings in config/laragent.php.

History & Tools

Property	Type	Description
`$history`	`string`	Chat history storage: `in_memory`, `session`, `cache`, `file`
`$tools`	`array`	Array of tool classes the agent can use

class MyAgent extends Agent
{
    protected $history = 'cache';
    
    protected $tools = [
        \App\Tools\WeatherTool::class,
        \App\Tools\CalculatorTool::class,
    ];
}

Both Context (chat history, data models) and Tools are core features of LarAgent with extensive configuration options. The properties shown here are just the basics.

Learn about context management, storage drivers, and truncation strategies in the Context page
Explore tool creation, parameters, and execution in the Tools Section

Arbitrary Configuration

Pass custom configuration values to the driver for provider-specific settings or experimental features:

class MyAgent extends Agent
{
    protected $configs = [
        'reasoning_effort' => 'high',
        'custom_header' => 'value',
    ];
}

$agent = MyAgent::for('chat-123')
    ->withConfigs([
        'reasoning_effort' => 'high',
        'timeout' => 60,
    ])
    ->respond('Analyze this problem');

// Set single config
$agent->setConfig('custom_key', 'value');

// Get config
$value = $agent->getConfig('custom_key');

// Check existence
if ($agent->hasConfig('custom_key')) {
    // ...
}

// Remove config
$agent->removeConfig('custom_key');

Custom configurations are passed directly to the driver, allowing you to leverage provider-specific features without modifying the agent’s core properties.

Runtime Configuration

Override any configuration at runtime using chainable methods:

$response = WeatherAgent::for('user-123')
    ->withModel('gpt-4o')
    ->temperature(0.9)
    ->maxCompletionTokens(1000)
    ->respond('Write a creative story');

All properties have corresponding chainable methods:

$temperature → temperature(float $temp)
$maxCompletionTokens → maxCompletionTokens(int $tokens)
$topP → topP(float $value)
And so on…

Next Steps

Responses

Learn how to interact with agents and handle their responses.

Streaming

Stream responses in real-time for better user experience.

Tools

Give your agents capabilities to perform actions and retrieve data.

Chat History

Manage conversation history and context persistence.

​Creating an Agent

​Core Methods

​instructions()

​prompt()

​model()

​API Key and URL

​Configuration Properties

​Model & Provider

​Response Settings

​History & Tools

​Arbitrary Configuration

​Runtime Configuration

​Next Steps

Responses

Streaming

Tools

Chat History

Creating an Agent

Core Methods

instructions()

prompt()

model()

API Key and URL

Configuration Properties

Model & Provider

Response Settings

History & Tools

Arbitrary Configuration

Runtime Configuration

Next Steps