ai-agent-patterns

AI Agent Patterns

When to Apply

• Creating a new agent class in app/Ai/Agents/
• Modifying AgentResolver action or prompt mappings
• Writing tests for agents (::fake(), ::assertPrompted())
• Working with SSE streaming in AdminArticleAiController
• Adding or changing apply block formats (:::apply-body, :::apply-excerpt)
• Debugging agent responses, conversation linking, or temperature behavior

Documentation

Use search-docs for detailed Laravel AI SDK documentation before making changes.

Agent Anatomy

Every agent implements Agent & Conversational (intersection type), uses three traits, and is configured via PHP attributes. All agents run on Ollama (Docker service), not OpenAI.

use App\Ai\Agents\Concerns\HasArticleContext; use Laravel\Ai\Attributes\MaxTokens; use Laravel\Ai\Attributes\Model; use Laravel\Ai\Attributes\Temperature; use Laravel\Ai\Attributes\Timeout; use Laravel\Ai\Concerns\RemembersConversations; use Laravel\Ai\Contracts\Agent; use Laravel\Ai\Contracts\Conversational; use Stringable;

#[Model('llama3.2:3b')] // Ollama model — NOT OpenAI #[Temperature(0.6)] // 0.3 (precise) to 0.8 (creative) #[MaxTokens(4096)] // Fixed for all agents #[Timeout(120)] // Fixed for all agents class ArticleRefiner implements Agent, Conversational { use HasArticleContext, Promptable, RemembersConversations;

public function instructions(): Stringable|string
{
    return <<<INSTRUCTIONS
    You are an expert content editor...

    {$this->articleContextBlock()}
    {$this->applyBlockInstructions()}
    INSTRUCTIONS;
}

}

Temperature spectrum — choose based on the agent's task precision:

Temperature	Agent	Rationale
0.3	GrammarChecker	Deterministic corrections, no creativity needed
0.4	Proofreader	Slight variation in feedback phrasing
0.5	SeoOptimizer	Balanced analysis with structured output
0.6	ArticleRefiner	Creative improvement while preserving voice
0.8	ArticleGenerator	Maximum creativity for original content