Laravel AI SDK ile ReAct Chat Ajansı Oluşturma

Bu rehber, Laravel AI SDK (laravel/ai) üzerinde bir akış, sohbet asistanı oluşturmayı adım adım açıklamaktadır.

1. ReAct Deseni Nedir?

Basit bir dil modeli, “tek seferde” metin tahminidir: ona bir soru verirsiniz, mevcut bilgileriyle size bir yanıt verir. Ancak modelin bilmediği bir şeye dayanan sorular bu yapıyı bozar.

ReAct (Reasoning + Acting) bu durumu, modelin tek seferde cevap vermek yerine bir döngüde çalışmasına olanak tanıyarak düzeltir:

• Reason: Model, sorunun neye ihtiyaç duyduğunu düşünür.
• Act: Dış bilgiye ihtiyaç duyuyorsa, tahmin yerine bir araca (sağladığınız bir işlev) çağrı yapar.
• Observe: Araç çalışır ve bir sonucunu döndürür; bu sonuç modelin yeni bir gözlem olarak geri beslenir.
• Repeat: Model, gözlemi değerlendirir ve ya başka bir aracı çağırır ya da nihai yanıtı üretir.

Örnek: “Şu anda Tokyo’da saat kaç?”

Kullanıcı: Şu anda Tokyo’da saat kaç?
Reason: Gerçekten mevcut saat hakkında bir bilgim yok. Bir saat aracını çağırmalıyım.
Act: current_datetime(timezone: “Asia/Tokyo”)
Observe: Cumartesi, 6 Haziran 2026’da Tokyo’da saat 23:42 (Asia/Tokyo)
Reason: Şimdi gerçek yerel saati öğrendim. Cevap verebilirim.
Cevap: Şu anda Tokyo’da 6 Haziran 2026 Cumartesi günü saat 23:42.

2. Laravel AI SDK Nedir?

Laravel AI SDK (laravel/ai), AI sağlayıcıları (Anthropic, OpenAI, Gemini, Groq, Ollama gibi) ile konuşmak için birleşik, Laravel tadında bir API’dir. Sağlayıcıya özgü HTTP çağrıları yapmak yerine, bir Ajansı PHP sınıfı olarak tanımlıyorsunuz ve SDK geri kalanını hallediyor.

Bilmeleri Gereken Dört Kavram:

• Agent: Bir sistem istemi (instructions()), bir model seçimi ve bir dizi araç içeren bir sınıf. Bu, “istek yaptığınız” şeydir.
• Tool: Modelin çağırmasına izin verilen, Laravel\Ai\Contracts\Tool uygulayan küçük bir sınıf. Her araç, bir isim, bir tanım ve bir parameter schema tanımlar ve işlemi gerçekleştiren handle() yöntemini açığa çıkarır.
• Streaming: Tüm yanıtı beklemek yerine, yanıt oluşturuldukça buna göre yineleyerek, metin parçaları ve araç çağrısı olaylarını gerçek zamanlı olarak alabilirsiniz.
• Conversation memory: SDK, her adımı otomatik olarak veritabanına kalıcı hale getirerek geçmişi yeniden oynatır, böylece ajan bir sonraki mesaj için bağlama sahip olur.

Özellikle, SDK sizin için ReAct döngüsünü çalıştırır. Araçları ve bir adım sınırı tanımlarsınız; SDK ne yapması gerektiğini sormak, seçilen aracı yürütmek, gözlemi geri beslemek ve model bitene kadar döngüyü sürdürmekle ilgilenir.

3. Uygulamanın Uyum Sağlaması

Uygulama, canlı bir sohbet (minimal bir ChatGPT klonu gibi düşünebilirsiniz). Bir Livewire bileşeni, kullanıcının istemini alır, bir ChatAgent’a iletir ve ajanın yanıtını tarayıcıya token şeklinde akıtır.

 
        ┌──────────────┐   prompt    ┌────────────────┐   reason/act   ┌──────────────┐
        │  Livewire UI │ ──────────▶ │   ChatAgent    │ ─────────────▶ │   Provider   │
        │  (Blade +    │             │ (Laravel AI    │ ◀───────────── │ (Claude 4.6) │
        │   Alpine.js) │             │   SDK agent)   │   tool calls   └──────────────┘
        └──────────────┘             └───────┬────────┘
                                           │ executes
                                           ▼
        ┌────────────────────────────────────────────────╕
        │ Tools: Calculator · CurrentDateTime ·         │
        │ WikipediaLookup · WebSearch                     │
        └────────────────────────────────────────────────╯

4. Yapılandırma

Varsayılan sağlayıcı ve kimlik bilgileri ortamınızda bulunur. Bu uygulama Anthropic’i kullanır:

    # .env
    AI_PROVIDER=anthropic
    ANTHROPIC_API_KEY=sk-ant-...
    

config/ai.php bu değerleri okur. Varsayılan sağlayıcı, anthropic’e geri düşer ve Anthropic sürücüsü API anahtarına bağlıdır:

// config/ai.php
'default' => env('AI_PROVIDER', 'anthropic'),

'providers' => [
    // ...
    'anthropic' => [
        'driver' => 'anthropic',
        'key' => env('ANTHROPIC_API_KEY'),
        'url' => env('ANTHROPIC_URL', 'https://api.anthropic.com/v1'),
    ],
    // ...
],
    

5. Ajansı Oluşturma

Tüm ajans, küçük bir sınıftır. Bir kez okuyun, ardından parçalara ayıracağız.

// app/Ai/Agents/ChatAgent.php
use App\Ai\Tools\Calculator;
use App\Ai\Tools\CurrentDateTime;
use App\Ai\Tools\WikipediaLookup;
use Laravel\Ai\Attributes\MaxSteps;
use Laravel\Ai\Attributes\Model;
use Laravel\Ai\Attributes\Provider;
use Laravel\Ai\Attributes\Temperature;
use Laravel\Ai\Concerns\RemembersConversations;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;
use Laravel\Ai\Providers\Tools\WebSearch;
use Stringable;

#[Provider(Lab::Anthropic)]
#[Model('claude-sonnet-4-6')]
#[Temperature(0.7)]
#[MaxSteps(8)]
class ChatAgent implements Agent, Conversational, HasTools
{
    use Promptable, RemembersConversations;

    public function instructions(): Stringable|string
    {
        return 'Lütfen ReAct modelini takip et.';
    }

    public function tools(): iterable
    {
        return [
            new Calculator,
            new CurrentDateTime,
            new WikipediaLookup,
            (new WebSearch)->max(5),
        ];
    }
}
    

6. Araçları Yazma

Bir araç, Laravel\Ai\Contracts\Tool’i uygulayan herhangi bir sınıftır. Sözleşme dört yöntem içerir: name(), description(), schema() ve handle(). Model, adı, tanımı ve şemasını okuyarak aracı çağırıp çağırmamaya karar verir; handle() gerçek işi yapar ve bir gözlem dizesi döndürür.

// app/Ai/Tools/CurrentDateTime.php
use Carbon\CarbonImmutable;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;

class CurrentDateTime implements Tool
{
    public function name(): string
    {
        return 'current_datetime';
    }

    public function description(): Stringable|string
    {
        return 'Mevcut tarihi ve saati alır. İsteğe bağlı olarak IANA zaman dilimi geçirilebilir (örneğin "Asia/Tokyo", "America/New_York").';
    }

    public function handle(Request $request): Stringable|string
    {
        $timezone = $request->string('timezone', 'UTC')->toString();
        $now = CarbonImmutable::now($timezone);
        return $now->format('l, F j, Y \a\t g:i A').' ('.$timezone.')';
    }
}
    

7. Cevabı Tarayıcıya Yayma

Bu sohbet, Livewire tek dosya bileşeninde bulunur. send() yöntemi, ajan ile UI’nin buluştuğu yerdir.

public function send(string $prompt): void
{
    $agent = ChatAgent::make()->forUser($this->user());
    $response = $agent->stream($prompt);
    
    $answer = '';

    foreach ($response as $event) {
        // ...
    }
}
    

8. Konuşmaları Kalıcı Hale Getirme

Kodda herhangi bir kalıcılık kodu yazmadınız — SDK bunu yaptı. Kullanıcı, konuşmaları yönetir ve her kullanıcı için kendine ait konuşmalar oluşturur.

9. Test Etme

Gerçek bir modeli testlerde kullanmak yavaş, maliyetli ve öngörülemez olur. SDK, ajansı verilen bir yanıta değiştirmeye olanak tanır.

it('streams an answer and persists the conversation', function () {
    ChatAgent::fake(['Hello from the agent!']);
    
    // Test code...
});
    

10. Uzatmak: Kendi Araçlarınızı Ekleyin

Ajansa bir yetenek eklemek üç adımdan oluşur: aracınızı oluşturun, ajansın tools() içinde kaydedin ve isteğe bağlı olarak yönergeleri güncelleyin.

Tüm bunlar, SDK’ya iyi tanımlanmış bir ajan ve bir dizi güvenli, dürüst araç sağladığınızda gerçekleşir. ReAct deseni geri kalanını halleder.

Kaynak Kodu

Bu rehberin tam kaynak koduna mevcut GitHub deposunda bulabilirsiniz.

Kaynak: Orijinal Makale