Ana içeriğe geç

Araç Yüzeyleri Bir Şema Problemidir: Akıllı Promptlardan Önce Tipli Argümanlar

Ajan araç kullanımı hatalarının çoğu zayıf akıl yürütmeden değil, eksik tanımlanmış şemalardan kaynaklanır. Araç arayüzünü birincil güvenilirlik kaldıracı olarak ele alın.

Vibrant backlit buttons on an electronic music controller for audio production.

Hata genellikle sınırda gerçekleşir

Bir ajan bir aracı çağırdığında ve çağrı yanlış gittiğinde, içgüdü modeli suçlamaktır. Prompt yeterince açık değildi, akıl yürütme sığdı, bağlam gürültülüydü. Pratikte bu hataların büyük bir kısmı model daha akıl yürütmeden önce belirlenir: araç şemasında. Şema, model ile sistem arasındaki sözleşmedir. Bu sözleşme belirsizse, model boşlukları makul tahminlerle doldurur ve araç bunları yürütür.

Bu makale, arayüz tasarımının ajan sistemleri için birincil güvenilirlik kaldıracı olarak, prompt mühendisliğinin önünde ele alınması gerektiğini savunur. Promptlar davranışı olasılıksal olarak şekillendirir. Şemalar ise yapısal olarak zorlar.

Araç çağrıları aslında nerede başarısız olur

Üç kalıp, kötü araç çağrılarının orantısız bir payını oluşturur.

Belirsiz parametre adları. target veya value veya options adlı bir alan, modeli anlamı bağlamdan çıkarsamaya davet eder. Model, sözdizimsel olarak geçerli ve anlamsal olarak yanlış bir argüman üretir. Araç bunu kabul eder. Hata daha sonra, genellikle başarısız bir çağrı yerine alt akışta bir veri problemi olarak ortaya çıkar. target_user_id ve retention_days gibi adlar ayrıntılı değildir; belirsizliği giderirler.

Varsayılanı olmayan isteğe bağlı alanlar. Bir şema bir alanı isteğe bağlı olarak işaretliyorsa ancak aracın varsayılanı ve null işleme yolu yoksa, model çağrıyı tamamlamak için bir değer uydurmak zorundadır. Uyduracaktır. Uydurulan değer makul görünecek ve tespit edilmesi zor bir şekilde yanlış olacaktır. İsteğe bağlılık, aracın davranışı hakkında bir iddiadır, modele bir ipucu değil.

Serbest metin argümanları. Yapısı olmayan bir string argümanı, niyeti düzyazıya indirger. Araç düzyazıyı doğrulayamaz. Model düzyazıyla düzeltilemez. "raporu yarın sabah ekibe gönder" kabul eden bir alan, zamanlama mantığını modelin kafasına itmiştir; orada ne denetlenebilir ne de test edilebilir.

Bunlar akıl yürütme hataları değildir. Akıl yürütme hataları olarak görünen spesifikasyon hatalarıdır.

Interior view of a warehouse in Dar es Salaam with a shrink film machine and industrial equipment.

Bir araç şeması için tasarım kuralları

Bir araç şeması, tıpkı bir genel API gibi aynı titizlikle ele alınmalıdır, çünkü zaten öyledir.

Her argüman tipli, sınırlı ve sınırda doğrulanmış. Tipler gerekli ancak yeterli değildir. Sabit bir kümeden biri olması gereken bir string enum olmalıdır. Bir aralıkta olması gereken bir sayı aralığı taşımalı ve sınır, yürütmeden önce dışındaki değerleri reddetmelidir. Sınırda doğrulama, aracın işleyemeyeceği bir argümanı asla görmemesi ve modelin ürettiğinde deterministik bir sinyal alması anlamına gelir.

Ön koşullar bağlamdan varsayılmak yerine açıklamada belirtilmiş. Bir araç bir kaynağın var olmasını veya önceki bir çağrının başarılı olmasını gerektiriyorsa, bu açıklamaya aittir. Model ön koşulları konuşma geçmişinden güvenilir şekilde çıkarsamaz ve çıkarsamak zorunda da olmamalıdır. "open_session'dan alınan aktif bir oturum kimliği gerektirir" diyen bir açıklama bir spesifikasyondur. "Şeyi yapar" diyen bir açıklama bir umuttur.

Hatalar düzeltme ipuçlarıyla tipli kodlar olarak döndürülür. Bir çağrı doğrulamada başarısız olduğunda, yanıt makine tarafından okunabilir olmalıdır: ajanın dallanabileceği bir kod ve sözleşmeyi neyin karşılayacağına dair kısa bir ipucu. Stack trace'ler ve serbest metin hata mesajları, ayrıştırmayı modele geri iter; bu tam da şemanın ortadan kaldırması gereken iştir.

Somut bir mekanizma: iki aşamalı bir çağrı yolu. Model, şemaya karşı argümanlar üretir. Bir doğrulayıcı tipleri, sınırları, enum'ları ve ön koşulları kontrol eder ve ya normalleştirilmiş bir argüman nesnesi ya da tipli bir ret döndürür. Aracın uygulamasına yalnızca normalleştirilmiş nesneler ulaşır. Araç uygulaması daha sonra girdilerinin iyi biçimlendirilmiş olduğunu varsayabilir; bu, yürütme yolundan savunmacı dallanmayı kaldırır ve hataları iki yerden birine atfedilebilir kılar: modelin argümanı veya aracın davranışı.

Promptlar neden telafi edemez

Aracın tuhaflıklarını açıklayan daha uzun bir sistem promptu yazmak cezbedicidir. Bu ölçeklenmez, üç nedenden dolayı.

Talimat takibi bağlam uzunluğu ve araç sayısıyla bozulur. Mevcut araçların sayısı arttıkça, modelin herhangi bir tek talimata olan dikkati incelir. Uzun bir promptta bir kez belirtilen bir kural, penceredeki her şeyle rekabet eder. Bir şema ise kaç araç mevcut olursa olsun her çağrıda zorlanır.

Bir şema zorlanır; bir prompt ise yerine getirilir. Temel asimetri budur. Doğrulama deterministik olarak çalışır. Prompt uyumu, ifadeye, sıralamaya ve bağlama göre değişen bir olasılıktır. Güvenilirlik önemli olduğ

Detailed view of a retro arcade machine control panel with colorful buttons and joystick.

Şema değişiklikleri incelenebilir artefaktlardır. Bir araç şemasına yapılan bir diff, bir sözleşmeye yapılan bir difftir. İncelenebilir, sürümlenebilir, test edilebilir ve geri alınabilir. Bir prompt ince ayarı ise, etkileri yerel olmayan ve kolayca sınırlandırılamayan doğal dil talimatına yapılan bir değişikliktir. Promptları güvenilirlik katmanı olarak ele alan ekipler, incelenemeyen bir güvenilirlikle kalır.

Dürüst ödünleşim: daha katı şemalar esnekliğe mal olur. Sıkı tipli bir araç, gevşek belirtilmiş bir isteği ememez ve bazı meşru kullanım durumları zarifçe ele alınmak yerine sınırda reddedilir. Alternatif, her şeyi kabul eden ve öngörülemez şekilde başarısız olan bir araçtır. Çoğu üretim sistemi için tipli bir ret, sessiz bir yanlış sonuçtan daha ucuzdur. Esneklik gerçekten gerekli olduğunda, tipsiz bir string olarak değil, örneğin tipli istek varyantlarının ayrımlı bir birleşimi olarak açıkça modellenmelidir.

Geçiş ve sürümleme

Araçlar API'lerdir. Kullanımdan kaldırma pencerelerine, sürümlenmiş adlara ve eski ve yeni şemaların her ikisinin de çözümlendiği bir döneme ihtiyaçları vardır. Bir aracın şeklini açıklaması yoluyla öğrenmiş bir ajan, yıkıcı bir değişikliğe anında uyum sağlamayacaktır ve etrafında kurulmuş değerlendirmeler de sağlamayacaktır.

İki metrik, gecikme ve maliyetin yanında birinci sınıf panoda yer almalıdır:

  • Araç başına çağrı başarı oranı. Toplanmış değil, araca göre ayrıştırılmış. Sistem genelinde bir başarı oranı, başarısız olan tek aracı gizler.
  • Argüman reddetme oranı. Yürütmeden önce doğrulayıcı tarafından reddedilen çağrıların oranı. Yükselen bir reddetme oranı, bir şemanın belirsiz olduğunun, bir açıklamanın yanıltıcı olduğunun veya modelden bilemeyeceği bir değerin istendiğinin erken bir işaretidir.

Bu iki metrik, şema problemlerini akıl yürütme problemlerinden ayırır. Yüksek reddetme oranına ve net bir ret koduna sahip bir araç, size sözleşmesinin belirsiz olduğunu söylüyordur. Daha sonra yanlış sonuç üreten çağrılarda yüksek başarı oranına sahip bir araç, size doğrulamasının fazla müsamahakâr olduğunu söylüyordur. Hiçbir sinyal bir promptta görünmez.

Bu pratikte neyi değiştirir

Araç yüzeyini bir şema problemi olarak ele almak, mühendislik çabasının nereye gittiğini değiştirir. Şema tasarımı, kendi testleri olan incelenebilir bir etkinlik haline gelir. Açıklamalar, ön koşulları ve son koşulları olan spesifikasyonlar haline gelir. Hatalar, sonradan akla gelen bir şey yerine arayüzün bir parçası haline gelir. Promptlar hâlâ önemlidir, ancak iyi oldukları şeyi yaparlar: tonu, stratejiyi ve ayrıştırmayı şekillendirmek. Bir sözleşmeyi zorlama yükünü taşımazlar.

Daha geniş nokta şudur: ajan güvenilirliği çoğunlukla bir arayüz disiplinidir. Belirsiz bir arayüze karşı iyi akıl yürüten bir model yine de belirsiz çağrılar üretecektir. Kesin bir arayüze karşı yeterince akıl yürüten bir model, kontrol edilebilen, reddedilebilen ve düzeltilebilen çağrılar üretecektir. İşletilebilir olan sistem ikincisidir.

İlgili okumalar

Bunun yanıtladığı sorular

Why do agent tool calls fail even when the model reasons correctly?

Because the failure is often at the schema boundary, not in reasoning. Ambiguous parameter names, optional fields with no default, and free-text arguments all let the model produce plausible but wrong arguments that the tool accepts. The schema, not the prompt, decides whether those arguments can be validated.

Can a longer system prompt fix an unclear tool schema?

Not reliably. Instruction following degrades as context length and tool count grow, and prompt adherence is probabilistic. A schema is enforced on every call regardless of context, which makes it the more dependable place to encode the contract.

What metrics should track tool schema health?

Per-tool call success rate and argument-rejection rate, both broken down by tool rather than aggregated. A rising rejection rate points to an ambiguous schema or misleading description; a high success rate on calls that later produce wrong results points to validation that is too permissive.

How should tool schemas be versioned?

Like any API. Use versioned names, deprecation windows, and a period where old and new schemas both resolve, so agents and the evaluations built around them can migrate without breaking.