DEV Community

Cover image for Veri Kaybı Olmadan API'lerinizi Çağıran Yapay Zeka Ajanları Nasıl Test Edilir
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

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ü ve ardından üretim veritabanındaki bir tablonun kaybolduğunu fark etti. Hacker News’teki ölüm sonrası analiz şu başlıkla yayıldı: “Yapay zeka veritabanınızı silmedi, siz sildiniz.” Mesaj netti: ajan yalnızca kendisine verilen araç tanımını izledi; araç gerçek uç noktaya gitti; uç noktada güvenlik önlemi yoktu; insan da DELETE FROM users gibi bir işlemi sorgulamayan sürece üretim anahtarlarını verdi. r/ClaudeAI’deki başka bir olayda ise bir ajan, faturalandırma döngüsünde yüzlerce dolarlık token tüketti. Yüzey farklıydı, hata sınıfı aynıydı: sorun modelin “aptal” olması değil, API’nin test edilmemesiydi.

Apidog'u bugün deneyin

💡 Otonom ajanlar API’larınızı çağırıyorsa, bu rehber sizin için. Ajan geliştirme sırasında harici uç noktaları nasıl taklit edeceğinizi, yıkıcı işlemleri nasıl sanal ortama alacağınızı, araç şemaları için sözleşme testleri yazmayı, ajan başına bütçe üst sınırları belirlemeyi ve üretime geçmeden önce hata modlarını nasıl prova edeceğinizi göreceksiniz. Test iskelelemesi için Apidog kullanacağız; çünkü OpenAPI ile çalışır, yapıştırıcı kod yazmadan mock sunucular oluşturur ve ajan araç çağrı dizilerine uygun senaryo testleri sağlar.

Kısaca

Ajanlar, araçlarının arkasındaki API tarafında güvenlik önlemi yoksa üretimde pahalı şekilde başarısız olur:

  • Eksik rate limit
  • Eksik kimliklendirme / idempotency
  • Kritik silme işlemleri
  • OpenAPI ile uyuşmayan araç şemaları
  • Gerçek ödeme, e-posta veya veritabanı uç noktalarına kontrolsüz erişim

Bunu dört adımda azaltabilirsiniz:

  1. Ajan araç tanımlarını OpenAPI spesifikasyonuna karşı sözleşme testinden geçirin.
  2. Yıkıcı uç noktalar için mock veya sanal ortam kullanın.
  3. Her ajan için bütçe, token ve istek limiti koyun.
  4. Hata senaryolarını CI’da tekrar oynatın.

Apidog, OpenAPI içe aktarımı, mock sunucular ve senaryo yürütme özelliklerini tek projede topladığı için bu akışı pratik hale getirir.

Giriş

Bir yıl önce “yapay zeka ajanını test etmek”, Claude veya GPT’ye birkaç prompt göndermek ve yanıtı değerlendirmek anlamına geliyordu. Artık bu yeterli değil.

Bugünün ajanları:

  • Fonksiyon çağırıyor
  • API’larınıza istek gönderiyor
  • Veritabanı, ödeme sağlayıcısı ve üçüncü taraf servislerle konuşuyor
  • Başarısız çağrıları tekrar deniyor
  • Araç şemalarındaki hataları aynen uyguluyor

Bu nedenle kötü bir araç tanımı veya eksik rate limit yalnızca “model davranışı” problemi değildir. Üretim olayıdır.

Hacker News’teki viral olay da bunu gösterdi: yapay zeka veritabanını silmedi; insana ait bir sistem, model ile veri arasına kontrol koymadan yazma erişimi verdi. Reddit’teki başka bir olayda ise ajan, başarısız çağrıları tekrar ederek faturalandırmayı 800 avronun üzerine taşıdı.

Ortak kök neden: güven yanlış katmana yerleştirildi.

Model katmanı önemlidir; ancak hasarı durduracağınız yer API katmanıdır. Bu yazıda, yapay zeka ajanlarının API entegrasyonlarını uçtan uca nasıl test edeceğinizi uygulamalı olarak göreceksiniz.

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

Yeterince ajan olayı incelerseniz aynı kalıp ortaya çıkar: model çoğu zaman baş aktör değildir. API’dir.

Prompt injection

Bir kullanıcı gizli talimatlar içeren PDF yükler. Ajan PDF’yi okur ve sonraki araç çağrısında /admin/users uç noktasına delete_all=true gönderir.

Burada çözüm yalnızca prompt’u güçlendirmek değildir. API, kullanıcı bağlamlı bir oturumdan gelen token ile delete_all=true gibi bir işlemi kabul etmemelidir.

OWASP bunu LLM Top 10’da LLM01 kapsamında ele alır. Azaltma stratejisi prompt mühendisliği değil, API tarafı yetkilendirmedir.

Hatalı araç şeması

OpenAPI spesifikasyonunuzda amount sent cinsinden integer’dır. Ajan araç tanımında ise amount dolar cinsinden decimal olarak yazılmıştır.

Sonuç:

{
  "amount": 19
}
Enter fullscreen mode Exit fullscreen mode

Bu değer API tarafında 19 sent, ajan tarafında 19 dolar olarak yorumlanabilir.

Model yanlış yapmadı. Ona verdiğiniz şemayı kullandı. Şema API’den sapmıştı ve kimse sözleşme testi çalıştırmamıştı.

Eksik rate limit

Ajan bir işlemi “henüz başarılı değil” olarak işaretler ve aynı e-posta uç noktasını iki dakika içinde binlerce kez çağırır.

Sonuç:

  • Sağlayıcı hesabınızı işaretler
  • Müşteriler spam alır
  • Token ve API maliyeti artar
  • Olay fark edilene kadar hasar büyür

Model kötü niyetli değildir. Sınırı olmayan bir araç kullanıyordur.

Eksik idempotency

Ajan POST /payments çağırır. Ağ zaman aşımı alır. Planlayıcı çağrının başarısız olduğunu düşünür ve yeniden dener.

Müşteri iki kez ücretlendirilir.

API, ajana “bu işlem zaten işlendi” deme yolu vermemiştir. Idempotency-Key başlığı bu problemi küçük bir middleware ile çözebilir; ancak bilinçli olarak tasarlanmalıdır.

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

Aşağıdaki dört kontrol, ajanların güvenli şekilde başarısız olmasını sağlar.

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

OpenAPI spesifikasyonunuz API’nin gerçek sözleşmesidir. Ajanın araç tanımı ise çoğu zaman elle yazılır veya dokümandan kopyalanır. Bu iki kaynak zamanla sapar.

Her PR’da bu farkı yakalayın.

Minimal 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ı 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ığı: "
                    f"API={api_def.get('type')} araç={tool_def_prop.get('type')}"
                )

    return errors
Enter fullscreen mode Exit fullscreen mode

CI’da kullanım örneği:

python scripts/check_agent_tool_schema.py
Enter fullscreen mode Exit fullscreen mode

Kural basit olmalı:

  • Liste boşsa geç
  • Hata varsa build’i durdur
  • Uyarı olarak bırakma

Bu kontrol, amount gibi para alanlarındaki tip veya anlam kaymasını üretime çıkmadan yakalar.

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

Ajanların pratik yapacağı bir ortama ihtiyacı vardır. Bu ortam üretim olmamalıdır.

Durum değiştiren her endpoint için mock karşılığı oluşturun:

  • POST
  • PUT
  • PATCH
  • DELETE

Mock endpoint aynı yanıt şeklini döndürmeli; ancak gerçek veritabanı, ödeme sağlayıcısı veya e-posta servisine dokunmamalıdır.

Apidog, OpenAPI spesifikasyonundan doğrudan mock endpoint’ler oluşturabilir. Geliştirme sırasında ajanın base URL’ini mock sunucuya yönlendirin.

Örnek:

API_BASE_URL=https://mock.apidog.com/m1/project-id
Enter fullscreen mode Exit fullscreen mode

Ajan yanlışlıkla /users/{id}/delete gibi bir endpoint’e istek gönderirse mock bunu yakalar; üretim veritabanı bu hatayı görmez.

Bu yaklaşımın API geliştirme sürecindeki yeri için sözleşme-öncelikli geliştirme rehberine bakabilirsiniz.

3. Yazma işlemleri için idempotency ve mantıksal silme

Ajanın çağırabileceği her yazma endpoint’i Idempotency-Key kabul etmelidir.

Özellikle şu işlemler için zorunlu hale getirin:

  • Ödeme alma
  • İade oluşturma
  • E-posta gönderme
  • Kullanıcı oluşturma
  • CRM kaydı açma
  • Bilet güncelleme
  • Silme işlemleri

Express middleware örneği:

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);
Enter fullscreen mode Exit fullscreen mode

Ajan tarafında her mantıksal işlem için UUID üretin:

const idempotencyKey = crypto.randomUUID();

await fetch(`${API_BASE_URL}/payments`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey
  },
  body: JSON.stringify({
    customer_id: "cus_123",
    amount: 1900
  })
});
Enter fullscreen mode Exit fullscreen mode

Retry sırasında aynı key kullanılmalıdır. Böylece ikinci çağrı yeni işlem oluşturmak yerine önceki yanıtı döndürür.

Silme işlemleri için ayrıca varsayılan davranışı mantıksal silme yapın:

UPDATE users
SET deleted_at = NOW()
WHERE id = $1;
Enter fullscreen mode Exit fullscreen mode

Kalıcı silme için ayrı, insan onaylı bir yol kullanın.

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

Her ajanın bütçesi olmalıdır:

  • Token bütçesi
  • API çağrı bütçesi
  • Zaman bütçesi
  • Dolar / maliyet bütçesi
  • Araç çağrısı derinliği

Örnek limitler:

Limit Başlangıç değeri
Oturum başına token 50.000
Dakika başına API çağrısı 30
Görev başına maliyet 5 dolar
İç içe araç çağrısı 10

Limit aşılırsa API gateway şu şekilde yanıt vermelidir:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-Budget-Exceeded: api_calls_per_minute
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "error": "budget_exceeded",
  "limit": "api_calls_per_minute",
  "retry_after_seconds": 60
}
Enter fullscreen mode Exit fullscreen mode

Ajan planlayıcısı bu durumda:

  1. Görevi durdurmalı
  2. Olayı loglamalı
  3. Gerekirse insana eskale etmeli

Bu dört kontrol birlikte çalışır:

  • Sözleşme testleri şema hatalarını yakalar
  • Mock sunucular yıkıcı hataları izole eder
  • Idempotency retry fırtınalarını güvenli hale getirir
  • Bütçe limitleri sonsuz döngüleri durdurur

Hedef şudur: “ajan korkunç bir şey yaptı” yerine “ajan 429 aldı, olayı kaydetti ve yardım istedi.”

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

Şimdi uygulama adımlarına geçelim.

Gerekenler:

  • Ajanın çağırdığı API için OpenAPI spesifikasyonu
  • Ajan araç tanımlarının listesi
  • Test ortamı değişkenleri
  • Mock veya staging hedefi

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

Apidog’da yeni proje oluşturun ve OpenAPI 3.x dosyanızı içe aktarın.

Apidog şu kaynakları projeye dönüştürür:

  • Path’ler
  • Method’lar
  • Request body şemaları
  • Response şemaları
  • Örnekler
  • Parametreler

API’niz henüz OpenAPI ile belgelenmemişse önce bunu düzeltin. Ajan güvenilirliği, hem geliştiricilerin hem de yapay zeka ajanlarının okuyabileceği tek bir doğruluk kaynağına bağlıdır.

Sıfırdan başlıyorsanız tasarım öncelikli API iş akışı rehberi iyi bir başlangıçtır.

Adım 2: Yıkıcı endpoint’ler için mock yanıtlar oluşturun

Veriyi değiştiren endpoint’leri listeleyin:

POST   /payments
POST   /refunds
PATCH  /users/{id}
DELETE /users/{id}
POST   /notifications
Enter fullscreen mode Exit fullscreen mode

Her biri için mock yanıt ekleyin.

Mock veriler üretim verisine benzememelidir. Loglarda sızıntı olursa hemen anlaşılması için ayırt edici değerler kullanın:

{
  "id": "mock_user_123",
  "email": "mock_user_123@example.test",
  "created_at": "1970-01-01T00:00:00Z"
}
Enter fullscreen mode Exit fullscreen mode

Ardından mock sunucuyu başlatın. Apidog size sabit bir URL verir:

https://mock.apidog.com/m1/your-project-id/
Enter fullscreen mode Exit fullscreen mode

Ajan geliştirme ortamında base URL’i değiştirin:

API_BASE_URL=https://mock.apidog.com/m1/your-project-id/
Enter fullscreen mode Exit fullscreen mode

Artık DELETE /users/{id} çağrısı gerçek kullanıcı silmez; mock payload ile yanıt döndürür.

Adım 3: Ajan çağrı dizisini senaryo olarak yazın

Apidog senaryoları, API çağrılarını assertion’larla zincirlemenizi sağlar.

Örneğin destek biletlerini önceliklendiren bir ajan için senaryo:

  1. POST /auth/token ile test token’ı al
  2. GET /tickets?status=open ile açık biletleri çek
  3. İlk biletin id değerini değişkene yaz
  4. POST /tickets/{id}/triage çağır
  5. 200 döndüğünü doğrula
  6. assigned_to alanını yakala
  7. POST /notifications ile mesaj oluştur
  8. Mesaj gövdesinin regex ile beklenen formatta olduğunu doğrula

Örnek assertion mantığı:

pm.test("triage başarılı olmalı", function () {
  pm.response.to.have.status(200);
});

pm.test("assigned_to boş olmamalı", function () {
  const body = pm.response.json();
  pm.expect(body.assigned_to).to.not.be.empty;
});
Enter fullscreen mode Exit fullscreen mode

Bu senaryo, ajanın üretimde yapacağı çağrı dizisinin provasını mock veya staging ortamında çalıştırır.

Daha kapsamlı senaryo test yaklaşımı için QA mühendisleri için API testi rehberine bakabilirsiniz.

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

Senaryoları PR pipeline’ına bağlayın.

Örnek komut:

apidog run -t scenario-id --env test
Enter fullscreen mode Exit fullscreen mode

GitHub Actions örneği:

name: Agent API Contract Tests

on:
  pull_request:
    paths:
      - "openapi/**"
      - "agent-tools/**"
      - "src/api/**"

jobs:
  api-agent-tests:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run Apidog scenario
        run: apidog run -t ${{ secrets.APIDOG_SCENARIO_ID }} --env test
Enter fullscreen mode Exit fullscreen mode

Kural:

  • OpenAPI değişirse test çalışır
  • Ajan araç tanımı değişirse test çalışır
  • API implementation değişirse test çalışır
  • Senaryo başarısızsa merge yok

Adım 5: Model sürümlerini yan yana karşılaştırın

Bir modelden diğerine geçerken yalnızca yanıt kalitesini değil, araç çağrılarını da karşılaştırın.

Akış:

  1. A modelini kullanarak aynı senaryoyu çalıştırın
  2. Tool call trace’i kaydedin
  3. B modelini kullanarak aynı senaryoyu çalıştırın
  4. Request body, header ve parametreleri diff edin

Yakalanabilecek farklar:

  • B modeli priority alanını farklı değerle gönderir
  • Tarih formatı değişir
  • Opsiyonel sanılan zorunlu alan atlanır
  • Aynı endpoint iki kez çağrılır
  • Farklı sıralamada işlem yapılır

Bu desen, yeni model davranışını değerlendirmenin önemli olduğu GPT-5.5 API entegrasyonu bağlamında da kullanışlıdır.

Gelişmiş teknikler ve profesyonel ipuçları

Testlerde sıcaklığı sıfıra sabitleyin

Araç çağrısı davranışını test ederken deterministik sonuç isteyin:

{
  "temperature": 0
}
Enter fullscreen mode Exit fullscreen mode

Yaratıcılığı değil, entegrasyon davranışını test ediyorsunuz.

Tool call trace’lerini snapshot olarak saklayın

Her test çalıştırmasında şunları kaydedin:

  • Çağrılan endpoint
  • Method
  • Header’lar
  • Request body
  • Response status
  • Tool call sırası

Örnek snapshot:

[
  {
    "method": "GET",
    "path": "/tickets?status=open"
  },
  {
    "method": "POST",
    "path": "/tickets/t_123/triage",
    "body": {
      "category": "billing",
      "priority": "high"
    }
  }
]
Enter fullscreen mode Exit fullscreen mode

Ajan bir endpoint’i bir kez yerine iki kez çağırmaya başlarsa bunu faturadan önce fark edersiniz.

Ajanlara doğrudan üretim kimlik bilgisi vermeyin

Üretim credential’ları:

  • .env içinde olmamalı
  • Ajan tarafından okunabilir olmamalı
  • Uzun ömürlü olmamalı

Ajan üretim endpoint’i çağıracaksa proxy kullanın. Proxy kısa ömürlü token üretir, kapsamı sınırlar ve loglama yapar.

Okuma ve yazma anahtarlarını ayırın

Çoğu ajan görevi okuma ağırlıklıdır.

Bu yüzden:

  • Read-only key verin
  • Write key’i ayrı tutun
  • Write işlemleri için insan onayı veya ek policy uygulayın

Bu değişiklik, ele geçirilmiş veya prompt injection’a uğramış bir ajanın etki alanını ciddi şekilde azaltır.

İnsan onayı gerektiren endpoint’ler için HTTP 423 kullanın

Bir ajan onay gerektiren işlem yapmaya çalışırsa:

HTTP/1.1 423 Locked
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode 
{
  "error": "human_approval_required",
  "confirmation_url": "https://internal.example.com/approve/req_123"
}
Enter fullscreen mode Exit fullscreen mode

403 Forbidden, “bunu yapamazsın” anlamına gelir.

423 Locked, “bunu henüz yapamazsın” demek için daha uygundur.

Şema kaymasında kapalı başarısız olun

Araç tanımı OpenAPI ile eşleşmiyorsa:

  • Warning üretmeyin
  • Build’i durdurun
  • Merge’i engelleyin

Birkaç başarısız build’in maliyeti, bir üretim olayından düşüktür.

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

  • Mock URL’i prompt içine sabit kodlamak
  • “Küçük” endpoint’lerde idempotency atlamak
  • Üretimde tam request body loglamak
  • PII, token veya e-posta adreslerini loglarda maskelememek
  • Ajanlara doğrudan veritabanı erişimi vermek
  • Ajanın güven puanını API güvenliği sanmak

Ajanınız tek bir API gateway arkasında olmayan dahili servislerle konuşuyorsa, mikro hizmetler test modelleri senaryoları servisler arasında nasıl dağıtacağınızı açıklar.

Alternatifler ve araçlar

Yaklaşım Kurulum Süresi Güçlü Yön Zayıf Yön En İyisi İçin
Elle yazılmış birim testleri Düşük Tam kontrol, satıcıya bağımlılık yok Yüksek bakım, gerçek API’den sapması kolay Küçük projeler, tek geliştiricili ekipler
LangSmith / LangGraph değerlendirme aracı Orta İzleme tekrarı, model farkındalıklı metrikler Ajan tarafı güçlü, API tarafı hafif Değerlendirme odaklı AI ekipleri
Postman + Postbot Orta Tanıdık UI, geniş şablon kütüphanesi Mock sunucu ücretli eklenti olabilir, senaryo sözdizimi eski Zaten Postman kullanan ekipler
Apidog senaryoları + mock’lar Orta Yerel OpenAPI, mock’lar, CI için senaryo CLI Postman kadar bilinir değil Tasarım, mock ve testleri tek araçta isteyen ekipler

LangSmith kullanıyorsanız ajan tarafı değerlendirmeleri orada tutup API tarafı sözleşme ve senaryo testlerini ayrı çalıştırabilirsiniz.

Postman’ın fiyatlandırması veya mock modeli ihtiyaçlarınızı karşılamıyorsa Apidog güçlü bir alternatiftir.

Sıfırdan başlıyorsanız OpenAPI, mock ve senaryoları aynı projede yöneten bir araç seçmek işleri basitleştirir.

Gerçek dünya kullanım örnekleri

Ajan üretim veritabanı satırlarını güncelliyor

Bir müşteri başarısı ekibi, destek biletlerinden hesap alanlarını güncelleyen bir ajan geliştirdi.

Yayına almadan önce:

  • Her yazma endpoint’i için idempotency zorunlu hale getirildi
  • Sanal veritabanına karşı Apidog’da 200 senaryo tekrarlandı
  • subscription_status alanına enum dışı değer yazılmaya çalışılan iki durum yakalandı
  • Şema doğrulaması eklendi

Sonuç: ajan üretime daha kontrollü çıktı.

Ajan ödeme API’sini çağırıyor

Otomatik iade ajanı geliştiren bir fintech ekibi şu limitleri koydu:

  • Oturum başına en fazla 5 iade
  • İade başına en fazla 50 dolar
  • Her çağrıda idempotency zorunlu
  • Her PR’da Stripe OpenAPI’sine karşı sözleşme test paketi

Bu yapı, çift ücretlendirme riskini azaltmak için API katmanında net sınırlar sağladı.

Ajan GitHub issue’larını önceliklendiriyor

Bir platform ekibi, Clawsweeper’dan esinlenerek issue triage ajanı geliştirdi.

Uyguladıkları testler:

  • GitHub API’sini Apidog’da mock’lama
  • Silinmiş issue
  • Eksik label
  • Hatalı kullanıcı girdisi
  • Yetkisiz kullanıcı
  • Boş yorum gövdesi

Lansmandan önce 50 senaryo çalıştırıldı ve üç çökme üretime çıkmadan yakalandı.

Sonuç

Bu rehberden tek şey alacaksanız şu olsun: sorun çoğu zaman ajan değildir. Sorun, API’nin güvenli ve test edilebilir tasarlanmamış olmasıdır.

Uygulanabilir kontrol listesi:

  • Araç şemalarını sözleşme olarak ele alın
  • OpenAPI ile araç tanımlarını CI’da karşılaştırın
  • Yıkıcı endpoint’leri mock ortamda test edin
  • Her yazma işlemi için Idempotency-Key isteyin
  • Ajan başına token, istek, zaman ve maliyet limiti koyun
  • Hata senaryolarını her PR’da tekrar oynatın
  • Üretim credential’larını ajanlardan uzak tutun
  • Read ve write anahtarlarını ayırın

Bu yılki viral olaylar son olmayacak. Ajan gönderen her ekip bu hata modlarından en az biriyle karşılaşacak. Hızlı toparlanan ekipler, güvenlik önlemlerini olaydan önce kuran ekipler olacak.

Başlamak için Apidog’u indirin ve ilk olarak mock sunucu adımını kurun. QA tarafındaki ek perspektif için QA mühendisleri için API test araçları rehberine, ajanların güvenle kullanabileceği araç tanımları için de AGENTS.md dosyaları nasıl yazılır yazısına bakabilirsiniz.

SSS

Token harcamadan yapay zeka ajan API çağrılarını nasıl test ederim?

Geliştirme sırasında ajanı mock sunucuya yönlendirin. Apidog mock URL’leri gerçekçi yanıtlar döndürür; böylece test döngüleri gerçek API kredisi tüketmez. Sıcaklığı 0 yapın ve küçük, sabit prompt seti kullanın. Daha ayrıntılı kontrol listesi için QA mühendisinin test kontrol listesi yazısına bakabilirsiniz.

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 ise endpoint’in çağrıldığında doğru davranıp davranmadığını doğrular.

İkisi ayrı katmanlardır. Bozuk API’yi çağıran iyi ajan da hatalı sonuç üretir. İyi API’yi çağıran bozuk ajan da yanlış işlem yapabilir.

Her endpoint’te idempotency gerekir mi?

Her yazma endpoint’inde gerekir. Okuma işlemleri doğası gereği idempotent’tir. Yazma işlemleri değildir ve ajanlar retry yapar.

Özellikle ödeme, iade, e-posta, mesajlaşma ve kayıt oluşturma endpoint’lerinde Idempotency-Key zorunlu olmalıdır.

Yanlış API çağrılarını tetikleyen prompt injection’ı nasıl önlerim?

Yalnızca prompt’a güvenmeyin. API, yetkilendirmeyi ajanın isteğine göre değil, orijinal kullanıcı bağlamına göre uygulamalıdır.

Bir kullanıcı normalde /admin/delete-all-users endpoint’ine erişemiyorsa, o kullanıcı adına hareket eden ajan da erişememelidir.

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

Test sırasında ajan araç tanımlarındaki HTTP base URL’i Apidog mock URL’ine yönlendirebilirsiniz. Claude ve GPT tarafında araç tanımlarında farklı base URL kullanımı ortam değişkeniyle yönetilebilir.

Hazırlık veya üretim ortamını test etmek istediğinizde yalnızca değişkeni değiştirirsiniz.

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

Katı başlayın, metriklerle gevşetin.

Başlangıç değerleri:

  • Oturum başına 50.000 token
  • Dakika başına 30 API çağrısı
  • Görev başına 5 dolar
  • En fazla 10 iç içe araç çağrısı

İki hafta izleyin. Gerçek iş akışını engelleyen limitleri artırın. Hiç yaklaşılmayan limitleri düşürün. Ama limitleri tamamen kaldırmayın.

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

Her PR’da CI içinde şema farkı çalıştırın.

Karşılaştırılacak kaynaklar:

  • Ajan araç tanımı JSON Schema
  • Aynı endpoint’in OpenAPI request body şeması

Fark varsa build’i başarısız kılın. Yukarıdaki Python örneğini reponuza ekleyip GitHub Actions veya GitLab CI’a bağlayabilirsiniz.

Top comments (0)