Laravel AI SDK: Üretimde Kullanılmaya Değer 3 Çoklu Ajan Modeli (ve Atlanması Gereken 2 Model)

Kaynağını bulmak için hafiz.dev adresini ziyaret edin.

Birçok Laravel geliştiricisi yapay zeka özellikleri geliştirirken benzer hatalar yapıyor. Çok ajanlı kalıplar hakkında yazıları okuyup heyecanlanıyorlar ve ilk özelliklerinde bir orkestratör-çalışan sistemi kurmaya çalışıyorlar. Bir hafta sonra dinamik planlama mantığıyla boğuşuyor, API maliyetleri tahmin edilemez hale geliyor ve özellik hala yayınlanmıyor.

Laravel AI SDK, ajanları kurmayı o kadar kolay hale getiriyor ki, aşırı mühendislik yapma isteği uyandırıyor. Bu SDK’nın bir eleştirisi değil; ancak dikkat etmeniz gereken bir tuzak.

Anthropic’in orijinal araştırması beş çok ajanlı kalıbı tanımlıyor. Resmi Laravel blogu, Mart 13’te tüm beşini temiz kod örnekleri ile ele aldı. Ama buradaki eksik olan kısım, hangi kalıpların gerçekten ilk olarak kullanılacağını ve hangilerinin standart bir SaaS bağlamında size maliyet anlamında zorluk çıkaracağını belirtmemesidir.

İşte bu yazı burada devreye giriyor.

Burada, tüm kod örnekleri, php artisan make:agent ile üretilmiş uygun Ajan sınıflarını kullanıyor, çoğu öğreticide göreceğiniz agent() yardımcı kısayolunu kullanmıyor. Yardımcı, prototip için harika. Ama üretimde, Ajan sınıflarına ihtiyacınız var. SDK’nın yerleşik sahte araçlarıyla test edilebilirler, talimatlar tek bir yerde yer alır ve bir istem üretimde kırıldığında nerede bulacağınızı bilirsiniz.

Çok Ajanlı Kalıplar Nedir?

Tek bir ajan, bir sistem istemi ile yapılan tek bir yapay zeka çağrısıdır. Bir istek gönderirsiniz, bir yanıt alırsınız. Basit. Çok ajanlı kalıplar, karmaşık görevleri odaklanmış adımlara bölmek için birden fazla yapay zeka çağrısını zincirleme, yönlendirme veya çalıştırmanın yapılandırılmış yollarıdır.

Anthropic’in tanımladığı beş kalıp: istem zincirleme, yönlendirme, paralelleştirme, orkestratör-çalışan ve değerlendirici-optimizatör. Her biri farklı bir sorunu çözer. Bunlardan üçünü günümüzün çoğu Laravel SaaS uygulaması için pratik buluyoruz. İkisi ise oldukça maliyetli ve çok özel bir kullanım durumu olmadıkça hata ayıklamak zor.

Öncelikle gönderilmesi gereken üç kalıpla başlayalım.

Kalıp 1: İstem Zincirleme

Bu, bir montaj hattıdır. Ajan A adım 1’i yapar ve çıktısını Ajan B’ye iletir, B adım 2’yi yapar ve bunu Ajan C’ye aktarır. Her ajanın bir görevi vardır ve onu iyi yapar.

Laravel’ın yerleşik Pipeline bu durumu doğal bir şekilde yönetir. Her adım, kendine ait bir Ajan sınıfını sarar ve yükü zenginleştirerek bir sonraki adımda iletir.

Gerçek bir dünya örneği verelim: Bir CRM için bir müşteri bilgisi zenginleştirme boru hattı. Bir satıcı bir şirket adı ekler ve üç ajan sırasıyla çalışarak gönderilecek olan bir ileti için hazır bir e-posta oluşturur.

php artisan make:agent LeadResearcher
php artisan make:agent LeadScorer
php artisan make:agent OutreachDrafter

Her Ajan sınıfı odaklanmış talimatlar tanımlar:

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;

class LeadResearcher implements Agent
{
    use Promptable;

    public function instructions(): string
    {
        return 'Sen bir B2B müşteri araştırmacısısın. Bir şirket adı verdiklerinde, ne yaptıklarını, muhtemel teknoloji yığınlarını ve büyüme aşamalarını içeren 3 cümlelik kısa bir rapor yaz. Kısa ve gerçekçi ol.';
    }
}

Pipelin’in adımları her ajanı sarar ve yükü zenginleştirerek iletir:

namespace App\Ai\Pipeline;

use App\Ai\Agents\LeadResearcher;
use Closure;

class ResearchStep
{
    public function handle(array $payload, Closure $next): array
    {
        $brief = (string) (new LeadResearcher)->prompt($payload['company']);

        return $next([...$payload, 'research' => $brief]);
    }
}

Bir denetleyicide veya işte bağlayın:

use Illuminate\Support\Facades\Pipeline;

$result = Pipeline::send(['company' => 'Acme Corp'])
    ->through([
        ResearchStep::class,
        ScoringStep::class,
        OutreachStep::class,
    ])
    ->thenReturn();

Bu kadar. Üç ajan, üç odaklanmış iş, bir temiz sonuç. Her adımı bağımsız olarak test edebilmeniz, üretim ortamında bir şeyler bozulduğunda gerçekten değerli. Talimatlar kendi başlarına sınıflarda yaşar, dolayısıyla araştırmacı istemini güncellerken skorer veya taslak hazırlayıcıyı etkilemezsiniz.

Zincirleme, karmaşıklıkla iyi bir şekilde ölçeklenir. Skorlamadan sonra bir “ton denetimi” adımını eklemeye mı ihtiyacınız var? Bir boru hattı sınıfı ekleyin. İade eden müşteriler için puanlama adımını atlamak mı istiyorsunuz? O adımda bir koşul ekleyin. Yapı değişimleri temiz bir şekilde absorbe eder, bu da tek bir 800 kelimelik sistem isteminin beş şeyi aynı anda yapmaya çalıştığına kıyasla çok daha mantıklıdır.

Zincirlemeyi kullanın: görev, her adımın bir öncekine bağlı olduğu belirli bir sırayı içeriyorsa. Taslak, doğrula, rafine et. Çıkart, sınıflandır, biçimlendir. Araştır, puanla, yaz.

Kalıp 2: Yönlendirme

Yönlendirme, önce girdiyi sınıflandırmak ve ardından doğru uzmana göndermek anlamına gelir. Bir ajan isteği okur ve hangisinin ele alacağını belirler. Farklı giriş türleri, farklı talimatlar alır. Farklı karmaşıklık seviyeleri, farklı modeller ve maliyetlerle başa çıkabilir.

Burası, destek botları ve girdi çeşitliliği olan her şey için en mantıklı ekonomik modeldir.

php artisan make:agent TicketClassifier
php artisan make:agent BillingAgent
php artisan make:agent TechnicalAgent
php artisan make:agent GeneralSupportAgent

Sınıflandırıcı, yalnızca tek bir kategori kelimesi döndürür, başka bir şey değil:

class TicketClassifier implements Agent
{
    use Promptable;

    public function instructions(): string
    {
        return 'Destek bileti, yalnızca: faturalama, teknik, genel olarak birine kesin olarak sınıflandırın. Sadece kategori kelimesiyle yanıt verin, başka bir şey yok.';
    }
}

Yönlendirici, kategoriyi okuyarak ve doğru uzmana yönlendirerek işlemi gerçekleştirir:

namespace App\Support;

use App\Ai\Agents\BillingAgent;
use App\Ai\Agents\GeneralSupportAgent;
use App\Ai\Agents\TechnicalAgent;
use App\Ai\Agents\TicketClassifier;

class SupportRouter
{
    public function route(string $ticket): string
    {
        $category = (string) (new TicketClassifier)->prompt($ticket);

        return match (trim(strtolower($category))) {
            'billing'   => (string) (new BillingAgent)->prompt($ticket),
            'technical' => (string) (new TechnicalAgent)->prompt($ticket),
            default     => (string) (new GeneralSupportAgent)->prompt($ticket),
        };
    }
}

Bu durumu ileriye taşıyabilir, prompt() çağrısında her ajan için farklı sağlayıcılar belirleyebilirsiniz. Basit faturalama soruları daha ucuz ve hızlı bir modele yönlendirilebilir. Karmaşık teknik sorunlar ise daha yetenekli bir modele yönlendirilir. Sınıflandırıcı çağı, gerçek hacmi yönettiğinizde hızla kendisini amorti eder.

Örneğin, teknik ajan için bunu şöyle görebiliriz:

use Laravel\Ai\Enums\Lab;

// Teknik Ajan'ın çağrısında, veya prompt() ile geçersiz kılma üzerinden:
(string) (new TechnicalAgent)->prompt(
    $ticket,
    provider: Lab::Anthropic,
    model: 'claude-opus-4-5-20251101'
);

// Faturalama, config/ai.php'den varsayılan daha ucuz modeli kullanır
(string) (new BillingAgent)->prompt($ticket);

Bir faturalama bileti için toplam maliyet büyük ölçüde düşmekteyken, teknik biletler hala tam modeli alır. Bu, üretimde akıllıca bir maliyet profili oluşturur, özellikle de ölçeklendiğinde.

Yönlendirme akışının görünümü şu şekildedir:

Diyagramı görmek için hafiz.dev’deki etkileşimli diyagrama göz atın

Yönlendirmeyi kullanın: girdiler tür veya karmaşıklık bakımından önemli ölçüde farklılık gösteriyorsa ve tek bir istem, tüm durumları temiz bir şekilde işlemeyi başaramıyorsa.

Kalıp 3: Paralelleştirme

Birden fazla ajanın aynı girdi üzerine bağımsız olarak bakması gerektiğinde, onları tek tek çalıştırmanın bir anlamı yoktur. Laravel’ın Concurrency::run() özelliği, tümünü aynı anda başlatmanızı ve sonuçları toplamanızı sağlar.

Zaman farkı gerçektir. Paralel çalışan üç ajan, yaklaşık olarak bir ajan süresince geçen zaman alır. Sırasıyla çalışan üç ajan, üç kat sürede tamamlanır.

Burdaki bir belge analizi örneği: Bir sözleşmeniz var ve yasal, finansal ve risk değerlendirmelerini aynı anda almak istiyorsunuz:

php artisan make:agent LegalReviewer
php artisan make:agent FinancialAnalyzer
php artisan make:agent RiskAssessor
php artisan make:agent ContractSummaryAgent

Üç uzmanı paralel olarak çalıştırın, sonra çıktıları bir özet ajansına aktarın:

use App\Ai\Agents\ContractSummaryAgent;
use App\Ai\Agents\FinancialAnalyzer;
use App\Ai\Agents\LegalReviewer;
use App\Ai\Agents\RiskAssessor;
use Illuminate\Support\Facades\Concurrency;

[$legal, $financial, $risk] = Concurrency::run([
    fn () => (string) (new LegalReviewer)->prompt($contract),
    fn () => (string) (new FinancialAnalyzer)->prompt($contract),
    fn () => (string) (new RiskAssessor)->prompt($contract),
]);

$summary = (string) (new ContractSummaryAgent)->prompt(
    "Hukuki inceleme:\n{$legal}\n\nFinansal analiz:\n{$financial}\n\nRisk değerlendirmesi:\n{$risk}"
);

ContractSummaryAgent ancak üçü de işini tamamladıktan sonra çalışır ve tam resmi görür. Bu kalıp, belgeleri asenkron olarak işlerken kuyruklanmış işler ile doğal bir şekilde eşleşir. Eğer Laravel kuyruklarını ölçekli bir seviyede yönetme konusunda henüz kendinize güvenmiyorsanız, büyük iş hacimlerini işleme üzerine olan bu çözümleme, asenkron ajan boru hatları ile ilgili temeller hakkında bilgi sahibi olmanız için gerekli.

Not: Concurrency::run() Laravel 11 ile birlikte geldi. Eğer hala Laravel 10 üzerindeyseniz, paralellik işleme havuzları veya kuyruklu işler aracılığıyla gerçekleştirilmelidir.

Üretimde dikkat edilmesi gereken bir nokta: paralelde çalışan ajanalardan biri başarısız olursa, Concurrency::run() bir hata fırlatır. Bunu bir try/catch bloğuna sarın ve tüm isteğin başarısız olmasını mı yoksa başarısız olan ajanın senkron olarak çalıştırılmasını mı istediğinizi belirleyin. Belgelerin analizinde, nazik bir şekilde geri dönmek genellikle, bir uzmanın zaman aşımına uğraması nedeniyle tüm işlemin başarısız olmasından daha iyidir.

Paralelleştirmeyi kullanın: Birden fazla bağımsız uzman aynı girdi üzerine bakması gerektiğinde veya birbirlerinin sonuçlarına bağımlı olmayan birkaç ayrı analiz gerektiğinde kullanılır.

Şu An Atlanması Gereken İki Kalıp

Orkestratör-Çalışanlar

Bu kalıp dikkat çekici görünüyor. Yönetici bir ajan, karmaşık bir görevi alır, alt görevlere dinamik olarak böler, çalışan ajanalara devreder ve sonucu bir araya getirir.

Ancak pratikte sorun şudur: orkestratör, bir iç ajansal döngü çalıştırır. Gereken adımları belirlemek, çalışan araçları çağırmak ve ne zaman bittiğini çözmek gerekir. Bu, token kullanımını tahmin etmenizi, ne zaman bir şeyler bozulduğunu kolayca takip etmenizi ve testi gerçekten zorlaştırır.

Çoğu SaaS özelliği için, gereken adımlar aslında çalışma zamanında bilinmiyor gibi görünür. Gerçekte, çoğu zaman dinamik bir orkestratörü iyi yapılandırılmış bir zincirleme boru hattıyla değiştirmek mümkün olur ve bu da daha ucuz, daha hızlı ve hata ayıklaması daha kolay hale gelir. Kendi yazdığınız üç adımlı bir boru hattı, umduğunuz modelin doğru bir şekilde çalıştığını umduğunuz bir planlama döngüsünden daha kolaydır ve ondan daha verimlidir.

Orkestratör kalıbının yeri, görev yapısının gerçekten değişken olduğu durumlarda vardır. Özellik isteğine bağlı olarak beş veya on beş dosya oluşturması gereken bir kod oluşturma ajansını düşünün. Sorgulanacak kaynak sayısını belirlemesi gereken bir araştırma ajansı. Göreviniz öngörülebilir bir yapıya sahipse, zincirlemeyi tercih edin. Orkestrasyonun gerçekten gerekip gerekmediğini anlayacaksınız.

Değerlendirici-Optimizatör

Bu kalıp döngüseldir: çıktı üret, onu değerlendir, yeterli değilse yeniden yaz, N kez tekrarla. Kalite için harika gibi görünse de maliyet açısından acı vericidir.

Gerçekten “3 iyileştirme yinelemesi” nin üretimde ne anlama geldiğini düşünün. Bu, kullanıcı eylemi başına dört API çağrısına kadar çıkabilir: bir yazma, bir değerlendirme, bir yeniden yazma ve bir son değerlendirme. Eğer gerçek hacimde içerik üretiyorsanız, bu çarpan hızla büyür. Günde 1.000 isteği işleyen bir özellik, tek bir ajanın çağrısı için $0.01 olduğunda, $0.04 olur ve üç yineleme döngüsü devam ettirirken. Çok da az gibi görünmeyebilir, ama bir ay geçtikten sonra büyük rakamlara ulaşır.

Bir de gecikme sorunu var. Her bir yineleme, bir yapay zeka sağlayıcısına tam bir gidiş-dönüş ekler. Bunu bir web isteğinde senkron olarak yapıyorsanız, üçüncü yineleme ile 10-20 saniye bekleme süresiyle karşılaşabilirsiniz. Bu, yayınlamak istemeyeceğiniz bir kullanıcı deneyimidir.

Değerlendirici kalıbı gerçekte, çıktı kalitesi iş açısından kritik olduğunda ve insan bir sonucu gözden geçirecekse yerini alır. Hukuki belge taslağı, tıbbi içerik, kötü bir çıktının gerçek sonuçları olan her şey. Çoğu SaaS AI özelliği için, açık bir çıktı şemasına sahip iyi bir şekilde yönlendirilmiş bir ajanın tek başına işini görmesi maliyetin onda biri ile yeterlidir.

Eğer bir RAG destek sistemi inşa ediyorsanız ve daha iyi yanıt kalitesi istiyorsanız, araçlar ve bellek üzerine olan 2. parti öğretici, değerlendiriciyi ele almadan önce bir ajandan daha fazlasını nasıl alabileceğinizi anlatır.

Basit Bir Karar Çerçevesi

Bir kalıp seçmeden önce, iki soru sorulmalıdır: görev öngörülebilir bir yapıya mı sahip ve adımlar birbirine bağlı mı?

Önce, tek bir iyi yönlendirilmiş Ajan sınıfı ile başlayın. Eğer bu ajan işi temiz bir şekilde yapamazsa, önce zincirlemeyi tercih edin. Sonrasında durum uygun olduğunda yönlendirme ya da paralelleştirmeyi ekleyin. Orkestratör ve değerlendirici, gerçekten ihtiyaç duyduğunuzda devreye girer ve ne zaman gerektiğini bilirsiniz.

SSS

Bir kalıp mı seçmem gerekiyor, yoksa bunları karıştırabilir miyim?

İstediğiniz gibi karıştırabilirsiniz. Bir biletleri uzman ajanlara yönlendiren bir yönlendirme kalıbı, karmaşık çok adımlı çözümleme için teknik ajan içinde zincirlemeyi kullanabilir. Kalıplar bileşken. Sadece işe yarayan en basit şeyi başlatın ve üzerine ekleyin.

Zincirleme ile paralelleştirmenin maliyet farkı nedir?

Aynı sayıda API çağrısında, farklı duvar saati zamanı. Zincirleme bunları sırayla çalıştırır, böylece toplam zaman tüm ajan yanıt sürelerinin toplamıdır. Paralelleştirme hepsini eşzamanlı çalıştırdığı için toplam süre yaklaşık olarak en yavaş tek ajandır. Maliyetler aynıdır. Adımlar birbirine bağlı olup olmadığını belirleyerek seçim yapın, maliyet üzerinde değil.

Bu Laravel 11, 12 ve 13 ile çalışır mı?

Evet. Laravel AI SDK hepsini destekler. Concurrency::run() paralelleştirme, Laravel 11 ya da daha yenisini gerektirir. Laravel 10 için paralel çalıştırma için farklı bir yaklaşım gereklidir. Zincirleme ve yönlendirme için Ajan sınıfı kalıpları herhangi bir desteklenen versiyonda çalışır.

Çok sayıda ajan iş akışını nasıl test edebilirim?

AI SDK, yerleşik sahte araçlar içerir. Her Ajan sınıfını testlerde taklit edebilir ve doğru istem ile doğru sırada çağrıldığını doğrulayabilirsiniz. 30 dakikalık SDK öğreticisi, çok aşamalı boru hatları oluşturmadan önce test araçları üzerine kapsamlı bilgi sunar.

Ne zaman php artisan make:agent kullanmalıyım, ne zaman agent() yardımcı fonksiyonunu?

agent() yardımcı fonksiyonu tek seferlik çağrılar ve prototipler için iyidir. Üretim çok ajanlı iş akışları için, düzgün Ajan sınıflarını kullanın. Test edilebilir, yeniden kullanılabilirler ve talimatlar tek bir yerde yaşar. Sistem istemini güncellemeye ihtiyaç duyduğunuzda nereye bakacağınızı bilirsiniz.

Sonuç

Çok ajanlı kalıplar, Laravel ile yapay zeka ile yapabileceklerinizde gerçek bir sıçrama sağlar. Fakat başlamak için en iyi kalıp genellikle, gerçek problemi çözen en basit olandır. Önce tek bir ajanı çalışır hale getirin. Sonra, zincirlemeyi yapı eklemek için kullanın, yönlendirmeyi çeşitlendirmek için ve bekleme sürelerini kesmek için paralelleştirmeyi kullanın. Orkestratör ve değerlendiriciyi, görev gerçekten ihtiyaç duyduğunda saklayın.

Laravel AI SDK, tüm bunları normal Laravel kodu yazmak gibi hissettiriyor. Pipeline zaten orada. Eş zamanlılık zaten mevcut. Sadece ajanları ona yönlendirmekte. Ve her Ajan sınıfı, iyi tanımlanmış bir arayüze sahip düz bir PHP sınıfı olduğundan, testleriniz temiz kalır ve istemler zaman içinde gelişirken sürdürülebilir olur.

Bugün atladığınız kalıplar sonsuza dek gitmedi. Üretimde zincirlemeyi gönderdiğinizde ve gerçek API maliyetleri ve gecikme profili hakkında daha net bir anlayışa sahip olduğunuzda, orkestratörü veya değerlendiricinin ne kadar değerli olduğunu daha iyi anlayabileceksiniz. Çoğu durumda, daha basit kalıpların sizi beklediğinizden daha ileri taşıdığını göreceksiniz.

Bir müşteri projesi veya bir SaaS için çok ajanlı iş akışları oluşturuyorsanız, mimariye ikinci bir göz atmak için iletişime geçin.