Çoğu aracı kod tabanı, kimsenin sürdürmekten hoşlanmadığı bir dosya içerir. Kırk araç tanımı barındırır ve her biri, zaten başka bir yerde şeması olan bir uç noktayı tanımlayan el yazımı bir JSON şemasıdır. API ekibi yeni bir zorunlu alan gönderir, spesifikasyon güncellenir, belgeler güncellenir ve birisi 400 hatalarını fark edene kadar aracı eski yükü göndermeye devam eder.
Her uç noktanın makine tarafından okunabilir bir açıklamasına zaten sahipsinizdir. Bu, OpenAPI belgesidir. Görev, bunu modelin çağırabileceği araç tanımlarına dönüştürmek ve ikisini manuel olarak değil, otomatik olarak senkronize tutmaktır.
Bu rehber, OpenAPI işlemlerinin araç şemalarına nasıl eşlendiğini, oluşturucunun bu süreçte neleri düzeltmesi gerektiğini, 200 uç noktalık bir spesifikasyonu modelin anlayabileceği bir şeye nasıl indireceğinizi ve oluşturulan araçların davranışını nasıl test edeceğinizi kapsar. Eğer bu konuda daha erken aşamadaysanız, ajanlar kodu yazarken API aracına hala ihtiyaç duyup duymadığınıza dair yazımız daha geniş bir bağlam sunar.
Apidog burada önemlidir, çünkü ondan üretilen herhangi bir şey doğru olmadan önce spesifikasyonun doğru olması gerekir. Bir araç tanımı, geldiği belgedeki her boşluğu miras alır.
El yazımı araç tanımlarının maliyeti
Beş uç nokta için araçları elle yazmak iyi hissettirir. Üç nedenden dolayı yirmi civarında bir yerde iyi hissetmeyi bırakır.
Tanımlar kayar. Spesifikasyon koddan üretilir veya API ekibi tarafından sürdürülür. Araç dosyası, ajanı oluşturan kişi tarafından sürdürülür. Hiçbir şey onları birbirine bağlamaz, bu yüzden sessizce farklılaşırlar ve ilk belirti "aniden" çalışmayı durduran bir ajandır.
Açıklamalar sığlaşır. Bir kişi kırk şemayı elle yazdığında, son yirmi şema tek satırlık açıklamalara sahip olur. Modeller bu açıklamaları okuyarak araçları seçer, bu nedenle sığ metin doğrudan araç seçimini düşürür. Ajanlar için araç şeması tasarımı hakkındaki yazımız, ifadelerin neden bu kadar önemli olduğunu daha derinlemesine inceler.
Hatalar çalışma zamanına kadar görünmezdir. API bir tamsayı isterken bir alanın dize olduğunu söyleyen el yazımı bir şema, ajan bunu ilk denediğinde, üretimde, gerçek bir görevde bir 422 hatasına neden olur.
Spesifikasyondan üretim, her üçünü de aynı anda düzeltir. Tek bir doğru kaynak vardır, açıklamalar belgelerinizin kullandığı metinden gelir ve türler sunucunun doğruladığı aynı şemadan gelir.
Bir OpenAPI işlemi nasıl araca dönüşür?
Eşleme göründüğünden daha doğrudandır. Tek bir işlemi ele alalım:
paths:
/orders/{orderId}/refund:
post:
operationId: refundOrder
summary: Siparişi iade et
description: >
Tamamlanmış bir siparişe karşı tam veya kısmi iade yapar.
İadeler geri alınamaz. Kısmi iadeler, kalan iade edilebilir
bakiyeden fazla olmayan bir miktar gerektirir.
parameters:
- name: orderId
in: path
required: true
schema: { type: string }
description: İade edilecek sipariş.
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [reason]
properties:
amount:
type: integer
description: Cent cinsinden miktar. Tam iade için boş bırakın.
reason:
type: string
enum: [duplicate, fraudulent, requested_by_customer]
Bundan çıkan araç tanımı:
{
"name": "refundOrder",
"description": "Tamamlanmış bir siparişe karşı tam veya kısmi iade yapar. İadeler geri alınamaz. Kısmi iadeler, kalan iade edilebilir bakiyeden fazla olmayan bir miktar gerektirir.",
"input_schema": {
"type": "object",
"required": ["orderId", "reason"],
"properties": {
"orderId": { "type": "string", "description": "İade edilecek sipariş." },
"amount": { "type": "integer", "description": "Cent cinsinden miktar. Tam iade için boş bırakın." },
"reason": { "type": "string", "enum": ["duplicate", "fraudulent", "requested_by_customer"] }
}
}
}
Dört kural işin çoğunu yapar:
operationIdaracın adı olur. Bir işleminoperationId'si yoksa, metot artı yoldan kararlı bir ad oluşturun ve sonra onu spesifikasyona ekleyin.- Yol, sorgu ve gövde parametreleri tek bir özellik nesnesine düzleştirilir. Model, bir değerin ağda nerede taşındığını umursamaz. Yürütücünüz umursar, bu yüzden hangi parametrenin nereye gittiğini kaydeden bir yan tablo tutun.
summaryartıdescriptionaracın açıklaması olur. Her ikisi de birleştirilir. Sadece özet genellikle seçimi yönlendirmek için çok kısadır.- Zorunlu diziler birleştirilir. Zorunlu bir yol parametresi ve zorunlu bir gövde alanı, aynı
requiredlistesine düşer.
Yürütücü diğer yarıdır ve küçüktür:
def execute(tool_name, args, spec_index, http):
op = spec_index[tool_name] # method, path template, param locations
path = op.path
query, body = {}, {}
for name, value in args.items():
location = op.locations[name] # "path" | "query" | "header" | "body"
if location == "path":
path = path.replace("{" + name + "}", str(value))
elif location == "query":
query[name] = value
elif location == "body":
body[name] = value
return http.request(op.method, path, params=query, json=body or None)
Köprü tamamen budur. Geri kalan her şey, yol boyunca yapılan temizliktir.
Oluşturucunun düzeltmesi gerekenler
Spesifikasyonun araç şemalarına naif bir şekilde dökülmesi, modellerin kötü yönettiği araçlar üretir. Beş ayarlama önemlidir.
$ref işaretçilerini çözümleyin. Çoğu araç çağırma API'si JSON Şeması'nın bir alt kümesini kabul eder ve referansları bir components bölümüne kadar izlemez. Bunları satır içi yapın. Satır içi yapıldığında sonsuza kadar genişleyecek özyinelemeli şemalara dikkat edin; özyinelemeyi sabit bir derinlikte kesin ve daha derin yapıyı düz yazı ile açıklayın.
Desteklenmeyen anahtar kelimeleri bırakın. oneOf, allOf, discriminator ve nullable spesifikasyonlarda yaygındır ve araç şemaları tarafından zayıf bir şekilde desteklenir. Özellikleri birleştirerek allOf'u daraltın. oneOf için, ya baskın varyantı seçin ya da işlemi iki araca, her şekil için bir tane olmak üzere ayırın. Bu ikinci seçenek genellikle daha iyi araç seçimi sağlar.
Derin iç içe geçmiş yapıyı düzleştirin. Üç seviye derinliğinde bir gövdenin bir model tarafından doğru şekilde doldurulması zordur. Eğer sipariş oluşturma yükünüz customer.address.postal_code'u iç içe geçiriyorsa, daha düz bir araç yüzeyi düşünün ve iç içe geçmiş yapıyı yürütücüde yeniden birleştirin.
Yanıt şemalarını budayın. Araç tanımları girdileri açıklar. Tam yanıt şeması tanıma ait değildir ve dahil edilmesi bağlamı boşa harcar. Yanıtın neye benzediği, sonuç geri geldiğinde önemlidir ve bu, API yanıtlarını aracının bağlam penceresinde tutmak hakkındaki yazımızda ele alınan ayrı bir sorundur.
Güvenlik bayraklarını taşıyın. Yazma işlemleri, yürütücünüzün bunları bir onay geçidinden yönlendirebilmesi için işaretlenmelidir. Spesifikasyonunuz x-agent-requires-approval gibi bir uzantı kullanıyorsa, onu okuyun ve uygulayın. Bunu, yapay zeka ajanı koruyucuları rehberimizdeki desenlerle eşleştirin.
Modele 200 uç noktanın hepsini vermeyin
En büyük pratik sorun dönüştürme değildir. Hacimdir. Olgun bir API yüzlerce operasyona sahiptir ve hepsini araç listesine yapıştırmak aynı anda iki hataya yol açar: görev başlamadan önce bağlam şemalarla dolar ve model neredeyse aynı seçenekler arasından seçim yaptığı için seçim doğruluğu düşer.
Kabaca ne kadar iyi çalıştıklarına göre sıralanmış üç azaltma yolu.
Etikete göre filtrele. OpenAPI operasyonları etiketler taşır ve etiketler genellikle ürün alanlarına eşlenir. İadeleri yöneten bir ajan, admin veya analytics etiketlerine değil, orders ve payments etiketlerine ihtiyaç duyar. Bu, tek satırlık bir filtredir ve genellikle yüzeyin çoğunu kaldırır.
Bir izin listesi oluşturun. Bu ajanın çağrı yapmasına izin verilen operasyonları operationId'ye göre yazın ve sadece bunları oluşturun. Bu, bir güvenlik kontrolü olarak da işlev görür, çünkü bir uç nokta için aracı olmayan bir ajan onu kazara çağıramaz. Ajanların API'nizi yok etmesini durdurma hakkındaki yazımız tam da bu tür dar bir yüzeyi savunur.
Araçları talep üzerine geri alın. Çok büyük API'ler için, operasyonları indeksleyin ve göreve bağlı olarak her seferinde birkaç tane seçin. Bu, bir alma adımı ve kendi hata modlarını ekler, bu yüzden filtreleme ve derleme yeterli olmaktan çıktığında buna başvurun.
Bir de protokol yolu var. Model Bağlam Protokolü (MCP), bir sunucunun bir istemciye araçları nasıl açığa çıkaracağını standartlaştırır ve OpenAPI belgenizle desteklenen bir MCP sunucusu, her çerçeve için bir tane yerine size tek bir entegrasyon noktası sunar. MCP'nin ne olduğu hakkındaki açıklayıcımız modeli kapsar ve Apidog ile bir MCP sunucusu oluşturmak yapıyı kapsar.
Önce spesifikasyon doğru olmalı
Üretim, kalite sorununu yukarıya taşır. OpenAPI belgenizdeki belirsiz bir açıklama, belirsiz bir araç açıklaması haline gelir ve model yanlış uç noktayı seçer. Sunucunun aslında zorunlu kıldığı isteğe bağlı bir alan, ajanın ilk denemede yanlış çağrı yapacağı bir araca dönüşür.
Bu yüzden, herhangi bir şey oluşturmadan önce spesifikasyonu bir ajanın gözünden denetleyin:
- Her operasyonun bir
operationId'si vardır ve bu bir fiil artı bir isim gibi okunur. - Her operasyonun ne yaptığını, neyi değiştirdiğini ve ne zaman kullanılmaması gerektiğini belirten bir açıklaması vardır. "Kullanıcıyı siler" yeterli değildir. "Bir kullanıcıyı ve tüm oturumlarını kalıcı olarak siler. Geri alınamaz. Erişimi geçici olarak devre dışı bırakmak için deactivateUser kullanın." yeterlidir.
- Her parametrenin birim ve format içeren bir açıklaması vardır.
amountbelirsizdir. "Cent cinsinden miktar, minimum 50" değildir. - Numaralandırmalar düz yazı ile açıklanmak yerine açıkça belirtilmiştir, böylece model tahmin etmek yerine kapalı bir küme alır.
- Zorunluluk doğrudur. Spesifikasyonlar her şeyi isteğe bağlı olarak işaretlemeye yönelir, bu da doğrulama hatalarını çalışma zamanına iter.
Bu sıradan bir spesifikasyon hijyenidir ve iki kat fayda sağlar, çünkü aynı metin yayınlanmış belgelerinizi de yönlendirir. Apidog'da spesifikasyon, belgeler, sanal sunucu ve testler tek bir projeden gelir, bu nedenle bir açıklamayı sıkılaştırmak hepsini aynı anda iyileştirir. Apidog'da API sürümünü yönetme rehberimiz, oluşturulan araçları zaman içinde dürüst tutmanın diğer yarısını kapsar.
Araç setini paylaşın, kopyalamayın
Oluşturulan bir araç seti bir yapılandırmadır ve tek bir geliştiricinin kontrolünde yaşayan yapılandırma, el yazımı şemaların kaydığı gibi kayar. Filtre listesi, izin listesi ve sabitlenmiş spesifikasyon sürümü, geldikleri spesifikasyonun yanında sürümlendirilen paylaşılan eserler olmalıdır.
Bazı platformlar bunu varsayılan birim yapar. Sharkly'de, bir Ajan tek seferlik bir istem yerine kaydedilmiş bir çalışma yapılandırmasıdır: talimatları, Çalışma Zamanı, Becerileri, depoları ve çalışma ayarları onunla birlikte seyahat eder ve bir Alan içinde paylaşılabilir, böylece çalışan bir araç kurulumu, her kişinin yeniden oluşturduğu bir şey yerine bir ekibin yeniden kullandığı bir şey haline gelir. Alttaki çalışma zamanı hala Claude Code, Codex veya zaten çalıştırdığınız her neyse odur. Değişen şey, etrafındaki yapılandırmanın yerel olmaktan çıkmasıdır.
Oluşturulan araçları test etme
Oluşturulan araçlar, el yazımı olanların yapmadığı şekillerde başarısız olur, bu yüzden hem oluşturmayı hem de çağrıları test edin.
Şema gidiş-dönüş kontrolüyle başlayın. Her oluşturulan araç için, şemadan geçerli bir örnek oluşturun ve gönderin. 400 veya 422 döndüren her şey, araç şemasının ve sunucunun uyumsuz olduğu ve düzeltilmesi gereken şeyin spesifikasyon olduğu anlamına gelir.
Ardından seçimi test edin. Bilinen doğru bir araçla küçük bir görev istemi kümesi yazın, bunları çalıştırın ve modelin hangi aracı seçtiğini kaydedin. Bu, birisinin bir operasyonun adını değiştirdiğinde veya bir açıklamayı kısalttığında ortaya çıkan bir gerileme paketidir. Çıktı deterministik olmadığı için, deterministik olmayan ajanları test etme rehberimizdeki gibi tam argümanlar yerine araç adı üzerinde iddia edin.
Son olarak, canlı bir şeye başlamadan önce ajanı sanal sunuculara karşı çalıştırın. Aynı spesifikasyondan oluşturulan bir sanal sunucu, yan etkileri olmadan gerçekçi yanıtlar verir ve yeniden deneme mantığınızın ele alması gereken 500'leri ve zaman aşımlarını enjekte etmenizi sağlar.
Bu sizi nereye getiriyor?
Spesifikasyon sözleşmedir ve araç listesi, elle sürdürülen paralel bir kopya değil, onun bir yansıması olmalıdır. Araçları oluşturun, sıkıca filtreleyin, açıklamaları dürüst tutun ve hem şekilleri hem de seçimi test edin.
OpenAPI belgenizi dışa aktararak ve açıklaması olmayan operasyonları sayarak başlayın. Bu sayı, sizinle güvenebileceğiniz ajan araçları arasında duran işin ne kadar olduğunu gösterir. Düzeltirken spesifikasyonu, sanal sunucuları ve testleri tek bir yerde istiyorsanız Apidog'u indirin.
Sıkça sorulan sorular
Swagger 2.0 belgesinden araçlar oluşturabilir miyim? Evet, ancak önce onu OpenAPI 3.x'e dönüştürün. 2.0 gövde modeli, oluşturucuların tutarsız bir şekilde ele alması için yeterince farklıdır ve mevcut araçların hedefi 3.x'tir. OpenAPI Spesifikasyon deposu farklılıkları belgeler.
Bir model aynı anda kaç aracı işleyebilir? Doğruluk, teknik sınırdan çok önce düşmeye başlar ve pratik tavan genellikle birkaç düzinedir. Bundan sonraki herhangi bir listeyi, test edilecek bir sınır olarak değil, etikete göre filtreleme veya bir izin listesi oluşturma sinyali olarak kabul edin.
Araç adları operationId ile tam olarak eşleşmeli mi? Evet, operationId okunabilir olduğunda. Bu size araç çağrısından spesifikasyon işlemine doğrudan bir arama sağlar, bu da izlemeyi ve hata ayıklamayı çok daha kolay hale getirir. Ad kötü ise spesifikasyonda yeniden adlandırın, oluşturucuda değil.
GraphQL API'leri ne olacak? Aynı fikir farklı bir kaynakla geçerlidir: şemayı denetleyin ve her sorgu veya mutasyon için bir araç oluşturun. GraphQL şeması daha fazla yüzey açığa çıkardığı için hacim sorunu daha da kötüdür, bu yüzden filtreleme daha da önemlidir.
Hala elle araç yazmam gerekiyor mu? Birkaç tane. Birden fazla çağrıyı tek bir eylemde zincirleyen bileşik araçlar ve HTTP dışındaki bir şeyi saran araçlar hala manuel olarak yazılır. Buradaki nokta, rutin tek uç noktalı sarmalayıcıların el işi olmaktan çıkmasıdır.
Test sırasında ajanın yazma uç noktalarını çağırmasını nasıl engellerim? HTTP yöntemine göre filtreleyerek test çalıştırmaları için salt okunur bir araç seti oluşturun ve ajanı yazan her şey için bir sanal sunucuya yönlendirin. Ajanların neden üretim yerine sanal sunucuları kullanması gerektiği hakkındaki yazımız kurulumu kapsar.