Autokorreksiyonu engelleme: Laravel, Grok ve OpenSpec ile AI ajansları için güvenlik sistemlerinin pratik bir demonstrasyonu

Giriş

Yazılımcılar için, otomatik düzeltme (self-correction) yeteneğine sahip yapay zeka ajanlarının nasıl çalıştığını anlamak önemlidir. Geleneksel koruma yöntemleri genelde ikili (binary) olarak çalışır; bir kural ihlal edildiğinde işlem durdurulur ve kullanıcı müdahalesi gerekir. Ancak bu her zaman en iyi deneyim olmuyor.

Yeni bir yaklaşım olarak “steering” yani yönlendirme yöntemi önerilmektedir. Bu yöntemde, ajan kuralları ihlal ettiğinde yalnızca erişimi engellemek yerine hata düzeltilir ve kullanıcıya bir düzeltme önerisi sunulur.

Amacım bu yaklaşımı kendi günlük kullandığım teknolojilerle bir örnek üzerinden göstermek:

Laravel
Laravel AI SDK
Vue
Docker Compose
MySQL
Grok / xAI
OpenSpec

Önemli bir not: Bu demom, Strands Agents veya Agent Control doğrudan uygulamamaktadır. Ben, makalenin kavramsal gündemini alıp bunu Laravel + Vue + Laravel AI SDK + Grok yığınına aktardım.

Bu çalışma ile amaç, öğrendiklerimi bir koda dönüştürmek ve ana fikir olan şu üç maddeyi göstermekti:

No bloquear por defecto.
Corregir cuando sea seguro.
Bloquear cuando realmente sea necesario.

Problemi Tanımlama

Bir randevu ayarlamak için bir yapay zeka ajanı düşünelim.

Kullanıcı şöyle bir mesaj yazıyor:

Quiero una cita mañana a las 8pm para 3 personas

Ancak işin içinde şu kurallar var:

Horario de atención: 8:00 a.m. a 6:00 p.m.
Máximo de personas por cita: 2
Duración de la cita: 30 minutos
No se pueden agendar días bloqueados
No se pueden duplicar slots ocupados

Geleneksel bir koruma kuralı en azından şöyle cevap veriyordur:

No puedo agendar esa cita.

Bu şekilde tüm akış kesilmiş oluyor.

Daha iyi bir deneyim ise:

No puedo agendar a las 8:00 p.m. ni para 3 personas.
Te puedo ofrecer mañana a las 5:30 p.m. para 2 personas.
¿Deseas confirmar?

İşte asıl burada otomatik düzeltme fikri devreye giriyor.

Yapılanlar

Bir kullanıcı için randevu talebinde bulunan işlevsel bir demo oluşturdum.

Yapay zeka niyetini anlıyor, yapılandırılmış bir payload oluşturuyor ve ardından GuardrailEngine iş kurallarını doğruluyor.

Kullanıcı, yapay zekanın önerisini doğrudan onaylamıyor. Önce bir kontrol katmanından geçiyor.

Ayrıca, kuralları, hizmetleri ve engellenen günleri yapılandıran bir admin arayüzü ekledim.

Kısaca:

Yapay zeka anlıyor.
Guardrail karar veriyor.
Backend çalıştırıyor.
Admin yapılandırıyor.

Demo Mimarisi

Demo aşağıdaki bileşenlerden oluşuyor:

Frontend Cliente
Backend Laravel
Laravel AI SDK
AppointmentIntentAgent
LaravelAiAppointmentAgent
GuardrailEngine
AppointmentController
Frontadmin
MySQL

Bileşenlerin Sorumlulukları

Temel Akış

Usuario escribe una solicitud
        ↓
Frontend envía el mensaje al backend
        ↓
ChatController recibe el mensaje
        ↓
LaravelAiAppointmentAgent invoca AppointmentIntentAgent
        ↓
Laravel AI SDK usa xAI / Grok como provider
        ↓
El agente devuelve un payload estructurado
        ↓
GuardrailEngine evalúa reglas de negocio
        ↓
Si es válido: ALLOW
Si es corregible: STEER
Si no puede continuar: BLOCK
        ↓
El usuario confirma la propuesta
        ↓
Laravel crea la cita en MySQL

Yönetim Akışı

Frontadmin
        ↓
Admin Controllers
        ↓
MySQL
        ↓
Kurallar, hizmetler, engellenen günler ve loglar
        ↓
GuardrailEngine o kuralları runtime'da kullanır

Önemli olan kuralların yalnızca ajan isteminde yaşamaması. Frontadmin üzerinden daha sonra değiştirilebilir ve GuardrailEngine bunları çalışma zamanında kullanır.

Laravel AI SDK ile Uygulama

Başlangıçta xAI / Grok API ile doğrudan bir entegrasyonum vardı.

Sonrasında ihtiyacımı karşılamak için Laravel AI SDK‘ya geçiş yaptım.

SDK’yı yüklemek için şu komutu kullanmalısınız:

composer require laravel/ai

Sonrasında yapılandırma dosyaları, stubs ve göçler yayınlanır:

php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"

Ve göçler çalıştırılır:

php artisan migrate

Bu durumda, bu, ajanslar için kullanılan konuşma tablosunu oluşturdu:

agent_conversations

Ardından yapılandırılmış bir ajan oluşturdum:

php artisan make:agent AppointmentIntentAgent --structured

Bu ajanın amacı açıktır: niyet çıkarmak, iş kurallarını doğrulamak değildir.

Kavram olarak bir örnek:

$response = (new AppointmentIntentAgent)->prompt('Quiero una cita mañana a las 8pm para 3 personas');

Beklenen yanıt yapılandırılmış bir payload olacaktır:

[ 
    "service" => "consulta_general", 
    "date" => "2026-05-03", 
    "time" => "20:00", 
    "people" => 3,
]

Kontrolörü temiz tutmak için, bir hizmet sarmalayıcı oluşturdum:

class LaravelAiAppointmentAgent 
{ 
    public function extractPayload(string $message): array 
    { 
        $response = (new AppointmentIntentAgent)->prompt($message); 
        return [ 
            'service' => $response['service'] ?? 'consulta_general', 
            'date' => $response['date'] ?? null, 
            'time' => $response['time'] ?? null, 
            'people' => (int)($response['people'] ?? 1), 
        ]; 
    } 
}

Bu şekilde akış daha düzenli hale geliyor:

ChatController
        ↓
LaravelAiAppointmentAgent
        ↓
AppointmentIntentAgent
        ↓
Laravel AI SDK
        ↓
xAI / Grok
        ↓
Payload estructurado
        ↓
GuardrailEngine

Yapay zeka, randevun geçerli olup olmadığına karar vermez. Yalnızca doğal dili yapılandırılmış verilere dönüştürür.

Doğrulama işlemi GuardrailEngine‘de olur.

Guardrail Kararları

Üç ana karar türü uyguladım:

ALLOW

İşlem geçerlidir ve devam edebilir.

STEER

İşlemde düzeltilebilir hatalar var. Sistem verileri ayarlayarak düzeltme önerisinde bulunur.

BLOCK

İşlem devam edemez, çünkü eksik bilgi var ya da sıkı bir kural bulunuyor.

STEER Örneği

Kullanıcı girişi:

Quiero una cita mañana a las 8pm para 3 personas

Laravel AI SDK ile yapılandırılmış ajan:

{
    "service": "consulta_general",
    "date": "2026-05-03",
    "time": "20:00",
    "people": 3
}

Guardrail değerlendirmesi:

20:00 está fuera del horario permitido
3 personas supera el máximo permitido

Guardrail yanıtı:

{
    "decision": "STEER",
    "reason": "Payload was corrected.",
    "corrections": [
        {
            "field": "time",
            "from": "20:00",
            "to": "17:30:00",
            "reason": "Requested time is after business hours."
        },
        {
            "field": "people",
            "from": 3,
            "to": 2,
            "reason": "Requested people count exceeds maximum allowed."
        }
    ]
}

Kullanıcıya yanıt:

La hora solicitada no cumple las reglas. Te puedo ofrecer 17:30.
El máximo permitido es 2 persona(s).
¿Deseas confirmar esta propuesta?

Burada önemli olan kısım: sistem hemen engellemiyor, fakat güvenli olduğunda düzeltmeler yapıyor.

BLOCK Örneği

Her şey otomatik olarak düzeltilmemeli.

Kullanıcı tarih vermezse sistemin tarihi invente etmemesi gerekir.

Eksik payload:

{
    "service": "consulta_general",
    "time": "10:00",
    "people": 1
}

Yanıt:

{
    "decision": "BLOCK",
    "reason": "Date is required."
}

Mesaj:

Necesito que me indiques la fecha para revisar disponibilidad.

Burada dikkat edilmeli ki: STEER hemen BLOCK yerine geçmez. Her ikisi de birbirini tamamlar.

Özelleştirilebilir Kurallar Frontadmin’den

Kuralların istemde olmaması gerektiğini vurgulamak istedim.

Frontadmin’den şu değişiklikler yapılabilir:

Hora inicio
Hora fin
Máximo de personas
Duración de cita
Permitir autocorrección
Servicios activos
Días bloqueados

Örneğin, admin şu değişiklikleri yaparsa:

Hora fin: 17:00
Máximo personas: 1

Aynı mesaj:

Quiero una cita mañana a las 8pm para 3 personas

Artık düzeltme şöyle olur:

16:30
1 persona

Bu, işletme kurallarının ajan istemini dokunmadan değiştirebileceği önemli bir fikri gösteriyor.

Grok Neden Kullanılıyor?

Grok, Laravel AI SDK’da kullanılan modelin sağlayıcısı olarak devreye giriyor.

Daha önce doğrudan HTTP ile çağıyordum. Artık akış yapılandırılmış bir ajan üzerinden geçiyor:

Laravel AI SDK
        ↓
AppointmentIntentAgent
        ↓
xAI / Grok

Görevi, doğal dili yapılandırılmış bir payload’a dönüştürmektir.

Kullanıcı:

Quiero una cita mañana a las 8pm para 3 personas

Ajan şu çıktıyı döner:

{
    "service": "consulta_general",
    "date": "2026-05-03",
    "time": "20:00",
    "people": 3
}

Ancak Grok, bunun yürütülüp yürütülemeyeceğine karar veremez.

Bu sorumluluk GuardrailEngine‘de kalır.

Laravel AI SDK yapılandırır.
Grok yorumlar.
Guardrail kontrol eder.
Laravel yürütür.

Bu, sorumlulukları ayırmaya yardımcı olur ve modelin iş kurallarına son sözü söylemesini engeller.

OpenSpec Neden Kullanılıyor?

OpenSpec’i bu değişikliği tanımlamak için kullandım.

Demo, şu belgeleri ile belgelenmiştir:

proposal.md
design.md
tasks.md
specs/ai-guardrails/spec.md
specs/appointment-booking/spec.md
specs/admin-rules/spec.md

Bu, izlenebilirliği sağladı:

Requirement → Design → Implementation → Testing

Örneğin, gereksinim şunu söylüyordu:

El sistema debe evaluar todas las acciones generadas por la IA antes de llamar al API de citas.

Bu, akışta uygulandı:

ChatController
↓
LaravelAiAppointmentAgent
↓
AppointmentIntentAgent
↓
GuardrailEngine
↓
AppointmentController

Agent Control ve Strands ile Fark

Orijinal makale Strands Agents ve Agent Control kavramlarına dayanıyor.

Bu yaklaşımda, ajan düzeltici bir talimat alabilir; ardından Guide() benzeri bir yöntemle düzeltme yaparak işlemi yeniden dener.

Benim demomda daha basit bir uyarlama yaptım:

Laravel AI SDK yapısal payload oluşturur.
GuardrailEngine validasyonu yapar.
Eğer düzeltilebilirse backend corrected_payload döner.
Kullanıcı onaylar.
Laravel yürütür.

Aynı zamanda, LLM’nin otomatik olarak yeniden denemesi yoktur. Düzeltme belirleyici olarak arka uçta gerçekleşir.

Ancak kavramsal desen korunmaktadır:

AI önerir.
Guardrail değerlendirir.
Sistem düzeltir veya engeller.
Backend yalnızca geçiyorsa yürütür.

Test Edilmiş Senaryolar

Aşağıdaki durumları test ettim:

ALLOW  → geçerli randevu
STEER  → çalışma saatleri dışında
STEER  → fazla kişi
STEER  → engellenmiş gün
STEER  → dolu slotta alternatif mevcut
BLOCK  → tarih eksik
BLOCK  → geçersiz hizmet
BLOCK  → kendi kendine düzeltme kapalı
BLOCK  → dolu slotta alternatif yok

İlginç olanlardan biri dolu slot senaryosuydu. Hemen bloke etmek yerine, guardrail bir sonraki uygun zamanı arar:

Slot solicitado ocupado
↓
Buscar siguiente slot disponible
↓
Si existe: STEER
↓
Si no existe: BLOCK

Bu, orijinal makalenin fikrine çok yakın: eğer ajanın kendini düzeltebiliyor ise, akışı kesmeyin.

Öğrendiklerim

Temel dersim şu oldu:

No todo error del agente debe terminar en bloqueo.

Güvenle düzeltilebilecek hatalar vardır:

Hora fuera de horario
Cantidad mayor al máximo
Formato incorrecto
Día bloqueado
Slot ocupado

Ancak sistemin durması gereken durumlar da mevcuttur:

Falta información crítica
Servicio no existe
No hay disponibilidad
Autocorrección desactivada
Regla estricta de negocio

Kuralların iyi bir şekilde sınıflandırılması önemlidir.

Ayrıca, Laravel AI SDK ile çalışmak çok hoştu, çünkü model ile etkileşimi ajan sınıflarında kapsüllemeyi sağladı. Bu, kodun daha sürdürülebilir olmasını ve genelde Laravel’de nasıl sorumluluklarımızı düzenlediğimizi sağlıyor.

Sonuç

Bu demo, guardrail’ları sadece “izin ver” veya “engelle” olmasının ötesinde nasıl geliştirebileceğimi anlamama yardım etti.

Son desen şu şekilde oldu:

Usuario pide algo
↓
Laravel AI SDK invoca el agente
↓
IA interpreta y genera payload
↓
Guardrail evalúa
↓
ALLOW / STEER / BLOCK
↓
Usuario confirma
↓
Backend ejecuta

Bu, Agent Control ile aynı uygulama değil, ancak orijinal makalenin ana fikrini uyguluyor: ajanın güvenli düzeltme yapabileceği durumlarda rehberlik yapmak ve yalnızca gerçekten gerekli olduğunda engellemek.

Bu yaklaşım, randevu, rezervasyon, destek, teklif yönetimi, DevOps, iç API’leri ve bir yapay zekanın eylemlere girişebileceği tüm akışlar gibi gerçek uygulamalar için önemlidir.

Önemli olan, net bir ayrım yapmaktır:

La IA entiende.
El guardrail decide.
El backend ejecuta.
El admin configura.

Kaynak Kodu

Demo kodu GitHub üzerinde mevcuttur:

https://github.com/fmarchena/appointment-agent-demo/tree/main

Depoda şunlar bulunmaktadır:

Laravel API
Laravel AI SDK
Vue frontend
Docker Compose
MySQL
GuardrailEngine
xAI / Grok ile entegrasyon
OpenSpec ile teklif, tasarım, görevler ve spesifikasyonlar

Referanslar

Temel makale:

Otomatik Düzeltme İçin Koruma Duvarları — Elizabeth Fuentes L, AWS Türkçe.

https://dev.to/aws-espanol/guardrails-para-agentes-de-ia-que-se-autocorrigen-en-lugar-de-bloquear-3n32

İlgili dokümantasyonlar:

Laravel AI SDK

https://laravel.com/docs/13.x/ai-sdk

Laravel

https://laravel.com/

xAI / Grok API

https://docs.x.ai/

OpenSpec

https://openspec.dev/