> ## Content Index > Fetch the complete content index at: https://www.frontierlayers.com/llms.txt > Use this file to discover other available public pages before exploring further. # Agent araçları için şema tasarımı: İyi tool şeması neden güvenlik kontrolüdür? - URL: https://www.frontierlayers.com/agent-araclari-icin-sema-tasarimi-iyi-tool-semasi-neden-guvenlik-kontroludur/ - Published: 2026-09-13T16:52:37.000Z - Updated: 2026-09-13T16:52:37.000Z - Author: Anıl Güleroğlu Bir müşteri destek agent'ı, bağlantısı kopan bir çağrının ardından aynı sipariş için ikinci kez iade oluşturdu. Agent'ın niyeti doğruydu. Müşteri gerçekten para iadesi istiyordu. Hata, `issue_refund(customer_id, amount)` adlı aracın sözleşmesindeydi: Hangi siparişin iade edildiği, tutarın hangi para biriminde olduğu, işlemin daha önce yapılıp yapılmadığı ve başarılı sayılmak için neyin doğrulanacağı tanımlanmamıştı. Bu tür bir olayı yalnızca modele bağlamak kolaydır. Model daha dikkatli olmalıydı denir. Oysa daha iyi bir model de aynı belirsiz aracı, aynı eksik bilgiyle çağırabilir. Sorun, agent'ın dış sistemle temas ettiği yerdeki boşluktadır. Agentik sistemlerde tool tanımı çoğu zaman fonksiyon adı, kısa bir açıklama ve birkaç parametreden ibaret kalıyor. Bu, başlangıç için yeterli görünebilir. Fakat araç para iadesi oluşturuyor, kayıt güncelliyor, e-posta gönderiyor ya da erişim veriyorsa şema tek başına davranışı sınırlamaz. Tool'un hangi işi yaptığı, hangi koşulda reddedeceği, etkisinin ne olduğu ve sonucun nasıl deneneceği de açık olmalıdır. Bu yazıda tek bir iade talebini baştan sona izleyeceğim. Amaç, `refund` aracını daha ayrıntılı anlatmak değil. Amaç, bir tool contract'ın API imzasından neden daha fazlası olduğunu göstermek. ## Şema ile davranış sözleşmesi arasındaki fark Bir JSON Schema, alanların tipini ve bazı biçim kurallarını denetler. `amount` sayısal mı, `order_id` var mı, `reason_code` izin verilen değerlerden biri mi? Bunlar gerekli kontrollerdir. Ancak agentik bir akışta şu sorular da en az bunlar kadar önemlidir: - Bu tool ne yapar ve ne yapmaz? - İşlem hangi tenant ve hangi çağıran kimlik adına yürütülür? - Hangi iş koşulları sağlanmadan çağrı kabul edilmez? - Aynı niyet iki kez gelirse sistem ne yapar? - Çağrının dış dünyadaki etkisi nedir? - Hangi hata yeniden denemeyi, hangisi açıklama istemeyi gerektirir? - Yanıt geldikten sonra başarı nasıl doğrulanır? Bunların toplamı davranış sözleşmesidir. Agent'ın serbest metinli açıklamayı nasıl yorumlayacağını tahmin etmeye bırakmak yerine, yürütme sınırını sistemin kendisi kurar. Bu ayrım, daha önce ele alınan yetki, onay ve gözlemlenebilirlik konularıyla ilişkilidir ama onların tekrarı değildir. Yetki modeli kimin hangi işlemi yapabileceğini belirler. Tool contract ise izin verilmiş bir aracın, çağrıldığı anda hangi davranışı göstereceğini tanımlar. Birincisi erişim sınırıdır. İkincisi yürütme sınırıdır. ## Aynı iade için iki farklı tool tanımı İlk örnek, Chat Completions biçimine uyan ama iş açısından eksik bir tool tanımıdır. Bu JSON, modele gönderilen `tools` alanının içeriğidir: ```json { "tools": [ { "type": "function", "function": { "name": "issue_refund", "description": "Müşteriye iade yapar.", "strict": true, "parameters": { "type": "object", "properties": { "customer_id": { "type": "string" }, "amount": { "type": "number" } }, "required": ["customer_id", "amount"], "additionalProperties": false } } } ] } ``` Bu tanım biçimsel olarak geçerlidir. Fakat yalnızca modelin iletebileceği girdileri tarif eder. Aşağıdaki kararları agent'a veya çağrının arkasındaki uygulamaya bırakır: - Müşterinin birden fazla siparişi varsa hangisi seçilecek? - `49.90` hangi para birimidir? - İade ürün, sipariş kalemi ya da tüm sipariş düzeyinde mi yapılacak? - Çağıran kullanıcının bu müşteri için işlem yetkisi var mı? - Aynı çağrı ağ hatasından sonra tekrar edilirse ne olacak? - Bir `ok` yanıtı, iadenin gerçekten kayda geçtiğini gösteriyor mu? Bu soruların her biri gerçek bir iş kuralına karşılık gelir. Açıkça yazılmadıklarında, modelin tahmini veya bir geliştiricinin varsayımı haline gelirler. Aynı işlemin modelle paylaşılacak daha iyi tool tanımı ise şöyle olabilir: ```json { "tools": [ { "type": "function", "function": { "name": "create_refund", "description": "Belirtilen sipariş kalemi için iade kaydı oluşturur. Yalnızca iade uygunluğu ve gerekli insan onayı uygulama tarafından doğrulanmışsa çağırın.", "strict": true, "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "İade edilecek siparişin kimliği." }, "line_item_id": { "type": "string", "description": "İade edilecek sipariş kaleminin kimliği." }, "amount": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0.01 }, "currency": { "type": "string", "enum": ["TRY"] } }, "required": ["value", "currency"], "additionalProperties": false }, "reason_code": { "type": "string", "enum": ["damaged_item", "missing_item", "customer_cancellation"] }, "approval_id": { "type": "string" }, "idempotency_key": { "type": "string" } }, "required": ["order_id", "line_item_id", "amount", "reason_code", "approval_id", "idempotency_key"], "additionalProperties": false } } } ] } ``` Bu örnek bir ürün standardı değildir. İsimler ve alanlar her sistemde değişir. Ama sınır nettir: Bu, modelin çağrı için üreteceği girdileri tarif eden OpenAI tool şemasıdır. `purpose`, `does_not_do`, `side_effect`, `preconditions` ve `postconditions` bu JSON içinde yerel OpenAI alanları değildir. Bunlar uygulamanın çevresindeki contract dokümanında tanımlanmalı ve tool gateway ya da backend tarafından uygulanmalıdır. Bu çevre sözleşmesi örneğin şunları açıklar: Aracın amacı uygun ve onaylanmış bir sipariş kalemi için iade oluşturmaktır. Sipariş veya müşteri kimliği tahmin edilmez, kalan iade bakiyesi aşılmaz ve onaysız işlem yürütülmez. İşlemin finansal yazma etkisi vardır. Sunucu, siparişin tenant'a ait olduğunu, çağıranın yetkili olduğunu, kalemin iade edilebilirliğini, tutarın kalan bakiyeyi aşmadığını ve onayın geçerli olduğunu doğrular. Başarılı kabul edilen sonuçta bir `refund_id` üretilir, durum `pending` veya `completed` olur ve okuma sonrası doğrulama kayda alınır. ## İade talebi nasıl ilerlemeli? Müşteri temsilcisi agent'a şu isteği iletsin: "Müşterinin hasarlı ürün için iadesini yapabilir misin?" Bu cümle işlem başlatmak için yeterli değildir. Bir insan temsilci de önce hangi siparişten söz edildiğini, hangi ürünün hasarlı olduğunu ve iade tutarını doğrulamak ister. Agent'ın akışı da bunu atlamamalıdır. ### 1\. Kimliği çözmek, işlemi yetkilendirmek değildir Agent ilk olarak müşteri ve sipariş bilgisini bulmak için sadece okuma yapan araçları çağırır. Örneğin `find_orders_by_customer` aracı, ilgili tenant içindeki son siparişleri dönebilir. Bu sonuçta iki sipariş çıkarsa agent, kullanıcıya seçenek sunar veya daha fazla bilgi ister. Burada önemli sınır şudur: Arama sonucunda bulunan `customer_id`, para hareketi yapmak için tek başına yeterli değildir. İade aracının `order_id` ve `line_item_id` istemesi, gereksiz tekrar değildir. Yan etkisi olan işlemin gerçek hedefini belirler. Bu yaklaşım, yanlış müşteriye işlem yapmayı zorlaştırır. Tenant bağlamı ve `order_belongs_to_tenant` kontrolü modelin açıklamasına veya tool şemasındaki serbest alanlara değil, çağrının kimliğini taşıyan sunucu tarafı bağlamına dayanmalıdır. ### 2\. Tutarın anlamı contract içinde taşınmalıdır Para tutarı, yalın bir sayı olarak güvenli bir girdi değildir. `49.90` ifadesi para birimini, hassasiyet kuralını ve neyin iade edildiğini söylemez. Bu yüzden tutarı yapılandırılmış nesne olarak taşımak daha nettir: ```json { "amount": { "value": 49.90, "currency": "TRY" } } ``` Bu yapı tek başına yeterli değildir. Tool'un arka ucunda, tutarın iade edilebilir kalan bakiyeyi geçmediği denetlenmelidir. Kısmi iade varsa, işlem siparişe değil ilgili kaleme bağlanmalıdır. Uygunluk kararı, modelin "müşteri haklı görünüyor" yorumuna bırakılmaz. Agent'ın görevi, eksik bağlamı görünür kılmaktır. Sözleşmenin görevi ise eksik bağlamla yazma işlemini reddetmektir. ### 3\. Onay, açıklama metni değil ön koşuldur Finansal etkisi olan bir işlemde insan onayı gerekiyorsa model şemasında `approval_id` girdisi bulunabilir. Ancak `approval_is_valid` bir OpenAI tool alanı değildir. Bu, çevre contract'ında tanımlanan ve sunucu tarafında zorlanan bir iş kuralıdır. Böylece sistem sadece "onay iste" talimatına güvenmez. Geçerli bir onay kaydı yoksa çağrı ısrarla reddedilir. Onay kaydı işlem için yeterli bağlam içermelidir: sipariş, kalem, tutar, para birimi, gerekçe ve onaylayan kişi. Kullanıcı bir tutarı onayladıktan sonra agent'ın aynı onayı başka bir siparişe veya daha yüksek tutara bağlaması engellenmelidir. Bu ayrıntı, onayı kullanıcı deneyimi katmanından çıkarıp yürütmenin parçası yapar. Onay ekranı olabilir, ama kararın sunucu tarafındaki karşılığı da olmalıdır. ### 4\. İdempotency, ağ hatasına karşı iş kuralıdır İade talebi ödeme altyapısına gönderildiğinde bağlantı kesilebilir. Agent, bir hata aldığını görür ama karşı tarafın işlemi oluşturup oluşturmadığını bilemez. Bu noktada aynı çağrıyı körlemesine yenilemek, çift iade riski doğurur. İdempotency anahtarı bu riski sınırlar. Anahtar, aynı iş niyetini temsil eder. Örneğin `refund-ord_901-line_2-v1` hem sipariş kalemini hem de iade sürümünü tanımlar. Aynı anahtarla ikinci çağrı geldiğinde sistem yeni bir para hareketi yaratmak yerine daha önceki sonucu dönebilir. İdempotency anahtarı rastgele bir teknik etiket olmamalıdır. Hangi iş olayını tekilleştirdiği anlaşılmalıdır. Tam iade ile farklı bir sonraki kısmi iade aynı anahtarı kullanmamalıdır. Bunun için anahtar üretimi uygulamanın sorumluluğundadır. Agent, anahtarı uydurmak yerine tool'un sunduğu akıştan almalı veya güvenli biçimde oluşturulan anahtarı kullanmalıdır. ## Hata modeli, agent'ın bir sonraki adımını belirler Bir tool hata veriyorsa agent için tek bir davranış yoktur. Hata modelinin makinece işlenebilir olması, her hatayı yeniden deneme isteğine çevirmeyi önler. Aşağıdaki küçük hata sözleşmesi yeterli bir başlangıçtır: ```json { "error": { "code": "refund_not_eligible", "http_status": 422, "retryable": false, "safe_message": "Bu sipariş kalemi için iade uygun değil.", "next_action": "explain_or_request_manual_review" } } ``` İade akışında birkaç hata türü birbirinden ayrılmalıdır: - `403 caller_not_authorized`: Agent yeni bir yol aramamalı, yetki sınırını bildirmelidir. - `409 idempotency_key_already_processed`: Aynı işlemi tekrar başlatmamalı, mevcut iade kaydını okuma aracından doğrulamalıdır. - `422 refund_not_eligible`: Yeniden deneme yapılmamalı, uygun olmayan durum kullanıcıya açıklanmalı veya manuel incelemeye aktarılmalıdır. - Geçici zaman aşımı: Sistem, idempotency anahtarıyla durum sorgulaması yapmalı; işlem bulunamazsa kontrollü bir tekrar değerlendirmelidir. Bu sınıflama, retry politikasının tool contract'a dayanmasını sağlar. Yalnızca hata metnini modele verip yorumlamasını beklemek, özellikle farklı servislerin farklı mesajları olduğunda kırılgandır. ## Başarılı yanıt, başarı kanıtı değildir `create_refund` çağrısı bir `refund_id` döndürdüğünde akış bitmiş sayılmamalıdır. Ödeme altyapısı işlemi kabul etmiş ama henüz işleme koymamış olabilir. Bazı sistemler asenkron çalışır, bazıları işleme alınan kaydı sonra iptal edebilir. Bu nedenle çevre contract'ında yazma işleminden sonra bir doğrulama adımı tanımlanmalıdır. Bu, OpenAI tool şemasına eklenecek bir `postconditions` alanı değildir. Agent, `get_refund(refund_id)` gibi yalnızca okuma yapan bir aracı çağırır ve beklenen durumu kaydeder. Örneğin `pending` veya `completed` kabul edilen durumlar olabilir. `failed` ya da beklenmeyen bir durum varsa, agent müşteriye iade yapıldı diye bilgi vermez. Bu doğrulamanın kanıtı da saklanmalıdır. Asgari bir kayıt şu alanları içerebilir: ```json { "trace_id": "tr_73f", "tool": "create_refund", "tenant_id": "tnt_42", "order_id": "ord_901", "idempotency_key": "refund-ord_901-line_2-v1", "approval_id": "apr_188", "result": "accepted", "refund_id": "ref_551", "verification_status": "pending" } ``` Buradaki amaç ham müşteri verisini iz kaydına taşımak değildir. Amaç, işlem kararı ile doğrulama sonucunu birbirine bağlamaktır. Kayıt tasarlanırken kişisel veri, erişim yetkisi ve saklama süresi için ayrı politikalar uygulanmalıdır. ## Contract'ı kodda nerede uygularız? Tool contract yalnızca model sağlayıcısına gönderilen JSON değildir. Sınırın birden fazla yerde uygulanması gerekir. İlk katman, input doğrulamasıdır. Şema, eksik veya yanlış biçimli alanı daha iş mantığına ulaşmadan reddeder. İkinci katman iş kurallarıdır. Siparişin tenant'a ait olması, iade bakiyesi ve onay kaydının geçerliliği burada değerlendirilir. Üçüncü katman yan etkiyi yapar. Para hareketi, idempotency anahtarı ve sınırlandırılmış yetkiyle bu katmanda oluşturulur. Son katman ise okuma sonrası doğrulama ve iz kaydıdır. Bu ayrım, tek bir geniş tool fonksiyonunun içine her şeyi gömmek zorunda olduğunuz anlamına gelmez. Çoğu sistemde agent'a açık araçlar dar tutulabilir: - Siparişleri bulmak için okuma aracı - İade uygunluğunu görmek için okuma aracı - Onay talebi oluşturmak için ayrı bir araç - İadeyi oluşturmak için yan etkili araç - İşlem durumunu doğrulamak için okuma aracı Araç sayısını artırmak kendi başına iyi bir şey değildir. Ancak okuma, karar ve yazma adımlarının ayrı contract'lara sahip olması, hangi noktada hangi güvenceyi aradığınızı netleştirir. Tool açıklaması da bu tasarımın parçasıdır. Açıklama agent'ın niyetini yönlendirir. Örneğin `create_refund` açıklaması "Uygunluk ve onay doğrulanmadan çağırma" diyebilir. Fakat açıklama güvenlik kontrolü değildir. Model açıklamayı yanlış yorumlayabilir veya bağlamı eksik okuyabilir. Kritik sınır, tool gateway ya da backend tarafından zorlanmalıdır. > Yan not: Onay uygunluğu veya işlem sonucunu değerlendirmek için bir LLM değerlendiricisi kullanılıyorsa, bu değerlendirici de ayrı test setleriyle kalibre edilmelidir. Modelin verdiği "uygun" kararı, deterministik para ve yetki kurallarının yerine geçmemelidir. ## Yayına almadan önce sorulacak sorular Bir agent'a yan etkili bir tool vermeden önce aşağıdaki sorulara kısa ve somut cevap yazmak faydalıdır: 1. Tool'un amacı tek cümlede net mi? Yapmadığı şeyler de yazılı mı? 2. Girdi, işlemin gerçek hedefini belirliyor mu? Müşteri kimliği yerine sipariş veya kalem gibi doğru nesne kullanılıyor mu? 3. Tenant, çağıran kimlik ve rol kontrolü sunucu tarafında mı? 4. İşlem öncesi hangi koşullar zorunlu ve bunları kim doğruluyor? 5. Yan etki türü açık mı? Okuma, taslak, geri alınabilir yazma ve mali işlem aynı riskte değerlendirilmemeli. 6. Aynı niyet tekrar gelirse sonuç tekilleşiyor mu? 7. Hatalar kod, yeniden deneme bilgisi ve güvenli sonraki adımla dönüyor mu? 8. Başarıdan sonra hangi kaydın okunacağı ve hangi durumun kabul edileceği tanımlı mı? 9. Kararı ve doğrulamayı bağlayan asgari iz kaydı var mı? 10. Bu sözleşmeyi bozan değişiklikler için otomatik sözleşme ve entegrasyon testleri çalışıyor mu? Bu liste, kapsamlı bir yönetişim programının yerine geçmez. Fakat agent'ın dış sistemle temas ettiği noktada belirsizliği azaltır. ## Sonuç Agent'a bir tool vermek, modele yeni bir fiil öğretmek değildir. Dış dünyada etkisi olan bir yeteneği açmaktır. Güvenli davranış, uzun bir tool açıklamasından değil; amaç, ön koşul, yan etki, idempotency, hata modeli ve doğrulama ile tanımlanmış bir sözleşmeden gelir. İade örneğinde asıl kazanım, agent'ın daha temkinli görünmesi değildir. Yanlış siparişe işlem yapmasının, aynı iade talebini iki kez yürütmesinin ve doğrulanmamış sonucu başarı diye sunmasının sistem tarafından zorlaştırılmasıdır. İyi bir tool contract tam olarak bunu yapar. --- ## Kaynaklar - Frontier Layers, [Agent Optimizasyonu: Production'da Farkı Yaratan Şey Prompt Değil, Sistem Tasarımı](https://medium.com/cognipeer/agent-optimizasyonu-productionda-fark%C4%B1-yaratan-%C5%9Fey-prompt-de%C4%9Fil-sistem-tasar%C4%B1m%C4%B1-885c14545f3a?ref=frontierlayers.com) - Frontier Layers, [Loop Engineering: Agent'ı "Çalıştırmak" Değil, Döngüyü Yönetmek](https://medium.com/cognipeer/loop-engineering-agent%C4%B1-%C3%A7al%C4%B1%C5%9Ft%C4%B1rmak-de%C4%9Fil-d%C3%B6ng%C3%BCy%C3%BC-y%C3%B6netmek-7afa08ac49e1?ref=frontierlayers.com) - Frontier Layers, [Tool-Heavy Agent'lar ve Context Engineering: Bağlam Taşmasını Yönetmek](https://medium.com/cognipeer/tool-heavy-agentlar-ve-context-engineering-ba%C4%9Flam-ta%C5%9Fmas%C4%B1n%C4%B1-y%C3%B6netmek-pratik-rehber-791d96372572?ref=frontierlayers.com) - Anthropic, [Writing effective tools for AI agents](https://www.anthropic.com/engineering/writing-tools-for-agents?ref=frontierlayers.com) - NIST, [Artificial Intelligence Risk Management Framework](https://www.nist.gov/itl/ai-risk-management-framework?ref=frontierlayers.com)