Bir yapay zeka aracısının güvenilirliği, çağırdığı API'ler kadardır. Model bir araç seçer, argümanları doldurur ve bir istek gönderir; eğer bu istek başarısız olursa, yanlış formatta dönerse veya takılırsa, aracınız kötü verilere dayanarak kendinden emin bir karar verir. Çoğu aracı demosu bu kısmı atlar. Üretimdeki aracılar bu kısma bağlı olarak hayatta kalır veya ölür.
Bu rehber, gerçek araçları çağıran bir aracıyı nasıl oluşturacağınızı ve daha da önemlisi, Apidog'u hem API katmanı hem de arkasındaki test düzeni olarak nasıl kullanacağınızı göstermektedir. Araç uç noktalarını tasarlayacak, çevrimdışı geliştirme yapabilmeniz için onları taklit edecek ve kullanıcıya ulaşmadan bozuk bir araç çağrısını yakalayan onaylamalar yazacaksınız. Amaç, tek seferlik bir "mutlu yol" çalıştığı için değil, test ettiğiniz için güvenebileceğiniz bir aracı elde etmektir.
Bir aracının API katmanında gerçekten ne yaptığı
Çerçeveyi kaldırdığınızda, bir aracı döngüsü basittir:
- Model bir kullanıcı hedefini ve araç listesini alır.
- Bir araç çağrısı döndürür: bir araç adı artı JSON argümanları.
- Kodunuz bu çağrıyı yürütür; genellikle bir API'ye bir HTTP isteği.
- Sonuç modele geri döner.
- Model ya başka bir aracı çağırır ya da yanıt verir.
Her ilginç hata 3. ve 4. adımda meydana gelir. Model bir argümanı halüsinasyon olarak görür, API bir 422 döndürür, yanıt şeması kayar, çağrı zaman aşımına uğrar veya döngünün ortasında bir hız limiti devreye girer. Yeni API tüketicileri olarak yapay zeka aracılarından bahseden yazıyı okuduysanız, bu fikrin somut hali budur: aracınız API'lerinizi kullanan bir istemcidir ve diğer tüm istemciler gibi aynı test titizliğini hak eder.
Yani iş ikiye ayrılır: araçları gerçek, test edilebilir API işlemleri olarak tanımlamak, ardından aracının hem iyi hem de kötü koşullar altında bunları doğru şekilde çağırdığını doğrulamak.
Adım 1: Araçları gerçek API işlemleri olarak tasarlayın
Tek bir satır aracı kodu yazmadan önce, her aracıyı Apidog'da bir API uç noktası olarak tanımlayın. Araç şeması ile API şemasını aynı şey olarak ele alın, çünkü öyleler. Bir `get_weather` aracı ve `GET /weather` uç noktası aynı sözleşmeyi paylaşır: aynı parametreler, aynı yanıt şekli.
Apidog'da, her araç için OpenAPI şemasıyla bir uç nokta oluşturun; yol, sorgu ve gövde parametreleri ve tipik bir yanıt. Bu size üç şeyi ücretsiz olarak sağlar:
- Hem aracı isteminizin hem de testlerinizin okuduğu aracın sözleşmesi için tek bir doğruluk kaynağı.
- Model'e araç tanımı olarak sunabileceğiniz otomatik olarak oluşturulmuş dokümantasyon.
- Daha sonra doğrulamak için bir şema, böylece bir yanıtın eşleşmeyi bıraktığı anda kaymayı yakalarsınız.
Bu şema-öncelikli alışkanlık, genel olarak sağlam API tasarım çalışmalarının arkasındakiyle aynıdır. Aracılar için geri dönüş spesifiktir: araç tanımınız ve gerçek uç noktanız tek bir şemadan geldiğinde, model API'nizin desteklemediği bir aracı çağıramaz.
Adım 2: Çevrimdışı geliştirebilmek için araçları taklit edin
Her geliştirme çalıştırmasının para maliyeti olan, hız limitleri uygulayan veya henüz oluşturulmamış canlı API'leri vurmasını istemezsiniz. Apidog, az önce tanımladığınız şemadan doğrudan bir sahte sunucu (mock server) oluşturur. Her araç uç noktası, herhangi bir arka uç olmadan gerçekçi, şema-geçerli örnek verileri döndürür.
Bu, aracıları nasıl oluşturduğunuzu değiştirir. Şunları yapabilirsiniz:
- Gerçek API'ler mevcut olmadan önce, kararlaştırılan sözleşmeyle eşleşen sahte yanıtlarla tam aracı döngüsünü geliştirin.
- Ücretli bir uç noktaya asla dokunmayan CI'da entegrasyon testleri çalıştırın.
- Aracınızın nasıl tepki verdiğini görmek için belirli yanıtları zorlayın; boş bir sonuç, bir 500 hatası, hatalı biçimlendirilmiş bir alan.
Geliştirme sırasında aracınızın araç yürütücüsünü sahte temel URL'ye yönlendirin. Model `get_weather`'ı çağırır, kodunuz Apidog sahte sunucusuna ulaşır ve geçerli bir yanıt anında geri döner. Gerçek şeye hazır olduğunuzda, temel URL'yi bir ortam değişkeni aracılığıyla değiştirin. Taklit (mocking), aracı geliştirmeyi hızlı ve deterministik hale getiren şeydir; aynı yaklaşım, herhangi bir ciddi yapay zeka aracı testi iş akışını güçlendirir.
Adım 3: Aracıyı araçları çağıracak şekilde bağlayın
Uç noktalar ve sahte yanıtlar yerleştirildiğinde, aracı kodu ince kalır. İşte Claude Messages API'sini kullanarak bir araç çağırma döngüsünün şekli; araç tanımları, Apidog'da oluşturduğunuz şemaları yansıtır.
import anthropic, requests, os
client = anthropic.Anthropic()
TOOL_BASE = os.environ["TOOL_BASE_URL"] # Apidog mock during dev, real API in prod
tools = [{
"name": "get_weather",
"description": "Get current weather for a city",
"input_schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
}]
def run_tool(name, args):
if name == "get_weather":
r = requests.get(f"{TOOL_BASE}/weather", params={"city": args["city"]}, timeout=10)
r.raise_for_status()
return r.json()
messages = [{"role": "user", "content": "What should I wear in Tokyo today?"}]
while True:
resp = client.messages.create(
model="claude-fable-5", max_tokens=1024, tools=tools, messages=messages
)
if resp.stop_reason == "tool_use":
block = next(b for b in resp.content if b.type == "tool_use")
result = run_tool(block.name, block.input)
messages.append({"role": "assistant", "content": resp.content})
messages.append({"role": "user", "content": [{
"type": "tool_result", "tool_use_id": block.id,
"content": str(result),
}]})
else:
print(resp.content[0].text)
break
`timeout=10` ve `raise_for_status()` satırları model çağrısından daha önemlidir. Bunlar, yüksek sesle başarısız olan bir aracı ile takılıp kalan veya hatalı bir isteği döngüye sessizce geri besleyen bir aracı arasındaki farktır. Aracılarının API iş akışlarına nasıl uyduğuna dair daha geniş bir görüş için, API iş akışınız için 5 yapay zeka aracısı içindeki desenler faydalı bir eşlikçidir.
Adım 4: Sadece hissiyatları değil, araç çağrılarını test edin
Çoğu ekibin atladığı kısım burası. Her araç uç noktasını Apidog'da kaydedilmiş bir istek olarak, modelden bağımsız olarak onaylamalarla çalıştırın. Aracının güvenilirliği, araçlarının güvenilirliği ile sınırlıdır, bu yüzden önce araçları test edin.
Her araç uç noktası için şunları onaylayın:
- Geçerli giriş için durum `200`'dür.
- Yanıt gövdesi şemayla eşleşir; Apidog yanıtı OpenAPI tanımınıza göre otomatik olarak doğrular.
- Modelin okuyacağı gerekli alanlar mevcuttur ve doğru tipte yazılmıştır.
- Yanıt süresi, aracınızın uyguladığı zaman aşımı içinde kalır.
Ardından, "mutsuz yolları" test edin, çünkü aracılar buralarda yanlış davranır:
- Modelin halüsinasyon olarak görebileceği hatalı argümanları gönderin; boş bir `city` (şehir), bir dizenin olması gereken bir sayı; ve temiz bir `400`/`422` aldığınızı, bir `500` almadığınızı onaylayın.
- Sahte yanıttan bir hata yanıtı zorlayın ve aracınızın `run_tool`'unun anlamsız veriler döndürmek yerine hata fırlattığını doğrulayın.
- Boş bir sonucu test edin ve aracının bir yanıt uydurmak yerine "veri yok" durumunu nasıl ele aldığını kontrol edin.
Bu, aracı araçlarına uygulanan sözleşme testidir; API sözleşme testinde ele alınan aynı disiplin, modelinizin çağırdığı uç noktalara yöneliktir. Bir aracın yanıt şekli kaydığında, CI'da onaylama başarısız olur ve aracı bozuk bir yük üzerinde akıl yürütmeye başlamadan önce düzeltirsiniz.
Adım 5: Yeniden denemeleri, zaman aşımlarını ve hız limitlerini yönetin
Aracılar, kararsız API'leri güçlendirir. Normal bir uygulamada tek bir yeniden deneme, bir yeniden denemedir; bir aracı döngüsünde, başarısız olan bir aracıyı tekrar tekrar çağıran bir model, hız limitinizi ve bütçenizi hızla tüketebilir. Kontrolleri oluşturun ve test edin:
- Zaman aşımları. Yukarıdaki örnekte olduğu gibi, her araç isteğinde açık bir zaman aşımı ayarlayın. Ardından, yavaş bir uç noktayı simüle etmek için Apidog'u kullanın ve istemcinizin tüm döngüyü askıda bırakmak yerine temiz bir şekilde vazgeçtiğini doğrulayın.
- Geri çekilmeli yeniden denemeler. Geçici başarısızlıkları yeniden deneyin, ancak sayıyı sınırlayın ve geri çekilin. İki kez başarısız olup ardından başarılı olan bir sahte yanıtla test edin ve aracınızın sonsuz döngüye girmek yerine kurtulduğunu onaylayın.
- Hız limitleri. Yük altında `429` bekleyin. Hız sınırlı bir yanıtı taklit edin ve aracınızın zorlamaktan ziyade bekleyip yeniden denediğini doğrulayın. Bunu ham model API'lerinde ele aldıysanız; aynı sınıf sorun için GPT API hız limitlerine bakın; aracı sürümü daha katıdır çünkü döngü her çağrıyı katlar.
- Devre kesme. Bir araçta N sayıda hatadan sonra, onu çağırmayı durdurun ve aracının dönmek yerine hatayı bildirmesini sağlayın. Kesicinin devreye girdiğini test edin.
Bunları Apidog'da tekrarlanabilir senaryolar olarak çalıştırın, böylece hata yönetiminizdeki bir regresyon, bir üretim olayı değil, başarısız bir test olarak ortaya çıkar.
Adım 6: CI'da sahte yanıtlarla uçtan uca çalıştırın
Her şeyi bir araya getirin. CI'da, aracınızı Apidog sahte sunucusuna yönlendirerek başlatın, ona belirli bir kullanıcı hedefleri kümesi besleyin ve nihai sonuç ile araç çağrıları dizisini onaylayın. Sahte yanıtlar deterministik olduğu için, aynı giriş her çalıştırmada aynı araç çağrılarını üretir, böylece aracı testleriniz kararsız olmayı bırakır. Güvendiğinizde, daha küçük bir canlı "smoke test" için temel URL'yi gerçek API'lere geçirin. Bu ayrım; testlerin çoğu için deterministik sahte yanıtlar, gerçeklik için ince bir canlı kontrol; agentic AI testing'i ideal olmaktan çıkarıp pratik hale getiren şeydir.
Güvenilir bir aracı için kontrol listesi
- [ ] Her araç, OpenAPI şeması ile gerçek bir API işlemi olarak tanımlanmıştır.
- [ ] Her araç için sahte yanıtlar mevcuttur, böylece çevrimdışı geliştirebilir ve test edebilirsiniz.
- [ ] Her araç uç noktasının durumu, şeması ve zamanlaması hakkında onaylamaları vardır.
- [ ] "Mutsuz yollar"; hatalı argümanlar, hatalar, boş sonuçlar; açıkça test edilmiştir.
- [ ] Zaman aşımları, geri çekilmeli yeniden denemeler ve hız limiti yönetimi kodda mevcuttur ve test edilmiştir.
- [ ] Uçtan uca bir CI çalıştırması, tam döngüyü deterministik sahte yanıtlarla uygular.
Tüm altısını da sağladığınızda, güvenilirliğini umutla değil, kanıtlarla açıklayabileceğiniz bir aracıya sahip olursunuz.
SSS
Neden sadece aracıyı çalıştırmak yerine bir API istemcisi kullanarak bir aracıyı test edeyim? Aracıyı çalıştırmak, modeli ve araçları birlikte test eder, bu yüzden bir başarısızlık belirsizdir. Her araç uç noktasını Apidog'da test etmek, API katmanını izole eder, böylece bir sorunun modelin akıl yürütmesinden mi yoksa bozuk bir araçtan mı kaynaklandığını bilirsiniz.
Aracıyı oluşturmadan önce gerçek API'leri oluşturmak zorunda mıyım? Hayır. Araç sözleşmelerini Apidog'da şema olarak tanımlayın, sahte yanıtlar oluşturun ve tüm aracı döngüsünü bu sahte yanıtlarla oluşturun. Gerçek uç noktaları daha sonra bir ortam değişkeni aracılığıyla değiştirin.
Aracımın başarısız olan bir araçta sonsuza kadar döngüye girmesini nasıl durdururum? Yeniden denemeleri sınırlayın, geri çekilme ekleyin ve tekrarlanan başarısızlıklardan sonra bir devre kesiciyi devreye sokun, böylece aracı dönmek yerine sorunu bildirir. Her kontrolü hatalar döndüren bir sahte yanıtla test edin.
Model ve API çağrıları için para harcamadan aracıyı test edebilir miyim? Çoğunlukla evet. Deterministik, ücretsiz entegrasyon testleri için Apidog'daki araç API'lerini taklit edin ve canlı model çağrılarını küçük bir "smoke test" paketine saklayın.
Bu, LangChain veya Claude Agent SDK gibi çerçevelerle çalışır mı? Evet. Araç katmanı sadece HTTP'dir. Döngüyü hangi çerçeve yönlendirirse yönlendirsin, test için araç çağrılarını Apidog sahte yanıtlarına ve üretim için gerçek uç noktalara yönlendirin. Böyle bir döngü için Claude Kod SDK rehberine bakın.
Sonuç
Güvenilir bir aracı daha akıllı bir istemci değildir; test edilmiş bir araç katmanıdır. Araçlarınızı gerçek API işlemleri olarak tanımlayın, geliştirmeyi hızlı ve deterministik hale getirmek için onları taklit edin, her yanıt şeklini onaylayın ve başarısızlıkları kasıtlı olarak test edin. Apidog size bu uç noktaları tasarlamak, taklit etmek ve bir test düzeni olarak çalıştırmak için tek bir yer sunar, böylece aracınızın davranışını kanıtlayabilirsiniz. Apidog'u indirin ve üretimde gerçekten güvenebileceğiniz aracıyı oluşturun.