DEV Community

Cover image for Yapay Zeka Aracısı Koruma Mekanizmaları: Onay Kapıları ve Etki Alanı Kontrolü
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Yapay Zeka Aracısı Koruma Mekanizmaları: Onay Kapıları ve Etki Alanı Kontrolü

#agents #ai #automation #security

Saat sabah 3. Siz uyurken ajanınız destek bileti kuyruğunu işliyordu. Biletlerden biri acil bir eskalasyon gibi göründü; ajan bir özet hazırladı ve yöneticinize e-posta gönderdi. Özet doğruydu, dilbilgisi temizdi. Sorun şu: Kimse bu e-postayı istemedi, kimse göndermeden önce incelemedi ve ajan karar verdikten sonra onu durduracak hiçbir mekanizma yoktu. Ajan, talimatlarının izin verdiği şeyi eksiksiz yaptı. Uykunuzu kaçırması gereken nokta budur.

Apidog'u bugün deneyin

En çok zarar veren hatalar, modelin halüsinasyon gördüğü veya sürecin çöktüğü hatalar değildir. Bunlar gürültülüdür ve fark edilir. Tehlikeli olanlar sessizdir: Ajan kendisine söyleneni yapar, ancak sonuç yine de kötüdür; çünkü e-postayı göndermiş, kaydı silmiş veya siparişi vermiştir ve model kararı ile canlı eylem arasında hiçbir kontrol yoktur.

Güvenlik bariyerleri bu boşluğu kapatır. Bir güvenlik bariyeri, eylem gerçekleşmeden önce isteği inceleyen ve aşağıdaki kararlardan birini veren katmandır:

  • İzin ver
  • Engelle
  • İnsan onayına gönder

Bu rehber dört pratik güvenlik bariyerini ele alır:

  1. Eylem izin listeleri
  2. Onay kapıları
  3. Kuru çalıştırma modu
  4. Patlama yarıçapı sınırları

Son bölümde ise çoğu ekibin atladığı adımı uygulayacağız: güvenlik bariyerinin gerçekten çalıştığını test etmek.

Daha geniş bağlam için, üretimde yapay zeka ajanlarının neden bozulduğu yazısı ajan hatalarını beş kategoriye ayırır. Eksik güvenlik bariyerleri bunlardan biridir.

Eylemleri zarar potansiyeline göre sınıflandırın

Her eylem için onay kapısı gerekmez. Takvimi okuyan, tahmin getiren veya salt okunur rapor sorgulayan bir ajan, insan müdahalesi olmadan çalışabilir.

Bu tür işlemleri gereksiz onaylarla sarmak ters etki yaratır. Ekip zamanla her istemi düşünmeden “evet” diyerek geçer. Kritik bir onay geldiğinde kapı değerini kaybeder.

İlk adım, ajanınızın yapabildiği eylemleri iki gruba ayırmaktır.

Grup Örnekler Varsayılan davranış
İzin listesi Okuma, arama, tekrar çalıştırılabilir sorgular, geri alınabilir işlemler Otomatik çalıştır
Onay gerektirenler Gönderme, silme, ödeme, kayıt sistemine yazma, müşteriye ulaşan işlemler Durdur ve onay iste

Şu soruyu her eylem için sorun:

Ajan bunu yanlışlıkla yüz kez yaparsa ne kadar kötü olur?

Cevap “önemsiz” değilse, bu eylem izin listesinde olmamalıdır.

HTTP metoduna göre karar vermeyin. Sonuca göre karar verin.

Örneğin:

  • Taslak oluşturan bir POST geri alınabilir olabilir.
  • Taslağı oluşturan ve e-posta olarak gönderen bir POST geri alınamaz olabilir.

Kodda benzer görünen iki çağrı, risk sınıflandırmasında tamamen farklı gruplarda yer alabilir.

Yıkıcı eylemler için insan onayı ekleyin

Tehlikeli eylemleri belirledikten sonra bir onay kapısı ekleyin. Akış basittir:

  1. Ajan bir eylem planlar.
  2. Orkestrasyon katmanı eylemi durdurur.
  3. İnsan inceleyici gerçek isteği görür.
  4. İnceleyici onaylar veya reddeder.
  5. Yalnızca onaylanan istek canlı API'ye gider.

Bu, insan-döngüde (human-in-the-loop) modelidir. Geri alınamaz bir hatayı, reddedilebilen bir isteğe dönüştürür.

İyi bir onay ekranı özet değil, gerçek yükü göstermelidir.

Yetersiz:

Ajan bir e-posta göndermek istiyor.
Enter fullscreen mode Exit fullscreen mode

İncelenebilir:

Eylem: send_email
Alıcı: customer@example.com
Konu: Destek talebiniz hakkında
Gövde: ...
Gerekçe: Bilet önceliği "kritik" olarak sınıflandırıldı.
Enter fullscreen mode Exit fullscreen mode

Aynı ilke silme işlemleri için de geçerlidir:

Eylem: delete_record
Kayıt: invoice_12345
Gerekçe: Yinelenen kayıt olduğu tespit edildi.
Enter fullscreen mode Exit fullscreen mode

Onaylayan kişi, ajanın ürettiği açıklamaya güvenmek zorunda kalmamalıdır. Gerçek isteği görmelidir.

Ayrıca “reddetme” seçeneğini ucuz ve net tutun. Reddetmek yavaş veya belirsizse, kullanıcılar refleks olarak onay verir.

Anthropic SDK tartışmalarında da tekrar eden nokta budur: İnceleyici somut yükü göremiyorsa gerçek bir karar veremez.

Her kararı kaydedin:

{
  "action": "send_email",
  "status": "rejected",
  "reviewer": "user_42",
  "reason": "Yanlış alıcı grubu",
  "timestamp": "2025-03-08T03:15:00Z"
}
Enter fullscreen mode Exit fullscreen mode

Bu kayıtlar, bir olay sonrasında hangi kontrolün neden başarısız olduğunu bulmanızı sağlar.

Ajana kuru çalıştırma modu ekleyin

Onay kapıları üretimi korur. Kuru çalıştırma modu ise üretime gitmeden önce davranışı doğrulamanızı sağlar.

Kuru çalıştırmada ajan:

  1. Aracı seçer.
  2. İsteği oluşturur.
  3. Argümanları belirler.
  4. Eylemi çalıştırmak yerine planı raporlar.

Örnek çıktı:

{
  "dry_run": true,
  "planned_actions": [
    {
      "step": 1,
      "tool": "search_tickets",
      "arguments": {
        "priority": "high"
      }
    },
    {
      "step": 2,
      "tool": "send_email",
      "arguments": {
        "to": "manager@example.com",
        "subject": "Eskalasyon özeti"
      }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Kuru çalıştırma iki nedenle değerlidir:

  • Yeni bir görevde ajanın davranışını canlı yan etki olmadan görürsünüz.
  • Ajanın niyetlerini adım adım inceleyebilirsiniz.

Plan yanlışsa, bunu gerçek e-posta, silme veya ödeme gerçekleşmeden öğrenirsiniz.

Ama kuru çalıştırmayı onay kapısının yerine koymayın:

  • Kuru çalıştırma: geliştirme ve hazırlık ortamları için
  • Onay kapısı: üretimdeki gerçek eylemler için

Ajanın planladığı çağrıları incelemek için yapay zeka ajan hata ayıklayıcısı yaklaşımı kullanabilirsiniz. Bu yaklaşım, “ajan garip bir şey yaptı” ifadesini şu seviyeye indirir:

Dördüncü adımda silme uç noktasını çağırmaya çalıştı.

Patlama yarıçapını sınırlayın

İzin listeleri, onay kapıları ve kuru çalıştırma tek bir eylemin gerçekleşip gerçekleşmeyeceğini belirler.

Patlama yarıçapı sınırları ise ajanın toplamda ne kadar zarar verebileceğini sınırlar. Buna onaylanan eylemler de dahildir.

Üç sınır özellikle önemlidir.

1. Kapsamları sınırlayın

Ajana yalnızca ihtiyacı olan kaynaklara erişebilen kimlik bilgileri verin.

Örneğin, tek bir projenin sorunlarını yöneten ajana organizasyon yöneticisi anahtarı vermeyin. Yalnızca ilgili projeye erişen bir belirteç kullanın.

Yanlış: organization_admin_token
Doğru: project_abc_issue_manager_token
Enter fullscreen mode Exit fullscreen mode

2. Kota uygulayın

Bir eylemin belirli süre içinde kaç kez çalışabileceğini sınırlayın.

Örneğin:

send_email: saat başına en fazla 10 çağrı
delete_record: görev başına en fazla 1 çağrı
create_order: kullanıcı başına günde en fazla 3 çağrı
Enter fullscreen mode Exit fullscreen mode

Bu sınırlar, takılı kalan bir döngünün binlerce e-posta göndermesini önler.

3. Harcama sınırları koyun

Belirteç tüketimi veya para maliyeti oluşturan işlemler için görev ve gün bazında üst sınır belirleyin.

Görev başına token bütçesi: 100.000
Günlük API harcama limiti: 50 USD
Sipariş başına maksimum tutar: 100 USD
Enter fullscreen mode Exit fullscreen mode

Bu sınırlar, kontrolden çıkan bir ajanın beklenmedik maliyet yaratmasını engeller.

Sınırlarınızı gözlemleyin. Her sınır için aşağıdaki metrikleri takip edin:

  • Eylem başına çağrı sayısı
  • Görev başına harcama
  • Kota ihlalleri
  • Limit yakını hata oranları
  • Reddedilen ve onaylanan istek sayıları

Bunu, herhangi bir üretim hizmetinde yaptığınız API gözlemlenebilirliği çalışması gibi ele alın.

OWASP bu riski doğrudan adlandırır: “Aşırı Ajanlık”, LLM uygulamaları için OWASP Top 10 listesinde yer alır. Buradaki her sınır, bu riski azaltmaya yardımcı olur.

Güvenlik bariyerini test edin

Rahatsız edici gerçek şudur: Güvenlik bariyerleri genellikle yalnızca tehlikeli bir şey olmak üzereyken çalışan kod dallarıdır.

Bu nedenle en az kullanılan ve sessizce bozulma ihtimali en yüksek yollardır.

Asla tetiklenmeyen bir kapı ile tetiklenip görmezden gelinen bir kapı dışarıdan aynı görünebilir.

Test etmediğiniz güvenlik bariyerine sahip değilsiniz.

Bunu canlı API üzerinde test etmeyin. Canlı API üzerinde test etmek, gerçekten e-posta göndermek, kayıt silmek veya ödeme almak anlamına gelebilir.

Bunun yerine yan etkisi olan uç noktayı taklit edin (mock).

Test akışı

  1. Yıkıcı uç noktayı taklit edin.
  2. Ajanı tehlikeli eyleme yönlendiren senaryoyu çalıştırın.
  3. Canlı uç noktanın çağrılmadığını doğrulayın.
  4. Onay isteğinin doğru yükle oluşturulduğunu doğrulayın.
  5. Güvenli eylemlerin gereksiz onay olmadan çalıştığını test edin.

Örnek test iskeleti:

def test_agent_requests_approval_before_sending_email():
    mock_email_api = MockEmailApi()

    result = run_agent(
        ticket="Kritik eskalasyon talebi",
        email_api=mock_email_api,
        approval_required=True
    )

    assert mock_email_api.call_count == 0
    assert result.status == "pending_approval"
    assert result.approval_request.action == "send_email"
    assert result.approval_request.payload["to"] == "manager@example.com"
Enter fullscreen mode Exit fullscreen mode

Buradaki geçiş koşulu şudur:

"Ajan e-postayı gönderdi" değil,
"Ajan e-posta göndermek için onay istedi".
Enter fullscreen mode Exit fullscreen mode

Ters yönü de test edin. Güvenli bir okuma işlemi çalıştırın ve anlamsız bir onay istemi olmadan geçtiğini doğrulayın.

def test_agent_can_read_calendar_without_approval():
    result = run_agent(
        task="Yarınki toplantıları listele",
        approval_required=True
    )

    assert result.status == "completed"
    assert result.approval_request is None
Enter fullscreen mode Exit fullscreen mode

Her şeyi engelleyen bir kapı, hiçbir şeyi engellemeyen bir kapı kadar bozuktur.

API'lerinizi çağıran yapay zeka ajanlarını nasıl test edeceğinize dair rehber, bu kurulumun ayrıntılarını açıklar. Yapay zeka ajanları ve API testi yazısı ise deterministik olmayan modeller için dayanıklı doğrulama kalıplarını kapsar.

Unutulmaması gereken nokta:

  • Yan etkinin gerçekleşmediğini doğrulayın.
  • Onay akışının gerçekleştiğini doğrulayın.
  • Hem engellenen hem serbest bırakılan yolları test edin.

Apidog nerede işe yarar, nerede yaramaz?

Aracın sorumluluk sınırını net tutun.

Apidog:

  • Bir ajan çerçevesi değildir.
  • Model barındırma hizmeti değildir.
  • Güvenlik bariyeri kütüphanesi değildir.
  • Değerlendirme platformu değildir.
  • Hangi eylemlerin güvenli olduğuna karar vermez.

İzin listesi, onay kapısı, kuru çalıştırma anahtarı ve erişim sınırları sizin uygulama kodunuzun ve orkestrasyon katmanınızın sorumluluğundadır.

Apidog'un rolü, güvenlik bariyerlerinin koruduğu API katmanında başlar:

  • Gönderme, silme ve ücretlendirme gibi yan etkili uç noktaları taklit edebilirsiniz.
  • Taklitlerin başarılı veya hatalı yanıtlar döndürmesini sağlayabilirsiniz.
  • Ajanın canlı API yerine onay akışını izlediğini doğrulayabilirsiniz.
  • İstek yüklerini ve çağrı sayılarını kontrol edebilirsiniz.

Bu, doğru entegrasyon sınırıdır: Apidog, ajanın çağırdığı API'leri test eder ve yıkıcı uç noktaları taklit eder. Böylece ajanın onay yolunu izlediğini kanıtlayabilirsiniz.

Sıkça sorulan sorular

İzin listesi ile onay kapısı arasındaki fark nedir?

İzin listesi, insan müdahalesi gerektirmeyen eylemleri belirler. Bu eylemler otomatik çalışır.

Onay kapısı ise izin listesinde olmayan eylemleri durdurur ve insan kararı bekler.

Kısaca:

  • İzin listesi sınıflandırır.
  • Onay kapısı durdurur.

Güvenlik bariyerleri ajanı çok yavaşlatır mı?

Yalnızca yanlış eylemleri engellerseniz.

Geri alınabilir okuma ve sorguları izin listesinde tutun. Kapıları, maliyetli veya geri alınması zor eylemler için ayırın. İyi sınıflandırılmış bir izin listesinde çoğu adım duraklamaz.

Gerçek API'leri çağırmadan güvenlik bariyerlerini test edebilir miyim?

Evet, etmelisiniz.

Yan etkili uç noktayı taklit edin, ajanı tehlikeli senaryoda çalıştırın ve taklidin sıfır çağrı aldığını doğrulayın. Aynı anda onay yolunun doğru yükle tetiklendiğini kontrol edin.

Önce hangi eylemi kapının arkasına koymalıyım?

Geri alınması en zor olanı.

Öncelik sırası genellikle şöyledir:

  1. Ödemeler
  2. Silmeler
  3. Müşteriye veya iş arkadaşına ulaşan iletişimler
  4. Kayıt sistemlerine yapılan yazmalar

Yanlışlıkla tek bir tekrarın gerçek hasar yaratabileceği eylemler izin listesinde değil, onay kapısının arkasında olmalıdır.

En yıkıcı eyleminizle başlayın

İlk günden itibaren dört güvenlik bariyerinin tamamını uygulamak zorunda değilsiniz.

Önce, olay incelemesinde açıklamak istemeyeceğiniz tek eylemi seçin. Bu hafta o eylem için bir onay kapısı ekleyin.

Ardından testi yazın:

  1. Uç noktayı taklit edin.
  2. Ajanı tehlikeli senaryoda çalıştırın.
  3. Ajanın eyleme geçmek yerine onay istediğini doğrulayın.

Kapıyı ilk kez bozduğunuzda testin kırmızıya döndüğünü gördüğünüzde, güvenlik bariyerine gerçek bir nedenle güvenirsiniz: yalnızca var olduğu için değil, test edildiği için.

Apidog'u indirin; yıkıcı uç noktaları taklit etmek, yanıtları programlamak ve ajanınızın canlı yol yerine onay yolunu izlediğini doğrulamak için.

Top comments (0)