Understanding Agents in the Laravel AI SDK

Laravel AI SDK-তে agent হলো main application-facing abstraction। Agent কোনো magical worker নয় যে product logic নিজের হাতে নিয়ে নেবে। Agent হলো dedicated PHP class, যেখানে একটি AI-powered responsibility-এর instruction, optional conversation context, tool, output contract এবং generation setting এক জায়গায় রাখা হয়।

এই distinction গুরুত্বপূর্ণ। Agent configured boundary-এর মধ্যে response decide করতে পারে, কিন্তু authorization, validation, persistence, queue, retry, logging এবং final business decision Laravel-এর দায়িত্বেই থাকে। ভালো agent AI behavior review করা সহজ করে; normal application engineering বাদ দেয় না।

Agent আসলে কী represent করে

Laravel AI SDK-তে agent হলো এমন একটি class, যা Agent contract implement করে এবং সাধারণত Promptable trait ব্যবহার করে। Official documentation agent-কে dedicated PHP class হিসেবে describe করে, যেখানে instruction, conversation context, tool এবং output schema encapsulate করা যায়।

মানে agent-এর একটি clear job থাকা উচিত। SupportSummaryAgent support ticket summarize করবে। ProductDescriptionAgent catalog copy improve করবে। RefundPolicyAgent approved document থেকে policy explain করবে। Agent-এর নাম যদি department-এর মতো শোনায়, তাহলে agent সম্ভবত অনেক broad।

Minimal agent class

সবচেয়ে ছোট useful agent হলো clear instruction-সহ একটি named class। Instruction-এ job, audience, allowed behavior এবং uncertainty rule থাকা উচিত।

1<?php2 3namespace App\Ai\Agents;4 5use Laravel\Ai\Attributes\MaxTokens;6use Laravel\Ai\Attributes\Temperature;7use Laravel\Ai\Contracts\Agent;8use Laravel\Ai\Promptable;9 10#[MaxTokens(900)]11#[Temperature(0.3)]12class SupportReplyDraftAgent implements Agent13{14    use Promptable;15 16    public function instructions(): string17    {18        return <<<'PROMPT'19You draft support replies for a Laravel SaaS product.20 21Write in a calm, helpful tone.22Use only the ticket details and internal notes provided by the application.23Do not promise refunds, credits, account changes, or engineering timelines.24If information is missing, ask the support agent to verify it.25Return a draft reply, not a final customer-visible decision.26PROMPT;27    }28}

এখানে syntax সবচেয়ে গুরুত্বপূর্ণ নয়; boundary গুরুত্বপূর্ণ। Agent reply draft করতে পারে, কিন্তু account change promise করতে পারে না। এই rule agent instruction-এ থাকবে এবং agent-এর চারপাশের Laravel workflow-তেও enforce হবে।

Agent-এর ভেতরে কী থাকবে

Agent class durable AI behavior রাখার ভালো জায়গা: instruction, allowed tool, output schema, provider setting এবং agent-specific middleware। কিন্তু random controller input, hidden database query অথবা business decision agent-এর ভেতরে লুকিয়ে রাখা ভালো idea নয়।

• Stable task instruction agent-এ রাখুন।
• Model configuration এবং token limit attribute বা configuration-এ রাখুন।
• Task সত্যিই external capability চাইলে allowed tool agent-এ define করুন।
• Laravel structured data expect করলে output schema agent-এ রাখুন।
• Authorization model call-এর আগে controller, policy, action অথবা service-এ রাখুন।
• Database write, payment change এবং final approval deterministic Laravel code-এ রাখুন।

Agent-এর বাইরে কী থাকবে

Agent-এর চারপাশের Laravel service trusted context prepare করবে, agent call করবে, result validate করবে, usage log করবে এবং product কীভাবে response দেবে তা decide করবে। এতে HTTP layer thin থাকে এবং AI behavior একটি testable workflow-এর মধ্যে থাকে।

1<?php2 3namespace App\Services;4 5use App\Ai\Agents\SupportReplyDraftAgent;6use App\Models\SupportTicket;7use Illuminate\Support\Facades\Gate;8 9class DraftSupportReply10{11    public function handle(SupportTicket $ticket): string12    {13        Gate::authorize('view', $ticket);14 15        $prompt = <<<TEXT16Draft a support reply for this ticket.17 18Subject: {$ticket->subject}19Customer message:20{$ticket->message}21 22Internal notes:23{$ticket->internal_notes}24TEXT;25 26        $response = (new SupportReplyDraftAgent)->prompt($prompt);27 28        logger()->info('support_reply_draft.generated', [29            'ticket_id' => $ticket->id,30            'input_tokens' => $response->usage?->inputTokens,31            'output_tokens' => $response->usage?->outputTokens,32            'total_tokens' => $response->usage?->totalTokens(),33        ]);34 35        return trim((string) $response->content);36    }37}

এই service decide করে ticket-এর কোন data prompt-এ যাবে। Agent শুধু দরকারি context পায়। Model database, user session বা support team-এর private workflow সরাসরি access করে না, যদি না Laravel explicit controlled tool দেয়।

Agent execution loop

Plain model call সাধারণত এক request এবং এক response। Agent বেশি involved হতে পারে, কারণ tool এবং multi-step behavior loop-এ আসতে পারে। Model সরাসরি answer দিতে পারে, tool request করতে পারে, tool output পেতে পারে, তারপর final response দিতে পারে।

এই loop-এর কারণেই max steps এবং tool boundary গুরুত্বপূর্ণ। Tool-using agent simple prompt-এর চেয়ে powerful, কিন্তু cost, latency এবং validation point-ও বাড়ায়।

Tool agent-কে useful এবং risky দুটোই করে

Tool agent-কে Laravel-এর কাছে controlled কাজ request করতে দেয়: knowledge base search, order retrieve, file inspect অথবা action prepare করা। Tool যেখানে real application capability দেখা দেয়, তাই এটি narrow এবং permission-aware হতে হবে।

1use App\Ai\Tools\FindRelevantHelpArticles;2use Laravel\Ai\Contracts\HasTools;3 4class SupportReplyDraftAgent implements Agent, HasTools5{6    use Promptable;7 8    public function tools(): iterable9    {10        return [11            new FindRelevantHelpArticles,12        ];13    }14 15    public function instructions(): string16    {17        return 'Draft support replies using only the ticket context and approved help articles.';18    }19}

Model-এর দরকার হতে পারে বলে “run SQL”, “call any internal API” বা “write to storage” ধরনের broad tool expose করবেন না। Explicit input, authorization, logging এবং safe failure behavior-সহ ছোট tool তৈরি করুন। Write-capable tool-এর আগে read-only tool দিয়ে শুরু করাই ভালো।

Attribute দিয়ে model behavior control করা

SDK provider, model, max steps, max tokens, temperature, timeout এবং sampling option-এর মতো model behavior attribute support করে। এগুলো product decision, decoration নয়।

1use Laravel\Ai\Attributes\MaxSteps;2use Laravel\Ai\Attributes\MaxTokens;3use Laravel\Ai\Attributes\Model;4use Laravel\Ai\Attributes\Temperature;5use Laravel\Ai\Attributes\Timeout;6use Laravel\Ai\Contracts\Agent;7use Laravel\Ai\Promptable;8 9#[Model('gpt-5.1-mini')]10#[MaxSteps(4)]11#[MaxTokens(900)]12#[Temperature(0.3)]13#[Timeout(30)]14class SupportReplyDraftAgent implements Agent15{16    use Promptable;17 18    // ...19}

Classification, extraction, policy explanation এবং support workflow-এর জন্য lower temperature সাধারণত ভালো। Brainstorming বা marketing copy-এর জন্য higher temperature useful হতে পারে। Max steps agent-কে indefinitely tool call করা থেকে থামায়। Timeout এবং token limit user experience ও cost protect করে।

Structured output agent-কে contract বানায়

Laravel যদি data চায়, paragraph-এর ওপর depend করবেন না। Structured output চাইুন এবং validate করুন। যেমন ticket triage agent priority, category, confidence এবং short explanation return করতে পারে। UI explanation দেখাতে পারে, কিন্তু queue বা routing logic validated field ব্যবহার করবে।

Structured output model-কে deterministic করে না। এটি boundary validate করা সহজ করে। Laravel-এর schema check, enum check, record existence check এবং invalid response fallback দরকারই থাকে।

Agent-কে product workflow-এর মতো observe করুন

Agent multiple step, tool এবং provider call involve করতে পারে, তাই শুধু final text log করা যথেষ্ট নয়। Run-এর operational shape track করুন, যাতে quality, latency, failure এবং cost debug করা যায়।

• Agent class এবং prompt version।
• Provider, model, temperature, max tokens এবং max steps।
• Input token, output token, cached token, total token এবং response time।
• Requested tool name, tool duration, tool failure এবং denied tool call।
• Validation status, fallback path এবং human result edit করেছে কি না।
• Cost attribution দরকার হলে safe user বা tenant identifier।

Sensitive prompt content log করা উচিত নয়, যদি product এবং privacy rule explicit allow না করে। অনেক system-এ dashboard-এর জন্য metadata যথেষ্ট; full prompt capture controlled debugging environment-এ সীমাবদ্ধ থাকে।

Common agent design mistake

Agent problem বেশিরভাগ সময় SDK-এর কারণে হয় না। Problem আসে vague responsibility এবং weak boundary থেকে। Agent সবকিছু করতে পারলে test, observe এবং trust করা কঠিন হয়ে যায়।

• Unrelated product workflow-এর জন্য একটি “AssistantAgent” বানানো।
• Authorization বা database write decision prompt-এর ভেতরে রাখা, Laravel code-এ নয়।
• Task-এর জন্য দুইটি field দরকার হলেও পুরো record পাঠানো।
• Narrow input validation ছাড়া broad operation-capable tool expose করা।
• Consistency দরকার এমন workflow-তে high temperature ব্যবহার করা।
• Model output-কে draft, suggestion বা validated data structure নয়, final truth হিসেবে treat করা।
• Provider timeout বা invalid output হলে fallback behavior skip করা।

Series-এ agent কোথায় fit করে

Agent Laravel AI SDK-তে AI behavior package করার clean জায়গা দেয়। Instruction, tool, structured output এবং model setting এখানে একসঙ্গে আসে। কিন্তু agent সবসময় larger Laravel workflow-এর ভেতরে থাকা উচিত, যেখানে data access, validation, cost এবং user trust control করা হয়।

পরের episode-এ আমরা Laravel application-এর prompt engineering নিয়ে কথা বলব: instruction, context, constraint, example এবং output rule কীভাবে structure করলে agent বুঝতে সহজ হয় এবং change করা safer হয়।