Veri Kaybı Olmadan API'lerinizi Çağıran Yapay Zeka Ajanları Nasıl Test Edilir

Bir yapay zeka kodlama ajanı bir komut dosyasını çalıştırdı, başarılı olduğunu gördü, sonra bir üretim veritabanı tablosunun yok olduğunu izledi. Hacker News'taki ölüm sonrası analizi keskin bir başlıkla viral oldu: “Yapay zeka veritabanınızı silmedi, siz sildiniz.” Bu nokta yerine oturdu çünkü doğruydu. Ajan bir araç tanımını izledi, araç gerçek bir uç noktaya ulaştı, uç noktada hiçbir güvenlik önlemi yoktu ve bir insan, `DELETE FROM users` komutunun şüpheli görünüp görünmediğini sormak için duraklamayan bir sürece anahtarları teslim etmişti. Ayrı bir r/ClaudeAI başlığı, farklı bir açıdan benzer bir hikaye anlattı: bir faturalandırma döngüsündeki bir ajan, biri fark edene kadar yüzlerce dolarlık jetonu yiyip bitirdi. Farklı yüzey, aynı hata sınıfı. Sorun, modelin aptal olması değil. Sorun, kimsenin API'yi test etmemesi.

Kısaca

Ajanlar, araçlarının API tarafında güvenlik önlemleri olmadığında üretimde başarısız olur: eksik oran sınırlamaları, kimliklendirme eksikliği, kritik silmeler, bozuk şemalar. Bunu dört hamleyle düzeltirsiniz: ajanın araç tanımlarını OpenAPI spesifikasyonunuza karşı sözleşme-testi yapın, yıkıcı uç noktalar için bir taklit sunucu çalıştırın, ajan başına bütçe limitlerini ve kimliklendirme anahtarlarını uygulayın ve CI'da hata senaryolarını tekrar oynatın. Apidog, tüm bunları tek bir projeden yapmak için size OpenAPI içe aktarımını, taklitleri ve senaryo yürütücüyü sağlar.

Giriş

Bir yıl önce, "yapay zeka ajanını test etmek" Claude veya GPT'yi sorgulamak ve cevabı derecelendirmek anlamına geliyordu. Artık çıta bu değil. Günümüzün ajanları fonksiyonları çağırır, bu fonksiyonlar API'larınıza ulaşır ve API'larınız gerçek veritabanları, ödeme işlemcileri ve üçüncü taraf hizmetlerle konuşur. Kötü bir araç tanımı veya eksik bir oran sınırlaması stilistik bir sorun değildir. Bu, adınızın geçtiği bir üretim olayıdır.

Bu ayki viral Hacker News hikayesi bu değişimi yakaladı. Yazar, yapay zekanın veritabanını silmediğini; bunu insanın yaptığını, ajana model ile veri arasına herhangi bir kontrol koymadan yazma erişimi vererek iddia etti. Bu konu çok konuşuldu çünkü okuyan her geliştirici "Neredeyse ben de bunu gönderecektim" diye düşündü. Birkaç hafta önce, bir Reddit gönderisi, bir ajanın başarısız bir çağrıyı o kadar çok denediği bir faturalandırma döngüsünü anlattı ki, biri fark edene kadar fatura 800 avroyu aştı. Aynı temel neden: güvenin yanlış katmana yerleştirilmesi.

Bunu düzeltebilirsiniz. Model katmanı önemlidir, ancak kanamayı durdurduğunuz yer API katmanıdır. Bu makale, yapay zeka ajanlarının API entegrasyonlarını uçtan uca nasıl test edeceğinizi gösteriyor. Her ajan-API kurulumunun ihtiyaç duyduğu dört güvenlik önlemini ele alacak, yıkıcı uç noktaları taklit etmek için adım adım bir Apidog iş akışını inceleyecek ve şema kayması tespiti ve çift anahtar ayrımı gibi gelişmiş tekniklerle bitireceğiz. Repo'nuzda bugün kopyalayabileceğiniz somut desenlerle ayrılacaksınız. Taklit sunucu adımlarını takip edebilmek için başlamadan önce Apidog'u indirin.

Ajan hataları neden API hataları gibi görünür?

Yeterince ajan ölüm sonrası analizi okuduğunuzda bir kalıp ortaya çıkar: model baş kahraman değildir. API'dir.

Örneğin, istem enjeksiyonu. Bir kullanıcı gizli talimatlar içeren bir PDF yükler, ajan bunu okur ve bir sonraki araç çağrısı `delete_all=true` ile `/admin/users` uç noktanıza gider. Model bunu seçmedi; güvenmek için hiçbir nedeni olmayan talimatları izledi. Çözüm, istemi güçlendirmek değildir. Çözüm, kullanıcı bağlamlı bir oturumdan gelen bir jetona `delete_all=true` komutunu açık etmeyen bir API oluşturmaktır. OWASP bunu LLM Top 10'da LLM01 olarak adlandırır ve hafifletme, istem mühendisliği değil, API tarafı yetkilendirmedir.

Hatalı araç şemalarını ele alalım. OpenAPI spesifikasyonunuzda `amount` değeri sent cinsinden bir tam sayı olarak belirtilir. Ajanın araç tanımı, `amount` değerinin dolar cinsinden bir ondalık sayı olduğunu söyler. Üç ay sonra, biri 19 sentlik bir ücreti 19 dolar olarak iade eder ve bu tutarsızlığı muhasebeden öğrenirsiniz. Model yanlış değildi; model ona verdiğiniz şemayı kullandı. Şema API'den sapmıştı. Kimse sözleşmeyi test etmemişti.

Eksik oran sınırlamalarını ele alalım. Bir yeniden deneme döngüsündeki bir ajan, ajanın planlayıcısı adımı "henüz başarılı değil" olarak işaretlemeye devam ettiği için iki dakika içinde işlem e-posta uç noktanızı binlerce kez bombalar. Her yeniden deneme paraya mal olur. Her yeniden deneme gerçek bir e-postayı sıraya koyar. Siz uyanana kadar, sağlayıcınız hesabınızı işaretlemiş ve müşterileriniz spam almıştır. Model kötü niyetli değildi. Model, bir sınırı olmayan bir araçtan çalışıyordu.

Eksik kimliklendirmeyi ele alalım. Ajan, bir müşteriyi ücretlendirmek için `POST /payments` çağrısını yapar, bir ağ zaman aşımı alır, planlayıcı çağrının başarısız olduğunu düşündüğü için yeniden dener ve şimdi müşteri iki kez ücretlendirilir. Ajan katmanı orijinal çağrının başarılı olup olmadığını anlayamaz; API ona sormanın bir yolunu vermedi. Kimliklendirme anahtarları bunu beş satır sunucu kodunda çözer, ancak bunları yazmanız gerekir.

Ortak nokta: Bu olayların her birinde ajan, araçlarının kendisine söylediklerini tam olarak yapmaktadır. Araçlar, API'dir. Dolayısıyla, ajan güvenilirliğinin nerede bozulduğunu denetlerken, önce API sözleşmesine, ikinci olarak ajan donanımına ve neredeyse hiç modelin kendisine bakmayın. Bu yeniden çerçevelendirme önemlidir, çünkü nereye yatırım yapmanız gerektiğini söyler. Daha akıllı bir modele ihtiyacınız yok. Güvenlik önlemleri açık, test edilebilir API'lara ihtiyacınız var.

Her ajan-API entegrasyonunun ihtiyaç duyduğu dört güvenlik önlemi

Dört kontrol, güvenli bir şekilde başarısız olan ajan kurulumlarını pahalı bir şekilde başarısız olanlardan ayırır. Bu çeyrekte sadece bir tane eklemeye vaktiniz varsa, en üstten başlayın. Dördünü de yapabilirseniz, 2026'da göreceğiniz olay senaryolarının yüzde 90'ından fazlasını kapsarsınız.

1. Araç-şema sözleşme testleri

OpenAPI spesifikasyonunuz API'nizin gerçek kaynağıdır. Ajanınızın ayrı bir araç tanımı vardır, genellikle elle yazılmış veya dokümanlardan kopyalanmıştır. Bu iki yapıt sürekli olarak sapar. Sözleşme testleri, farklılaştıkları anda CI derlemenizi başarısız kılar.

İşte canlı OpenAPI spesifikasyonuna karşı Claude tarzı bir araç tanımını doğrulayan minimal bir Python kontrolü:

import json
from jsonschema import Draft202012Validator

def validate_tool_against_openapi(tool_def: dict, openapi_spec: dict) -> list[str]:
    """Uyuşmazlık hatalarının bir listesini döndürür, boş liste = geçerli."""
    errors = []
    op = openapi_spec["paths"][tool_def["path"]][tool_def["method"].lower()]
    api_schema = op["requestBody"]["content"]["application/json"]["schema"]
    tool_schema = tool_def["input_schema"]

    api_props = set(api_schema.get("properties", {}).keys())
    tool_props = set(tool_schema.get("properties", {}).keys())

    for missing in api_props - tool_props:
        if missing in api_schema.get("required", []):
            errors.append(f"Araçta zorunlu alan eksik: {missing}")
    for extra in tool_props - api_props:
        errors.append(f"Araç, API'de olmayan bir alan tanımlıyor: {extra}")

    for prop, api_def in api_schema.get("properties", {}).items():
        if prop in tool_schema.get("properties", {}):
            tool_def_prop = tool_schema["properties"][prop]
            if api_def.get("type") != tool_def_prop.get("type"):
                errors.append(
                    f"{prop} üzerinde tip uyuşmazlığı: API={api_def.get('type')} "
                    f"araç={tool_def_prop.get('type')}"
                )
    return errors

Hem OpenAPI spesifikasyonuna hem de araç tanımlarına dokunan her PR üzerinde bunu çalıştırın. Liste boş değilse derlemeyi başarısız kılın. Bu tek kontrol, önceki bölümde belirtilen ondalık sayı-sent hatasını herhangi bir geri ödeme yapılmadan aylar önce yakalayabilirdi.

2. Yıkıcı uç noktalar için sanal ve taklit ortamlar

Ajanların pratik yapacak bir yere ihtiyacı var. Asla üretimde pratik yapmamalılar. Model basittir: durumu değiştiren her uç noktanın, işi yapmadan aynı yanıt şeklini döndüren bir taklit karşılığı vardır. Ajan geliştirme döngünüz taklitleri kullanır. Hazırlık testleriniz bir sanal veritabanı kullanır. Üretim, bir insan dağıtımı onaylayana kadar dokunulmadan kalır.

Apidog, OpenAPI spesifikasyonundan doğrudan taklitler oluşturur; buna Faker desenleri tarafından yönlendirilen gerçekçi alan değerleri de dahildir. Ajanınızın temel URL'sini taklit sunucusuna işaretlersiniz, isteminizin yüzlerce yinelemesini çalıştırır ve nasıl davrandığını izlersiniz. Ajan, belgeleri yanlış anladığı için `/users/{id}/delete` adresine PUT yapmaya devam ederse, taklit bunu yakalar. Üretimdeki kullanıcı tablosu bu hatayı asla görmez. Bu kalıbın daha geniş uyduğu durum için sözleşme-öncelikli geliştirme bölümüne bakın.

3. Geri döndürülemez işlemler için kimliklendirme anahtarları ve mantıksal silmeler

Ajanınızın çağırabileceği her yazma uç noktası bir kimliklendirme anahtarını kabul etmelidir. Her silme işlemi varsayılan olarak bir mantıksal silme olmalı ve insanların yetkilendirdiği ayrı bir kalıcı silme yolu bulunmalıdır.

Middleware Express'te şöyle görünür:

const idempotencyCache = new Map();

function idempotency(req, res, next) {
  const key = req.headers['idempotency-key'];
  if (!key) {
    return res.status(400).json({ error: 'Idempotency-Key başlığı eksik' });
  }
  if (idempotencyCache.has(key)) {
    const cached = idempotencyCache.get(key);
    return res.status(cached.status).json(cached.body);
  }
  const originalJson = res.json.bind(res);
  res.json = function (body) {
    idempotencyCache.set(key, { status: res.statusCode, body });
    setTimeout(() => idempotencyCache.delete(key), 24 * 60 * 60 * 1000);
    return originalJson(body);
  };
  next();
}

app.post('/payments', idempotency, createPayment);

Ajan, her mantıksal işlem için bir UUID oluşturur ve yeniden denemelerde bunu yeniden kullanır. API'niz, ikinci çağrıda iki kez ücretlendirmek yerine önbelleğe alınmış yanıtı döndürür. Bu aynı kalıp, mesajlaşma API'lerinde çift göndermelere, CRM'lerde yinelenen satır oluşturmaya ve diğer çoğu "ajan yeniden denedi ve şimdi bir karmaşa var" senaryosuna karşı koruma sağlar.

4. Ajan başına bütçe üst sınırları

Her ajanın bir bütçesi vardır. Token bütçesi, istek bütçesi, dolar bütçesi, zaman bütçesi. Bütçe bittiğinde ajan durur. İstisna yok. 800 avroluk Reddit olayı, kimsenin kontrolden çıkan bir döngüye bir tavan koymaması nedeniyle yaşandı ve insan kontrol ettiğinde hasar zaten oluşmuştu.

API ağ geçidinizi saran bir bütçe ara yazılımı şunları takip edebilir:

• Oturum başına token, 50.000 ile sınırlı
• Dakika başına API çağrısı, 30 ile sınırlı
• Sent cinsinden kümülatif harcama, 500 ile sınırlı
• Araç çağrısı derinliği, 10 iç içe çağrı ile sınırlı

Herhangi bir sınıra ulaşıldığında, yapılandırılmış bir `Retry-After` ve sınırı belirten `X-Budget-Exceeded` başlığı ile HTTP 429 döndürün. Ajanın planlayıcısı daha sonra bir insana eskalasyon yapabilir veya görevi geri alabilir. Hangi ajanların limitleri zorladığını görmek ve buna göre ayarlama yapmak için bunu günlüğe kaydetme ile birleştirin.

Bu dört kontrol bir araya gelir. Sözleşme testleri belirgin şema hatalarını yakalar. Taklitler yıkıcı olanları yakalar. Kimliklendirme, yeniden deneme fırtınalarını yakalar. Bütçeler, kontrolden çıkan döngüleri yakalar. Hep birlikte, "ajan korkunç bir şey yaptı" ifadesini "ajan 429'a çarptı, sorunu kaydetti ve yardım istedi" ifadesine dönüştürürler. Çıta budur.

Apidog ile ajan API çağrılarını test edin

Şimdi pratik kısım. İşte Apidog'da eksiksiz bir ajan-API test iş akışını nasıl kuracağınız. Ajanınızın çağırdığı API için OpenAPI spesifikasyonuna ve ajanın araç tanımlarının bir listesine ihtiyacınız olacak.

Adım 1: OpenAPI spesifikasyonunu içe aktarın

Apidog'u açın, yeni bir proje oluşturun ve OpenAPI 3.x dosyanızı içe aktarın. Apidog her yolu, şemayı ve örneği ayrıştırır ve projede karşılık gelen uç noktalar oluşturur. API'niz henüz OpenAPI'de belgelenmemişse, bunu yapmanın tam zamanı; ajan güvenilirliği, hem insanlarınızın hem de yapay zeka ajanlarınızın okuyabileceği tek bir doğru kaynağa sahip olmaya bağlıdır. Baştan başlıyorsanız, tasarım öncelikli API iş akışı rehberi bu konuda size yol gösterecektir.

Adım 2: Yıkıcı uç noktalar için taklit yanıtları tanımlayın

Veriyi değiştiren her uç noktayı bulun: POST, PUT, PATCH, DELETE. Her biri için, uç noktaya tıklayın ve bir taklit yanıtı ekleyin. Apidog, şemanızdan gerçekçi taklitler otomatik olarak oluşturabilir, ancak alan değerlerini üretim verisi gibi değil, test verisi gibi görünecek şekilde geçersiz kılmalısınız. Günlüklerde herhangi bir sızıntının bariz olması için `mock_user_` gibi ön ekler ve 1970 yılındaki zaman damgalarını kullanın.

Taklit sunucuyu başlatın. Apidog size `https://mock.apidog.com/m1/your-project-id/` gibi sabit bir URL verir. Geliştirme sırasında ajanınızın API temel URL'sini taklit sunucusuna yönlendirin. Artık `DELETE /users/{id}` sahte bir kullanıcı yükü ile 200 döndürür ve gerçek veritabanınız güvendedir.

Adım 3: Ajanın çağrı dizisini simüle eden bir senaryo yazın

Apidog senaryoları, bir test paketi gibi, onaylamalarla API çağrılarını zincirlemenize olanak tanır. Destek biletlerini önceliklendiren bir ajan için senaryo şöyle olabilir:

1. Test kimlik bilgileriyle POST ` /auth/token` , taşıyıcı token'ı yakalayın
2. Token ile GET ` /tickets?status=open` , ilk bilet kimliğini yakalayın
3. Bir kategoriyle POST ` /tickets/{id}/triage` , 200'ü onaylayın ve atanmış-kime alanını yakalayın
4. Şablonlu bir mesajla POST ` /notifications` , mesaj gövdesinin bir regex ile eşleştiğini onaylayın

Esas olarak, ajanın üretimde göreceği bir değişiklikten önce, taklit sunucusu üzerinde, her adımda onaylamalarla ne yapacağını provasını yapıyorsunuz. Bir geliştirici bilet şemasını değiştirirse ve regex eşleşmezse, senaryo başarısız olur ve ajanın üretime geçmeden önce bunu bilirsiniz. Daha geniş senaryo test playbook'u için QA mühendisleri için API testi bölümüne bakın.

Adım 4: CI'dan çalıştırın

Apidog, senaryoları bir GitHub Eylemi, GitLab işlem hattı veya herhangi bir CI çalıştırıcısından çalıştıran bir CLI sunar. Komut `apidog run -t scenario-id --env test` gibi görünür. Her PR'da OpenAPI spesifikasyonunda veya ajan araç tanımlarında yapılan her değişikliğin tam bir senaryo tekrarını tetiklemesi için bunu PR işlem hattınıza bağlayın.

Adım 5: İki model sürümünü yan yana karşılaştırın

Bir modelden diğerine yükseltmeyi değerlendirirken, yeni modelin araç çağrılarının aynı senaryolarda aynı şekilde davranıp davranmadığını bilmek istersiniz. A modelini kullanarak ajanı aynı Apidog senaryosuna karşı çalıştırın, izi yakalayın. B modelini kullanarak tekrar çalıştırın, izi yakalayın. İstek gövdelerini karşılaştırın. Sürprizler hemen ortaya çıkar: B modeli farklı bir `priority` değeri geçirir veya bir alanı atlar veya tarihler için farklı bir format kullanır. Davranışsal sapmayı gönderilmeden önce yakalarsınız. Bu, yeni model davranışını değerlendirmenin tekrarlayan bir ihtiyaç olduğu GPT-5.5 API entegrasyonunda ele alınan desenlerden biridir.

Tüm iş akışı ilk kurulumda yaklaşık bir saat, sonrasında ise her çalıştırmada dakikalar sürer. Karşılığı ise, API'nizdeki veya ajan araçlarınızdaki her değişikliğin aynı beklenti tabanına göre test edilmesidir.

Gelişmiş teknikler ve profesyonel ipuçları

Temel bilgiler oturduktan sonra deneyimli ekiplerin başvurduğu birkaç model.

Testlerde sıcaklığı sıfıra sabitleyin. Deterministik olmayan ajanlar, deterministik olmayan test hatalarına neden olur. Araç çağrısı davranışını test ederken, sıcaklığı 0'a ayarlayın ve herhangi bir rastgelelik kaynağını sabitleyin. Yaratıcılık katmanını değil, araç katmanını test ediyorsunuz.

Araç çağrısı izlerini anlık görüntüleyin. Her test çalıştırması, ajanın yaptığı araç çağrılarının tam sırasını, argümanlarıyla birlikte kaydeder. Önceki taban çizgiyle farkı karşılaştırın. Ajan aniden `/users` öğesini bir yerine iki kez çağırmaya başlarsa, faturanın geldiği üç hafta sonra değil, bunu hemen bilmek istersiniz.

Bir ajana asla üretim kimlik bilgileri vermeyin. Ajanlar, kapsamlı hizmet hesapları alır. Üretim kimlik bilgileri, ajanın okuyabileceği `.env` dosyalarında değil, kasalarda bulunur. Bir ajanın bir üretim uç noktasını çağırması gerekiyorsa, istekleri kısa ömürlü token'larla imzalayan bir proxy üzerinden gider.

Okuma ve yazma API anahtarlarını ayırın. Çoğu ajan görevi çoğunlukla okuma odaklıdır. Bunlar için salt okunur anahtarlar verin. Yazma anahtarları, insan onayı gerektiren görevler için ayrılmıştır. Bu tek değişiklik, ele geçirilmiş bir ajanın etki alanını yarıya indirir.

İnsan onayı gerektiren uç noktalar için HTTP 423 Kilitli kullanın. Bir ajan, insan onayı gerektiren bir uç noktayı çağırmaya çalıştığında, 423 yanıtını bir `confirmation_url` alanı ile döndürün. Ajanın planlayıcısı kilitli durumu görür, URL'yi bir insana gösterir ve bekler. Bu, 403'ten daha temizdir, çünkü 403 "bunu yapamazsınız" anlamına gelirken, 423 "bunu henüz yapamazsınız" anlamına gelir.

Şema kaymasında kapalı başarısız olun. Ajanın araç tanımı OpenAPI spesifikasyonunuzla eşleşmezse, derleme başarısız olur. Bir uyarı göndermeyin. Bir hata gönderin. Birkaç ekstra başarısız derlemenin maliyeti, bir üretim olayından çok daha düşüktür.

Kaçınılması gereken yaygın hatalar:

• Taklit URL'yi ajan istemlerine sabit kodlamak. Aynı istemin taklit, hazırlık ve üretim ortamlarında çalışması için ortam değişkenleri kullanın.
• "Küçük" uç noktalarda kimliklendirmeyi atlamak. Her yazma işleminin buna ihtiyacı var. E-posta gönderimi istisna değildir.
• Üretimde tam istek gövdelerini günlüğe kaydetmek. PII (Kişisel Tanımlayıcı Bilgiler) gözlem yığınına sızar. Token'ları, e-postaları ve tanımlayıcıları günlüklere ulaşmadan önce sansürleyin.
• Ajanların doğrudan veritabanı erişimine sahip olmasına izin vermek. Her zaman API üzerinden gidin. API, testlerinizin yaşadığı yerdir.
• Ajanın güven puanına güvenmek. Puan, modelin cevap hakkındaki kesinliğini yansıtır, API güvenliğini değil. %99 güvenli bir ajan bile yanlış uç noktayı çağırabilir.

Arkasında tek bir API ağ geçidi olmayan dahili hizmetlerle konuşan ajanınız varsa, mikro hizmetler test modelleri, senaryo testlerini hizmetler arasında nasıl dağıtacağınızı anlatır.

Alternatifler ve araçlar

Seçenekleriniz var. İşte dört yaygın yaklaşımın adil bir karşılaştırması.

Dürüst özet: LangSmith'te yaşıyorsanız, ajan tarafında işe yarayanı yapmaya devam edin ve ayrı bir API test katmanı ekleyin. Postman'ın fiyatlandırmasını veya taklit modelini aştıysanız, Apidog güçlü bir alternatiftir. Sıfırdan başlıyorsanız, OpenAPI, taklitler ve senaryoları tek bir projede ele alan aracı seçin, çünkü ajan-API test sürenizin %80'i oraya gider.

Bazı ekipler bunları bir araya getirir. İstem seviyesi değerlendirmeleri için LangSmith'i kullanmaya devam ederler ve API tarafı sözleşme testleri ve senaryo tekrarları için Apidog'u kullanırlar. Bu gayet iyi çalışır; araçlar farklı katmanlara hizmet eder.

Gerçek dünya kullanım örnekleri

Ajan, üretim veritabanı satırlarını günceller. Bir müşteri başarısı ekibi, destek biletlerinden hesap alanlarını güncelleyen bir ajan geliştirdi. Lansmandan önce, her yazma uç noktasını bir kimliklendirme anahtarı gerektirecek şekilde yapılandırdılar ve bir sanal veritabanına karşı Apidog'da 200 senaryo tekrarı çalıştırdılar. Tekrarlar, ajanın `subscription_status` alanını, enum'da olmayan bir dizeye ayarlamaya çalıştığı iki durumu yakaladı. Şema doğrulaması eklediler ve sorunsuz bir şekilde yayına aldılar.

Ajan bir ödeme API'sini çağırır. Otomatik bir iade ajanı geliştiren bir fintech ekibi katı sınırlar belirledi: oturum başına en fazla 5 iade, iade başına en fazla 50 dolar, her çağrıda kimliklendirme zorunlu. Her PR'da Stripe'ın OpenAPI'sine karşı sözleşme test paketini çalıştırdılar. Altı ay içinde, sıfır çift ücretlendirme ile 12.000 iade işlediler.

Ajan GitHub sorunlarını önceliklendirir. Bir platform ekibi, Clawsweeper'dan esinlenerek bir sorun önceliklendirme ajanı geliştirdi. GitHub API'sini Apidog'da taklit ettiler, ajanı uç durumları (silinmiş sorunlar, eksik etiketler, hatalı kullanıcı girdisi) kapsayan 50 senaryo testinden geçirdiler ve lansmandan önce üç çökme buldular. Ajan şu anda 5.000 açık sorunu olan halka açık bir repoda önceliklendirmeyi yönetiyor.

Sonuç

Bu rehberden tek bir şey alacaksanız, şunu alın: sorun ajan değil. Sorun API'dir, ya da onu test edip etmediğinize bağlı olarak çözümdür.

Beş çıkarım:

• Araç şemalarını sözleşme olarak ele alın ve CI'da sözleşme testleri çalıştırın.
• Her ajan geliştirme döngüsü için yıkıcı uç noktaları taklit edin.
• Ajanınızın çağırabileceği her yazma işlemi için kimliklendirme anahtarları isteyin.
• Vurulduğunda kapalı başarısız olan ajan başına bütçe üst sınırları belirleyin.
• API'ye veya araç tanımlarına dokunan her PR'da senaryoları tekrar oynatın.

Bu yılki viral olaylar son olmayacak. Ajanları gönderen her ekip bu hata modlarından en az birini bir kez yaşayacaktır. Hızlıca toparlanan ekipler, güvenlik önlemleri zaten yerinde olan ekiplerdir. Apidog'u indirin ve taklit sunucu adımıyla başlayın; sadece bu bile bu çeyrekte uykusuz bir gece geçirmenizi engelleyecektir. Bu aynı sorunla ilgili QA ekibi perspektifi için, QA mühendisleri için API test araçları bölümüne bakın. Ajanların güvenle kullanabileceği araç tanımları yazma konusunda daha geniş bağlam için, AGENTS.md dosyaları nasıl yazılır bölümüne bakın.

SSS

Tokenlar için para harcamadan yapay zeka ajan API çağrılarını nasıl test ederim?

Geliştirme sırasında ajanı bir taklit sunucusuna karşı çalıştırın. Apidog'un taklit URL'leri ücretsiz olarak gerçekçi yanıtlar döndürür, böylece test döngüleriniz gerçek API kredilerini yakmaz. Sıcaklığı 0'a sabitleyin ve küçük, sabit bir istem kümesi kullanın. Taklit sunucunun maliyeti sıfır olduğu için binlerce test yinelemesi çalıştırabilirsiniz. Tam kurulum için QA mühendisinin test kontrol listesi bölümüne bakın.

Ajanı test etmek ile API'yi test etmek arasındaki fark nedir?

Ajan testi, modelin doğru aracı seçip argümanları doğru doldurup doldurmadığını kontrol eder. API testi, uç noktanın çağrıldığında doğru davranıp davranmadığını kontrol eder. İkisi de önemlidir. Bozuk bir API'yi çağıran mükemmel bir ajan hala bozuk sonuçlar üretir ve mükemmel bir API'yi çağıran bozuk bir ajan hala hatalar gönderir. Her iki katmanın da ayrı ayrı test edilmesi gerekir.

Her uç noktada kimliklendirme anahtarlarına ihtiyacım var mı?

Evet, her yazma uç noktasında. Okumalar tanım gereği kimliklendiricidir. Yazmalar değildir ve ajanlar yeniden dener. Bir kimliklendirme başlığını desteklemek için beş satır ara yazılım kodu, ajanın bir 500 hatasını yeniden denediğinde ve sizde yinelenen bir satır olmadığında kendini amorti eder.

Yanlış API çağrılarını tetikleyen istem enjeksiyonunu nasıl önlerim?

Yalnızca istem katmanına güvenmeyin. API, yetkilendirmeyi ajanın isteğine göre değil, orijinal kullanıcı bağlamına göre zorlamalıdır. Bir kullanıcı bağlamlı oturum normalde `/admin/delete-all-users` adresine ulaşamıyorsa, o kullanıcının adına hareket eden ajan da istem ne derse desin bunu yapamamalıdır. OWASP'ın LLM Top 10'u bunu ayrıntılı olarak ele almaktadır.

Kendi araç katmanımı yazmadan doğrudan Claude veya GPT ile Apidog kullanabilir miyim?

Test sırasında ajanın araç tanımlarını Apidog taklit URL'sine işaretlersiniz. Hem Claude hem de GPT, araç tanımlarında rastgele HTTP temel URL'lerini destekler, bu nedenle değiştirme tek bir ortam değişkenidir. Hazırlık veya üretim ortamlarına karşı test etmeye hazır olduğunuzda değişkeni değiştirin.

Bir ajan için doğru bütçe üst sınırı nedir?

Katı başlayın ve verilerle gevşetin. Oturum başına 50.000 token, dakika başına 30 API çağrısı, görev başına 5 dolar ile başlayın. Metrikleri iki hafta boyunca izleyin. Yasal olarak çarptığınız üst sınırları yükseltin. Hiç vurmadığınız üst sınırları düşürün. Aylık olarak gözden geçirin. Amaç sabit bir sayı değil; kontrolden çıkan döngüleri yakalayacak kadar sıkı ve gerçek işlerin gerçekleşmesine izin verecek kadar gevşek bir sayıdır.

Ajanın araçları ile API'm arasındaki şema kaymasını nasıl tespit ederim?

Her PR'da CI'da bir şema farkı çalıştırın. Ajanın araç tanımını (JSON şeması) aynı uç nokta için OpenAPI istek gövdesi şemasıyla karşılaştırın. Farklılık gösterirlerse derlemeyi başarısız kılın. Yukarıdaki güvenlik önlemleri bölümündeki 30 satırlık Python kodu bunu yapar; bunu reponuza kopyalayın ve GitHub Actions'a bağlayın.