PHP ile AI Ajanları Oluşturma: Laravel ile Araç Çağırma

Problem: Sadece konuşabilen sohbet botu

<p>Önceki bölümdeki sohbet botu soruları yanıtlayabiliyor, ancak ona "Dün kaç sipariş gönderdik?" diye sorarsanız, kendine güvenle bir cevap uyduracaktır. Veritabanınızı sorgulama, hizmetlerinizi arama veya sadece metin üretmekten başka bir şey yapamaz.</p>

<p>Tool calling bu durumu düzeltir. Kullanıcının isteğine göre fonksiyonları model aracılığıyla tanımlarsınız; model ihtiyaç duyduğunda "bu fonksiyonu bu argümanlarla çağır" diye yanıt verir. Kodunuz fonksiyonu çalıştırır, sonucu geri besler ve model veriye dayanarak son cevabı yazar. Bu döngü — model araç seçer, siz icra edersiniz, model devam eder — "ajanlar" konusundaki tüm numara. Herhangi bir çatıya ihtiyaç yok.</p>

<p>Bu yapıyı üretim aşamasında Laravel uygulamalarında sipariş sorguları, rapor oluşturma ve destek triage işleri için kullandım. Gerçek kullanıcılarla temas eden desen budur.</p>

<h2>
    <a name="architecture" href="#architecture"></a>
    Mimari
</h2>

<p>Üç parça, hepsi sade Laravel:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight plaintext"><code>User message ──→ AgentController
                 │
                 ▼
          AgentRunner (the loop, max N rounds)
                 │
    ┌── model returns text? ──→ done, return answer
    │
    └── model returns tool_calls?
                 │
                 ▼
          ToolRegistry ──→ OrderLookupTool
                        ──→ ShippingStatusTool
                 │              (each: name, schema, handle())
                 ▼
          results appended to messages ──→ back to the model

            <svg xmlns="http://www.w3.org/2000/svg" width="20px" height="20px" viewbox="0 0 24 24" class="highlight-action crayons-icon highlight-action--fullscreen-off"><title>Exit fullscreen mode</title>
            <path d="M18 7h4v2h-6V3h2v4zM8 9H2V7h4V3h2v6zm10 8v4h-2v-6h6v2h-4zM8 15v6H6v-4H2v-2h6z"/>
            </svg>

        </div>
    </div>
</div>

<p>Her araç bir sınıf olarak tanımlanır. Kayıt defteri isimleri sınıflara eşleyerek çalışır. Koşucu döngüyü ve güvenlik önlemlerini yönetir. Bu kadar.</p>

<h2>
    <a name="step-1-a-tool-contract" href="#step-1-a-tool-contract"></a>
    Adım 1: Bir araç sözleşmesi
</h2>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="c1">// app/Ai/Tools/Tool.php</span>

interface Tool
{
public function name(): string;

<span class="k">public</span> <span class="k">function</span> <span class="n">description</span><span class="p">():</span> <span class="kt">string</span><span class="p">;</span>

<span class="cd">/  JSON Schema for the arguments the model may pass. */</span>
<span class="k">public</span> <span class="k">function</span> <span class="n">parameters</span><span class="p">():</span> <span class="kt">array</span><span class="p">;</span>

<span class="cd">/  @param array $args validated arguments from the model */</span>
<span class="k">public</span> <span class="k">function</span> <span class="n">handle</span><span class="p">(</span><span class="kt">array</span> <span class="nv">$args</span><span class="p">):</span> <span class="kt">string</span><span class="p">;</span>

}

            <svg xmlns="http://www.w3.org/2000/svg" width="20px" height="20px" viewbox="0 0 24 24" class="highlight-action crayons-icon highlight-action--fullscreen-off"><title>Exit fullscreen mode</title>
            <path d="M18 7h4v2h-6V3h2v4zM8 9H2V7h4V3h2v6zm10 8v4h-2v-6h6v2h-4zM8 15v6H6v-4H2v-2h6z"/>
            </svg>

        </div>
    </div>
</div>

<p>Araçlar string döndürür çünkü bu, konuşmaya geri dönecek olan şeydir. Yapılandırılmış veriyi JSON olarak kodlayın — modeller bunu güzelce okuyabilir.</p>

<h2>
    <a name="step-2-a-real-tool" href="#step-2-a-real-tool"></a>
    Adım 2: Gerçek bir araç
</h2>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="c1">// app/Ai/Tools/OrderLookupTool.php</span>

class OrderLookupTool implements Tool
{
public function name(): string
{
return ‘order_lookup’;
}

<span class="k">public</span> <span class="k">function</span> <span class="n">description</span><span class="p">():</span> <span class="kt">string</span>
<span class="p">{</span>
    <span class="k">return</span> <span class="s1>'Siparişi numarasına göre kontrol eder. Durum, ürünler ve gönderim bilgilerini döndürür.'</span><span class="p">;</span>
<span class="p">}</span>

<span class="k">public</span> <span class="k">function</span> <span class="n">parameters</span><span class="p">():</span> <span class="kt">array</span>
<span class="p">{</span>
    <span class="k">return</span> <span class="p">[</span>
        <span class="s1>'type'</span> <span class="o">=&gt;</span> <span class="s1>'object'</span><span class="p">,</span>
        <span class="s1>'properties'</span> <span class="o">=&gt;</span> <span class="p">[</span>
            <span class="s1>'order_number'</span> <span class="o">=&gt;</span> <span class="p">[</span>
                <span class="s1>'type'</span> <span class="o">=&gt;</span> <span class="s1>'string'</span><span class="p">,</span>
                <span class="s1>'description'</span> <span class="o">=&gt;</span> <span class="s1>'Sipariş numarası, ör. ORD-2041'</span><span class="p">,</span>
            <span class="p">],</span>
        <span class="p">],</span>
        <span class="s1>'required'</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1>'order_number'</span><span class="p">],</span>
    <span class="p">];</span>
<span class="p">}</span>

<span class="k">public</span> <span class="k">function</span> <span class="n">handle</span><span class="p">(</span><span class="kt">array</span> <span class="nv>$args</span><span class="p">):</span> <span class="kt">string</span>
<span class="p">{</span>
    <span class="nv>$order</span> <span class="o">=</span> <span class="nc">Order</span><span class="o">::</span><span class="nf">where</span><span class="p">(</span><span class="s1>'number'</span><span class="p">,</span> <span class="nv>$args</span><span class="p">[</span><span class="s1>'order_number'</span><span class="p">])</span>
        <span class="o">-&gt;</span><span class="nf">where</span><span class="p">(</span><span class="s1>'user_id'</span><span class="p">,</span> <span class="nf">auth</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">id</span><span class="p">())</span>   <span class="c1">// ← önemli satır</span>
        <span class="o">-&gt;</span><span class="nf">first</span><span class="p">();</span>

    <span class="k">if</span> <span class="p">(</span><span class="o">!</span> <span class="nv>$order</span><span class="p">)</span> <span class="p">{</span>
        <span class="k">return</span> <span class="nb">json_encode</span><span class="p">([</span><span class="s1>'error'</span> <span class="o">=&gt;</span> <span class="s1>'Bu hesap için sipariş bulunamadı.'</span><span class="p">]);</span>
    <span class="p">}</span>

    <span class="k">return</span> <span class="nb">json_encode</span><span class="p">([</span>
        <span class="s1>'number'</span> <span class="o">=&gt;</span> <span class="nv>$order</span><span class="o">-&gt;</span><span class="n">number</span><span class="p">,</span>
        <span class="s1>'status'</span> <span class="o">=&gt;</span> <span class="nv>$order</span><span class="o">-&gt;</span><span class="n">status</span><span class="p">,</span>
        <span class="s1>'items'</span> <span class="o">=&gt;</span> <span class="nv>$order</span><span class="o">-&gt;</span><span class="n">items</span><span class="o">-&gt;</span><span class="nf">pluck</span><span class="p">(</span><span class="s1>'name'</span><span class="p">),</span>
        <span class="s1>'shipped_at'</span> <span class="o">=&gt;</span> <span class="nv>$order</span><span class="o">-&gt;</span><span class="n">shipped_at</span><span class="o">?-></span><span class="nf">toDateString</span><span class="p">(),</span>
    <span class="p">]);</span>
<span class="p">}</span>

}

            <svg xmlns="http://www.w3.org/2000/svg" width="20px" height="20px" viewbox="0 0 24 24" class="highlight-action crayons-icon highlight-action--fullscreen-off"><title>Exit fullscreen mode</title>
            <path d="M18 7h4v2h-6V3h2v4zM8 9H2V7h4V3h2v6zm10 8v4h-2v-6h6v2h-4zM8 15v6H6v-4H2v-2h6z"/>
            </svg>

        </div>
    </div>
</div>

<p><code>auth()->id()</code> ifadesi bu yazıda en önemli kısımdır. Model hangi aracı çağıracağına ve hangi argümanları geçeceğine karar verir; bir saldırgan bunu hileli bir taleple yönlendirebilir. Yetkilendirme, daima kodunuzda olmalıdır, asla talepte değil. Her aracı bir genel API uç noktası olarak değerlendirin, çünkü artık öyle.</p>

<h2>
    <a name="step-3-the-loop" href="#step-3-the-loop"></a>
    Adım 3: Döngü
</h2>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="c1">// app/Ai/AgentRunner.php</span>

class AgentRunner
{
private const MAX_ROUNDS = 5;

<span class="k">public</span> <span class="k">function</span> <span class="n">__construct</span><span class="p">(</span><span class="k">private</span> <span class="kt">ToolRegistry</span> <span class="nv">$tools</span><span class="p">)</span> <span class="p">{}</span>

<span class="k">public</span> <span class="k">function</span> <span class="n">run</span><span class="p">(</span><span class="kt">array</span> <span class="nv">$messages</span><span class="p">):</span> <span class="kt">string</span>
<span class="p">{</span>
    <span class="k">foreach</span> <span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="k">self</span><span class="o">::</span><span class="no">MAX_ROUNDS</span><span class="p">)</span> <span class="k">as</span> <span class="nv">$round</span><span class="p">)</span> <span class="p">{</span>
        <span class="nv">$response</span> <span class="o">=</span> <span class="nc">Http</span><span class="o">::</span><span class="nf">withToken</span><span class="p">(</span><span class="nf">config</span><span class="p">(</span><span class="s1>'services.openai.key'</span><span class="p">))</span>
            <span class="o">-&gt;</span><span class="nf">timeout</span><span class="p">(</span><span class="mi">30</span><span class="p">)</span>
            <span class="o">-&gt;</span><span class="nf">post</span><span class="p">(</span><span class="s1>'https://api.openai.com/v1/chat/completions'</span><span class="p">,</span> <span class="p">[</span>
                <span class="s1>'model'</span> <span class="o">=&gt;</span> <span class="s1>'gpt-4.1-mini'</span><span class="p">,</span>
                <span class="s1>'messages'</span> <span class="o">=&gt;</span> <span class="nv">$messages</span><span class="p">,</span>
                <span class="s1>'tools'</span> <span class="o">=&gt;</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="n">tools</span><span class="o">-&gt;</span><span class="nf">schemas</span><span class="p">(),</span>
            <span class="p">])</span><span class="o">-&gt;</span><span class="k">throw</span><span class="p">()</span><span class="o">-&gt;</span><span class="nf">json</span><span class="p">(</span><span class="s1>'choices.0.message'</span><span class="p">);</span>

        <span class="c1">// Düz metin cevabı — işimizi bitirdik.</span>
        <span class="k">if</span> <span class="p">(</span><span class="k">empty</span><span class="p">(</span><span class="nv">$response</span><span class="p">[</span><span class="s1>'tool_calls'</span><span class="p">]))</span> <span class="p">{</span>
            <span class="k">return</span> <span class="nv">$response</span><span class="p">[</span><span class="s1>'content'</span><span class="p">]</span> <span class="o">??</span> <span class="s1>''</span><span class="p">;</span>
        <span class="p">}</span>

        <span class="nv">$messages</span><span class="p">[]</span> <span class="o">=</span> <span class="nv">$response</span><span class="p">;</span>

        <span class="k">foreach</span> <span class="p">(</span><span class="nv">$response</span><span class="p">[</span><span class="s1>'tool_calls'</span><span class="p">]</span> <span class="k">as</span> <span class="nv">$call</span><span class="p">)</span> <span class="p">{</span>
            <span class="nv>$result</span> <span class="o">=</span> <span class="nv>$this</span><span class="o">-&gt;</span><span class="n">tools</span><span class="o">-&gt;</span><span class="nf">execute</span><span class="p">(</span>
                <span class="nv>$call</span><span class="p">[</span><span class="s1>'function'</span><span class="p">][</span><span class="s1>'name'</span><span class="p">],</span>
                <span class="nb">json_decode</span><span class="p">(</span><span class="nv>$call</span><span class="p">[</span><span class="s1>'function'</span><span class="p">][</span><span class="s1>'arguments'</span><span class="p">],</span> <span class="kc">true</span><span class="p">)</span> <span class="o">??</span> <span class="p">[],</span>
            <span class="p">);</span>

            <span class="nv">$messages</span><span class="p">[]</span> <span class="o">=</span> <span class="p">[</span>
                <span class="s1>'role'</span> <span class="o">=&gt;</span> <span class="s1>'tool'</span><span class="p">,</span>
                <span class="s1>'tool_call_id'</span> <span class="o">=&gt;</span> <span class="nv>$call</span><span class="p">[</span><span class="s1>'id'</span><span class="p">],</span>
                <span class="s1>'content'</span> <span class="o">=&gt;</span> <span class="nv>$result</span><span class="p">,</span>
            <span class="p">];</span>
        <span class="p">}</span>
    <span class="p">}</span>

    <span class="k">return</span> <span class="s1>'Bu adımlarla tamamlayamadım.'</span><span class="p">;</span>
<span class="p">}</span>

}

            <svg xmlns="http://www.w3.org/2000/svg" width="20px" height="20px" viewbox="0 0 24 24" class="highlight-action crayons-icon highlight-action--fullscreen-off"><title>Exit fullscreen mode</title>
            <path d="M18 7h4v2h-6V3h2v4zM8 9H2V7h4V3h2v6zm10 8v4h-2v-6h6v2h-4zM8 15v6H6v-4H2v-2h6z"/>
            </svg>

        </div>
    </div>
</div>

<p><code>MAX_ROUNDS</code> opsiyonel değildir. Olmadan, kafası karışmış bir model araçlar arasında sonsuza kadar ping-pong yapabilir — her tur sizden token alır ve kullanıcınızdan otuz saniye bekletir. Beş tur, teslim ettiğim her meşru akışı kapsar; daha derin olan her şey bir tasarım kokusudur.</p>

<p>Kayıt defterinin <code>execute()</code> kısmı burasıdır; burada doğrulama yaparsınız:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="k">public</span> <span class="k">function</span> <span class="n">execute</span><span class="p">(</span><span class="kt">string</span> <span class="nv>$name</span><span class="p">,</span> <span class="kt">array</span> <span class="nv>$args</span><span class="p">):</span> <span class="kt">string</span>

{
<span class=”nv>$tool = <span class=”nv>$this->map[<span class=”nv>$name] ?? null;

<span class="k">if</span> <span class="p">(</span><span class="o">!</span> <span class="nv>$tool</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">return</span> <span class="nb">json_encode</span><span class="p">([</span><span class="s1>'error'</span> <span class="o">=&gt;</span> <span class="s2>'Bilinmeyen araç: </span><span class="si>{</span><span class="nv>$name</span><span class="si>}</span><span class="s2>'</span><span class="p">]);</span>
<span class="p">}</span>

<span class="k">try</span> <span class="p">{</span>
    <span class="k">return</span> <span class="nv>$tool</span><span class="o">-&gt;</span><span class="nf">handle</span><span class="p">(</span><span class="nv>$args</span><span class="p">);</span>
<span class="p">}</span> <span class="k">catch</span> <span class="p">(</span><span class="nc">Throwable</span> <span class="nv>$e</span><span class="p">)</span> <span class="p">{</span>
    <span class="nf">report</span><span class="p">(</span><span class="nv>$e</span><span class="p">);</span>

    <span class="k">return</span> <span class="nb">json_encode</span><span class="p">([</span><span class="s1>'error'</span> <span class="o">=&gt;</span> <span class="s1>'Araç başarısız oldu. Lütfen tekrar deneyin.'</span><span class="p">]);</span>
<span class="p">}</span>

}

            <svg xmlns="http://www.w3.org/2000/svg" width="20px" height="20px" viewbox="0 0 24 24" class="highlight-action crayons-icon highlight-action--fullscreen-off"><title>Exit fullscreen mode</title>
            <path d="M18 7h4v2h-6V3h2v4zM8 9H2V7h4V3h2v6zm10 8v4h-2v-6h6v2h-4zM8 15v6H6v-4H2v-2h6z"/>
            </svg>

        </div>
    </div>
</div>

<p>Hataları modelin bir sonucu olarak geri döndürün, atmak yerine. Modeller "bu çalışmadı" durumunu zarif bir şekilde yönetir — sabit argümanlarla tekrar dener veya kullanıcıya bildirir. Ancak bir işlenmemiş istisna tüm konuşmayı keser.</p>

<h2>
    <a name="what-it-costs" href="#what-it-costs"></a>
    Maliyeti
</h2>

<p>Her tur bir API çağrısıdır ve tüm konuşmayı yanı sıra araç şemalarını taşır. Beş kayıtlı araçla üç tur bir ajan dönüşü, düz bir sohbet yanıtının 3–5 katı token tüketmektedir. Anında kendini amorti eden iki azaltma: yalnızca mevcut bağlama ilgili araçları kaydedin (bir destek ajanı, yönetici raporlama araçlarına ihtiyaç duymaz) ve açıklamaları kısa tutun — model her turda her şemayı okur. GPT-4.1-mini'de, üretim sipariş destek ajanım çözülen her konuşma için ortalama bir sentin altındadır. Yerine geçen mühendislik süresi ise dakikada daha fazla maliyetliydi.</p>

<h2>
    <a name="production-checklist" href="#production-checklist"></a>
    Üretim kontrol listesi
</h2>

<ul>
    <li>
        <strong>Her araçta yetkilendirme.</strong> Sorguları, doğrulanmış kullanıcı ile sınırlayın. Model, klavyeye sahip güvensiz bir arayıcıdır.</li>
    <li>
        <strong>Döngüyü sınırlandırın.</strong> <code>MAX_ROUNDS</code>, istek zaman aşımı ve uç noktada kullanıcı başına hız sınırı belirleyin.</li>
    <li>
        <strong>Argümanları doğrulayın.</strong> Modelin argümanlarını savunmacı bir şekilde <code>json_decode</code> yapın; eksik anahtarlar ve yanlış türler rutin, olağanüstü değil.</li>
    <li>
        <strong>Her araç çağrısını kaydedin.</strong> İsim, argümanlar, süre, sonuç boyutu. Ajan tuhaf bir şey yaptığında — ve yapacaktır — bu kayıt, ne olduğunu ve nedenini bulmanızı sağlar.</li>
    <li>
        <strong>Hataları veri olarak geri döndürün.</strong> Araç hataları araç sonuçları haline gelir; model kurtulur. İstisnalar 500'lere dönüşür; kullanıcı çıkar.</li>
    <li>
        <strong>Araçları denetleyin.</strong> Her <code>handle()</code> basit bir PHP'dir — doğrudan birim testi yapın, ardından döngü için bir entegrasyon testi ile <code>Http::fake()</code> kullanın.</li>
</ul>

<h2>
    <a name="where-this-goes-next" href="#where-this-goes-next"></a>
    Sonraki aşamalar
</h2>

<p>Yukarıdaki ajan senkron çalışıyor — sorgular için uygun, yavaş olan her şey için yanlış. Bir araç otuz saniye sürerse veya kullanıcı milyonlarca satırlık bir rapor isterse, döngüyü ilerleme güncellemeleri, yeniden denemeler ve bir bütçe ile birlikte kuyruklanmış bir işte çalıştırmanız gerekir. Bu, bu dizideki bir sonraki yazı: <strong>Laravel'de Kuyruk Tabanlı AI İş Akışları — İşler, Yeniden Denemeler ve Maliyet Kontrolü</strong>.</p>

<p><em>Beni Aditya Kumar olarak tanıyın (<a href="https://github.com/adityakdevin" target="_blank" rel="noopener noreferrer">adityakdevin</a>) — AI destekli web ürünleri geliştiren bir Tekno Lider & tam yığın geliştirici. Daha fazla bilgi için <a href="https://adityadev.in" target="_blank" rel="noopener noreferrer">adityadev.in</a> adresini ziyaret edin.</em></p>

Kaynak: Orijinal Makale