Laravel AI SDK Derin Analiz: AI’yi Temel Mimariye Entegre Eden İlk PHP Frameworkü – DEV Community

Son iki yılda yapay zeka agent’ları oluşturma konusunda neredeyse tüm kaynaklar Python’a yöneliyor. Python geliştiricileri LangChain, LangGraph ve CrewAI gibi araçlarla AI uygulamalarında hızlı bir şekilde ilerlerken, PHP geliştiricileri ya Python öğrenmek zorunda kalıyor ya da bir Python mikroservisi kurup HTTP çağrıları ile çalışmak durumunda kalıyor.

2026 yılı başında Laravel resmi olarak Laravel AI SDK (code>laravel/ai) paketini duyurdu. Bu, birinci taraf (first-party) paket olup durumu tamamen değiştirme potansiyeline sahip. Basit bir API kapsaması değil, Laravel’in temel mimarisine derinlemesine entegre edilmiş bir agent framework’üdür.

Neden Laravel AI SDK Bir Paradigma Değişimidir

Laravel AI SDK’nın temel tasarım felsefesi: Agent, PHP Sınıfıdır. Her agent, sistem direktifleri, diyalog geçmişi, araç seti ve çıktı şemasını kapsayan bağımsız bir PHP sınıfıdır. Bu yapı, Laravel’in servis konteyneri, Eloquent ORM ve kuyruk sistemleri ile kesintisiz bir işbirliği sağlar.

SDK, 14 farklı AI sağlayıcısını destekler: OpenAI, Anthropic, Google Gemini, Groq, Mistral, DeepSeek, xAI, Ollama, Azure OpenAI, Cohere, OpenRouter, Jina, VoyageAI ve ElevenLabs. Sağlayıcı değiştirmek için yalnızca bir parametre ya da .env değişkeni değiştirmeniz yeterlidir.

Fonksiyonel kapsamı “sohbet arayüzü” ile çok daha fazlasını kapsar:

Kurulum ve Konfigürasyon

Kurulum iki adımda yapılır:

composer require laravel/ai
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan migrate

Migrasyon ile agent_conversations ve agent_conversation_messages adında iki tablo oluşturulur; bu tablolar diyalog geçmişini kalıcı hale getirir. API Anahtarı için .env dosyasında ayar yapılmalıdır:

OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
GEMINI_API_KEY=xxx

Uygulama 1: Tam Bir Müşteri Hizmetleri Agent’ı Oluşturma

Artisan komutuyla Agent iskeleti oluşturulur:

php artisan make:agent SupportAgent --structured

Oluşturulan sınıf, app/Ai/Agents/SupportAgent.php konumunda yer alır. Aşağıda, araç çağrıları ve yapılandırılmış çıktıları içeren bir tam müşteri hizmetleri agent’ı uygulaması yer almaktadır:

 $schema->string()->required(),
            'ticket_closed' => $schema->boolean()->required(),
            'refund_amount' => $schema->number()->minimum(0)->nullable(),
        ];
    }
}

Çağırma yöntemi son derece basittir:

// Controller içinde
$response = SupportAgent::make(user: $user)
    ->prompt($request->input('message'));

return response()->json([
    'resolution' => $response['resolution'],
    'ticket_closed' => $response['ticket_closed'],
]);

RemembersConversations trait’i diyalog kalıcılığını otomatik olarak yönetir. Yeni bir diyalog başlatmak için:

$response = SupportAgent::make(user: $user)
    ->forUser($user)
    ->prompt('Merhaba, aboneliğimi görmek istiyorum.');
$conversationId = $response->conversationId;

Mevcut bir diyalogu sürdürmek için:

$response = SupportAgent::make(user: $user)
    ->continue($conversationId, as: $user)
    ->prompt('Aboneliğimi iptal etmek istiyorum.');

Uygulama 2: Agent’ın Veritabanını Kontrol Etmesini Sağlayacak Araçlar

Araçlar, agent’ın “elleri ve ayaklarıdır”. Her araç, handle metodunu ve JSON Şema tanımını içeren bir PHP sınıfıdır:

 [
                'type' => 'integer',
                'description' => 'Kullanıcı ID',
            ],
        ];
    }

    public function handle(int $user_id): string
    {
        $subscription = Subscription::where('user_id', $user_id)->first();

        if (!$subscription) {
            return json_encode(['error' => 'Abonelik kaydı bulunamadı']);
        }

        return json_encode([
            'plan' => $subscription->plan,
            'status' => $subscription->status,
            'expires_at' => $subscription->expires_at->toIso8601String(),
            'amount' => $subscription->amount,
        ]);
    }
}

LLM, kullanıcı girdisine göre bu aracın çağrılıp çağrılmayacağına otomatik olarak karar verir, SDK ise sonucu alır ve modele döndürür. Geliştiricilerin herhangi bir planlama mantığı yazmasına gerek kalmaz.

Uygulama 3: Vektör Arama ile RAG’yi Gerçekleştirme

Laravel AI SDK, vektör gömme ve benzerlik aramasını yerel olarak entegre etti, pgvector uzantısı ile Eloquent modeller üzerinde doğrudan anlaması için sorgu yapabilirsiniz:

use Laravel\Ai\Concerns\HasEmbeddings;

class Document extends Model
{
    use HasEmbeddings;

    protected $embeddings = [
        'embedding' => 'content',
    ];
}

// Anlamadığınız sorgu
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', 'İade politikası', minSimilarity: 0.7)
    ->limit(10)
    ->get();

Bu, geleneksel anahtar kelime aramalarına göre çok daha güçlüdür. Kullanıcı “nasıl iade edebilirim?” diye sorduğunda sistem, “Abonelik iptali ve ücret iade talimatları” başlıklı bir belge ile eşleşebilir, her iki içerik arasında ortak anahtar kelime olmaksızın.

Üretim Seviyesi Özellikler

Akışkan Yanıt: Agent, yanıtları SSE akışıyla ön uca gönderip Vercel AI Data Protocol ile uyumludur:

return SupportAgent::make(user: $user)
    ->stream($request->input('message'))
    ->usingVercelDataProtocol();

Kuyruk Asenkron Yürütme: Zaman alan görevler HTTP isteklerini engellemez:

SupportAgent::make(user: $user)
    ->queue($message)
    ->then(fn ($response) => $user->notify(new AgentDone($response)));

Sağlayıcı Arıza Tespiti: Ana sağlayıcı kullanılamadığında otomatik geçiş yapar:

$response = SupportAgent::make()->prompt(
    $message,
    provider: [Lab::Anthropic, Lab::OpenAI]
);

Test Desteği: SDK içinde tam bir Fake katmanı bulunmaktadır:

SupportAgent::fake(['Aboneliğiniz başarıyla iptal edildi.']);
SupportAgent::assertPrompted('Aboneliğimi iptal et.');

Çoklu Agent İş Akışı

SDK, Anthropic tarafından yayınlanan Agent tasarım araştırmasına dayalı olarak 5 farklı çoklu agent orkestrasyon modunu yerleşik olarak sunmaktadır:

1. İstem Zinciri: Bir agent’in çıktısı, bir sonraki agent’ın girişi olarak kullanılır.
2. Yönlendirme: Sınıflandırma agent’ı, istekleri uzman agent’lara yönlendirir.
3. Paralelize: Birden fazla agent aynı girişi paralel işleyebilir.
4. Orkestratör-Çalışanlar: Agent’ları görevi dinamik olarak dağıtır.
5. Değerlendirici-Optimize Edici: Üretme-değerlendirme-geliştirme döngüsü.

Son Söz

Laravel AI SDK, yalnızca “PHP ile AI yapabiliriz” demekle kalmaz. AI yeteneklerini Laravel’in mimari felsefesine birinci sınıf bir vatandaş olarak entegre eder — zarif arayüz, bağımlılık enjeksiyonu, kuyruk, olay, test; her şey tanıdık olan Laravel ekosisteminde bulunur.

AI fonksiyonları için daha önce Python mikro hizmetlerini sürdürmek zorunda kalan ekipler için, Laravel AI SDK genellikle o ekstra hizmete olan bağımlılığı ortadan kaldırır. Tek bir dil, tek bir dağıtım, tek bir kod tabanı.

📌 Daha fazla teknik öğretici için, her hafta güncellediğim blogumu takip edin!