Ajan Tool Calling En İyi Uygulamaları: Ajanınız Neden Yanlış Aracı Seçiyor

Ajan Tool Calling En İyi Uygulamaları: Ajanınız Neden Yanlış Aracı Seçiyor

Ajan tool calling en iyi uygulamaları, çalışan bir demo ile production'da sessizce yanlış aracı çağıran bir ajan arasındaki farkı belirler. Anthropic'in mühendislik ekibi, tek bir yeniden yazılmış açıklamanın bir araç sonucunu 206 tokendan 72'ye düşürdüğünü ölçtü ve Claude Code artık her araç yanıtını 25.000 tokenla sınırlıyor çünkü sızıntı gerçek. Ajanınız dört şekilde hata verir: yanlış araç, yanlış argümanlar, kontrolden çıkan döngüler, token sızıntısı. Her birinin bu hafta yayınlayabileceğiniz bir çözümü var.

Öne çıkanlar:

• Ajan tool calling tam olarak dört şekilde hata verir: yanlış araç, yanlış argümanlar, kontrolden çıkan döngüler ve token sızıntısı.
• Araç açıklamaları, modelin seçim anında gördüğü tek talimattır; bu yüzden yanlış araç çağrılarının çoğunu düzeltir.
• Düz, göreve uygun şemalar ve doğrulanan girdiler, yanlış argüman hatalarının çoğunu ortadan kaldırır.
• Kısa araç yanıtları ve her değişiklikte çalışan bir eval döngüsü, token maliyetini ve regresyonları ölçülebilir tutar.

Ajan tool calling production'da neden hata verir?

Ajan tool calling dört şekilde hata verir: model yanlış aracı seçer, yanlış argümanlar yazar, kontrolden çıkan bir döngüde döner ya da şişkin yanıtlarla token sızdırır. Her hata, çağrı döngüsünün farklı bir adımını vurur; bu yüzden düzeltme sırası önemlidir. Seçimle başlayın, çünkü yanlış bir araç seçimi ondan sonraki her adımı zehirler.

Tam reçete bir bakışta:

Bu sırayla ilerleyin. 1 ve 2. uygulamalar bir öğleden sonra sürer ve bugün gördüğünüz yanlış araç ve yanlış argüman hatalarının çoğunu kaldırır. Araç açıklaması dokümantasyon değildir. Modelin seçim anında aldığı tek talimattır.

Aşama 1: Modelin gerçekten kullanabileceği araçlar tasarlayın

Ajan tool calling'de en ucuz güvenilirlik kazanımları araç tanımlarınızda yatar; promptlarınızda ya da model seçiminizde değil. Model API dokümanlarınızı ya da README'nizi asla okumaz. Bir ad, bir açıklama metni ve bir JSON şeması görür, kararını yalnızca bunlardan verir. Bu üçünü doğru yapın, başka bir şeye dokunmadan seçim doğruluğu hareket eder.

Uygulama 1: Modelin uygulayabileceği açıklamalar yazın

Araç açıklamalarını modele talimat olarak yazın, API dokümantasyonu olarak değil. İnsan geliştiriciyi memnun eden bir açıklama ("users endpoint'i için REST sarmalayıcı") modele karar verecek hiçbir şey vermez. Anthropic'in araç yazma mühendislik rehberi ve araç tanımı en iyi uygulamaları aynı kalıbı önerir: aracın ne zaman kullanılacağını, ne döndürdüğünü ve ne zaman kullanılmayacağını söyleyin.

{
  "name": "get_user",
  "description": "Fetches a user profile. Use ONLY when you already have a user_id. Do NOT use to search or list users; call search_users instead. Returns name, email, plan. Errors if user_id is not a valid UUID."
}

karşısında çoğu ekibin yayınladığı versiyon:

{
  "name": "get_user",
  "description": "Gets a user."
}

İki kural işin çoğunu yapar. Birincisi, parametreleri anlamları belirsiz olmayacak şekilde adlandırın: user_id, asla user ya da id değil; çünkü user modeli UUID gereken yere bir ad ya da e-posta geçmeye davet eder. İkincisi, istisnaları açıkça belirtin. "Kullanıcı aramak için kullanmayın" ifadesi, herhangi bir miktarda olumlu açıklamadan daha fazla yanlış araç çağrısını önler; çünkü modeller örtüşen araçları, tek ve sınırları belli olanları yanlış anlamaktan çok daha sık karıştırır. Bu tanımların OpenAI, Anthropic ve Google API'lerine nasıl ulaştığının sağlayıcı düzeyindeki mekaniği için çoklu sağlayıcı function calling rehberimize bakın.

Uygulama 2: Şemaları düz ve göreve uygun tutun

Girdi şemalarını düz tutun; görevin gerçekten ihtiyaç duyduğu her alanla, duymadığı hiçbir alan olmadan. İsteğe bağlı dalları olan iç içe nesneler, yanlış argüman hatalarının ürediği yerdir: model, örneğini hiç görmediği bir yapıyı çıkarsamak zorunda kalır. OpenAI function calling rehberi keyfi JSON Schema kabul eder, ama izin verici olmak güvenilir olmakla aynı şey değildir.

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "ticket": {
        "type": "object",
        "properties": {
          "details": {
            "type": "object",
            "properties": {
              "title": { "type": "string" },
              "meta": { "type": "object" }
            }
          }
        }
      }
    }
  }
}

Göreve uygun şekilde düzleştirin:

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "medium", "high"] },
      "assignee_id": { "type": "string" }
    },
    "required": ["title", "priority"]
  }
}

Enum'lar, sınırlı bir değer kümesi olan her alan için serbest metni yener. Required dizileri, her şeyi isteğe bağlı yapmaktan iyidir. Model bir alana neredeyse her zaman ihtiyaç duyuyorsa, API'niz onu isteğe bağlı olarak adlandırsa bile araç şemasında required yapın. API'nizi yansıtmıyorsunuz. Belirli bir modelin doğru doldurabileceği bir yüzey tasarlıyorsunuz.

Aşama 2: Araç setini yönetin, sadece araçları değil

Bir ajan bir avuçtan fazla araç taşıdığında bireysel araç kalitesi yeterli olmaktan çıkar; çünkü seçim hataları, modelin okuduğu listenin boyutuyla birlikte büyür.

Uygulama 3: Çok adımlı API dizilerini atomik araçlara sarın

Sabit bir API çağrı dizisini tek bir atomik araca katlayın. Anthropic'in mühendislik yazısı schedule_event ve get_customer_context'i örnek gösterir: tüm işi yapan tek bir çağrı, ajanın her seferinde doğru zincirlemesi gereken üç çağrıyı yener. Zincirdeki her halka, modelin takılabileceği, yanlış tekrarlayabileceği ya da döngüye girebileceği başka bir turdur.

# What the agent does WITHOUT an atomic tool: 3 calls, 3 chances to fail
calendar = call_tool("list_calendars", {})
free = call_tool("find_free_slot", {"calendar_id": calendar["items"][0]["id"], "duration": 30})
call_tool("create_event", {"calendar_id": calendar["items"][0]["id"], "start": free["start"]})

# One atomic tool: the sequence lives in your code, not the model's head
call_tool("schedule_event", {"duration": 30, "attendees": ["[email protected]"]})

Pratik kural: model her zaman A'dan sonra B'yi çağırmak zorundaysa, A ve B iki kostüm giymiş tek bir araçtır.

Uygulama 4: Araçları namespace'leyin, budayın, dinamik filtreleyin

Her araç adını namespace'leyin ve her ajana yalnızca mevcut görevinin ihtiyaç duyduğu alt kümesini gösterin. Jenerik adlar, iki entegrasyon bağladığınız an çarpışır. İkisi de search adında bir araç sunan iki MCP sunucusuna bağlı bir ajan düşünün: iki özdeş fiil, ayırt etmenin yolu yok. Anthropic, ön ek namespace'lemesinden ölçülebilir eval kazanımları belgeliyor:

Budama da adlandırma kadar önemli. Bir destek ajanı, şifre sorusu yanıtlarken fatura araçlarının yüklenmesine ihtiyaç duymaz. Planlayıcı-çalışan kalıbı (bir planlayıcının görevi yalnızca ilgili araçları yükleyen bir çalışana yönlendirmesi) standart çözümdür; LangGraph'ın dinamik araç yükleme rehberi uygulamasını anlatır. Kaç araç çok fazla? Ajan başına 5-10'u çalışma aralığı olarak kabul edin, yasa olarak değil: doğruluk liste büyüdükçe düşer ve çözüm filtrelemedir, daha büyük bir model değil. Yönlendirme ve filtreleme katmanının kendisini seçiyorsanız, en iyi function calling kütüphaneleri derlememizde seçenekleri karşılaştırın.

Aşama 3: Geri geleni ve dışarı gideni kontrol edin

Döngü iki yönde çalışır ve çoğu ekip yalnızca giden yarısını mühendisler. Araçlarınızın döndürdüğü şey, bağlam penceresinin ne kadarının bir sonraki tura sağ kaldığını belirler; doğrulamanızın reddettiği şey ise modelin hatalarından öğrenip öğrenmediğini ya da tekrarlayıp tekrarlamadığını belirler.

Uygulama 5: Kısa, yüksek sinyalli sonuçlar döndürün

Modelin üzerinde hareket edebileceği en küçük sonucu döndürün; ham ID'ler yerine insan tarafından okunabilir tanımlayıcılarla. Anthropic'in mühendislik yazısı, varsayılan sonucu 206 token olan bir aracı belgeliyor; kısa bir response_format ayarı aynı sonucu 72 tokena, kabaca üçte birine düşürdü. Bunu görev başına düzinelerce çağrıyla çarpın; ajanınızın işi bitirip bitiremeyeceğini belirler.

// Before: 206 tokens (shape per Anthropic's documented example)
{
  "status": "success",
  "data": {
    "id": "8f14e45f-ceea-3f9c-a2f3-90c1b5e0a7d2",
    "object": "task", "created_at": "2026-07-02T09:14:00Z",
    "updated_at": "2026-07-11T16:40:12Z", "completed_at": null,
    "assignee": {"id": "c9a1...f2", "object": "user"},
    "projects": [{"id": "b7d3...91", "object": "project"}],
    "permalink": "https://app.asana.com/0/.../f"
  }
}

// After: 72 tokens
{ "task": "Fix login redirect", "assignee": "Dana Kim", "project": "Web App", "due": "2026-07-20" }

Aynı kaynaktan iki detay daha: Anthropic, araç tanımlarında bir response_format enum'u (detailed ile concise) destekler; böylece yangın hortumunu ayrıştırmak yerine istediğiniz şekli beyan edersiniz. Ve Claude Code araç yanıtlarını 25.000 tokenla sınırlar; bu, şişkin sonuçları her halükarda kesen sert bir tavandır. Anthropic ayrıca UUID'leri anlamsal adlara çözmenin alma halüsinasyonlarını ölçülebilir şekilde azalttığını kendi bulgusu olarak raporlar; yukarıdaki "sonra" payload'ında c9a1...f2 değil de "Dana Kim" yazmasının nedeni budur. Şişkin yanıtlar aynı zamanda bir maliyet sorunudur; tam tablo için LLM API maliyetlerini azaltma rehberimize bakın.

Uygulama 6: Her çağrıyı doğrulayın, hatalar modele öğretsin

Her araç çağrısını sunucu tarafında doğrulayın ve çözümü içeren hatalar döndürün. Martin Fowler'ın function calling yazısı bunu açıkça ortaya koyar: modelin çıktısına asla güvenmeyin. Enum gereken yere string geçer ve var olmayan ID'ler uydurur.

def create_ticket(args):
    if args.get("priority") not in {"low", "medium", "high"}:
        return {"error": f"priority must be one of: low, medium, high. Got '{args.get('priority')}'. Pass priority='medium' for normal issues."}
    if not is_valid_uuid(args.get("assignee_id")):
        return {"error": "assignee_id must be a UUID. Call list_team_members to get valid IDs, then retry."}
    return db.create_ticket(**args)

Hata metni işin tamamıdır. Karşılaştırın:

# Unhelpful: the model retries the same bad call
{"error": "invalid input"}

# Helpful: the model knows exactly what to change
{"error": "priority must be one of: low, medium, high. Got 'urgent'. Use 'high'."}

Aracınızın döndürdüğü her doğrulama hatası, modelin bir sonraki denemesi için yazdığınız bir prompt'tur. Kısıtı adlandıran ve düzeltici aracı işaret eden hatalar, bir tekrar döngüsünü tek seferlik bir kurtarmaya dönüştürür. Bu aynı zamanda ilk güvenlik savunma hattınızdır; LLM guardrails rehberimiz bunu derinlemesine ele alır.

Aşama 4: Nasıl güvenli hale getirirsiniz, sonra nasıl ölçersiniz?

Güvenlik ve ölçüm aynı aşamadır; çünkü onaysız bir yıkıcı işlem ve ölçülmeyen bir regresyon, ikisi de önceden göremeyeceğiniz olaylar olarak ortaya çıkar. Geri alınamayan işlemleri onaya bağlayın, sonra her şeyi enstrümanlayın; böylece bir sonraki araç değişikliği arkasında kanıt olan bir karar olur, bir umut değil.

Uygulama 7: Yıkıcı işlemleri insan onayına bağlayın

Okuma araçlarını yazma araçlarından ayırın ve yıkıcı olan her şeye insan onay kapısı koyun. MCP spesifikasyonunun araç anotasyonları tam bunun için var: destructiveHint yıkıcı güncellemeler yapan araçları işaretler, openWorldHint ise dış sistemlere dokunan araçları belirtir; böylece istemciler yürütmeden önce onay isteyebilir. Kullanın bunları.

Hata modu varsayımsal değil. Laurent Kubaski, Temmuz 2025 tool calling yazısında orijinal raporun bağlantısıyla birlikte bir vaka belgeledi: bir kullanıcı Excel'de Copilot'tan 4. satırda işlem yapmasını istedi, ajan bunun yerine 8. satırda işlem yaptı. Yanlış satır ile yazma işlemi arasında hiçbir onay kapısı yoktu. Çözüm, AWS'nin Bedrock Agents için belgelediği kalıptır: ajan işlemi hazırlar, onay için döndürür ve yalnızca bir insan onayladıktan sonra yürütür. Cursor dosya düzenlemeleri için aynısını yapar. Kimlik bilgilerini, görevin yalnızca okuma gerektirdiği durumlarda salt okunur olarak kapsamlayın ve onay kapılarını enjeksiyon yüzeyinizin bir parçası olarak ele alın; bu konuyu prompt injection önleme rehberimizde işliyoruz.

Uygulama 8: Her araç değişikliğinde eval döngüsü çalıştırın

Her araç değişikliğinden önce ve sonra küçük bir eval paketi çalıştırın ve metrikleri sabit bir sırayla okuyun. Paragon'ın optimizasyon rehberi, benimsemeye değer dört metrikli bir çerçeve önerir:

Anthropic'in gerçek Slack ve Asana MCP eval'ları üzerine kurulu tool evaluation cookbook'ı, iyi ve kötü eval görevlerinin nasıl göründüğünü gösterir:

# Weak: vague, many valid paths, impossible to score
"Use the Asana tools to organize some work."

# Strong: one correct tool, checkable arguments, binary outcome
"Create a task titled 'Renew TLS cert' in project 'Infra' assigned to [email protected], due 2026-08-15. Expect exactly one create_task call with those four fields."

Bizim yorumumuz, böyle etiketlenmiş olarak: yayınlanan sayılar size çalışma sırasını verir. Önce araç doğruluğunu kontrol edin; çünkü Anthropic'in kendi ölçümleri, açıklama ve adlandırma değişikliklerinin bunu doğrudan hareket ettirdiğini gösteriyor (206'dan 72 tokena yeniden yazım, UUID'den ada halüsinasyon bulgusu). Görev verimliliğini sona bırakın; çünkü o büyük ölçüde ilk üç metriğin zaten yakaladığı başarısızlıkları yansıtır. Başlangıç paketi için 15-30 görev tasarlayın, araç başına iki ya da üç; her biri tek bir beklenen çağrı ve ikili geçme koşuluyla. Bu boyut, bir açıklama yeniden yazımından kaynaklanan regresyonu bir haftalık etiketleme olmadan yakalamaya yeterlidir; cookbook'ın Slack ve Asana kurulumunu, bu kadar küçük bir paketin amaçlanan başlangıç noktası olduğunun kanıtı olarak okuyoruz, bir kısayol değil. Daha derin mekanikler production'da yapay zeka ajanlarını değerlendirme rehberimizde; eval sonuçlarınız araçların kendisinin iyi ama orkestrasyonun kötü olduğunu söylüyorsa, o zaman framework seçiminizi en iyi yapay zeka ajan framework'leri karşısında yeniden gözden geçirmenin zamanı gelmiştir.

Ajan tool calling ve MCP: fark ne?

MCP bir taşıma ve kayıt standardıdır, bir güvenilirlik katmanı değil; bu yüzden aynı sekiz uygulama, araçlarınız MCP üzerinden gelse de satır içi tanımlansa da geçerlidir. Yerel tool calling, model sağlayıcı sözleşmesidir: modelin bir tool_call yayınlama ve bir tool_result okuma biçimi. MCP, araçların modele nasıl ulaştığını standartlaştırır; modelin doğru olanı seçip seçmediği konusunda hiçbir şey yapmaz.

search adında ve "şeyleri arar" açıklamasıyla bir araç sunan bir MCP sunucusu, aynı şekilde tanımlanmış satır içi bir fonksiyonla özdeş şekilde hata verir. Tanımı düzeltin, sonra taşımayı dert edin. Model Context Protocol rehberimiz protokol tarafını uçtan uca ele alır.

Techsy bu sekiz uygulamayı nasıl uyguluyor

Her istemci ajan inşasında, başka bir şey yayınlanmadan önce bunlardan üçünü zorunlu tutarız: talimat olarak yazılmış açıklamalar (Uygulama 1), her yazma aracında doğrulama kapıları (Uygulama 6) ve bir olaydan sonra değil, dağıtımdan önce çalışan bir eval paketi (Uygulama 8). Bu üçü yanlış araç çağrılarını, yanlış argüman çağrılarını ve her ikisini yeniden getiren regresyonları kapsar; debug ettiğimiz her production ajan olayı tam da burada başladı. Diğer beş uygulama, ajan büyüdükçe takip eder. Ajanınız demo aşamasını geçtiyse ve yanlış araçları seçiyorsa, ücretsiz danışmanlık alın; sekiz uygulamadan hangisini önce düzeltmeniz gerektiğini söyleyelim.

Sıkça Sorulan Sorular

Ajan tool calling nedir?

Ajan tool calling, bir LLM'nin dış bir fonksiyonu çağırmaya karar verdiği, yapılandırılmış bir tool_call yayınladığı ve kodunuzun üzerinde akıl yürütebileceği bir tool_result döndürmesini beklediği mekanizmadır. Bir sohbet modelini veritabanlarını sorgulayabilen, API'leri çağırabilen ve eylem yapabilen bir ajana dönüştüren şey budur: model aracı ve argümanları seçer, yürütücünüz bunları çalıştırır.

Ajan tool calling döngüsü nasıl çalışır?

Döngü beş adımdan oluşur: kullanıcı isteği modele ulaşır, model bir araç seçer ve bir tool_call yazar, yürütücünüz bunu çalıştırır, bir tool_result modele döner ve model ya yanıt verir ya da başka bir çağrı yapar. Bu döngü görev bitene kadar tekrarlanır. Bu rehberdeki dört hata modu, bu döngünün belirli bir adımında yer alır.

Ajanım neden yanlış aracı seçiyor?

Genellikle iki araç örtüştüğü ve açıklamaları hangisinin hangisi olduğunu söylemediği için. Model yalnızca adlardan ve açıklamalardan seçim yapar; bu yüzden "bir kullanıcı getirir" ile "kullanıcıları bulur" birbirinin yerine geçebilir gibi okunur. İstisna satırlarıyla ("aramak için kullanmayın"), namespace'lenmiş adlarla ve bağlamdaki daha az araçla düzeltin. Kubaski'nin dört model testi, güçlü modellerin bile belirsiz listelerde yanlış yönlendiğini gösterdi.

Tool calling ajanını çıktısını yapılandırmaya nasıl zorlarım?

Şemayı kısıtlayın, prompt'u değil. Sınırlı alanlar için enum kullanın, görevin ihtiyaç duyduğu her şey için required dizileri kullanın ve iç içe nesneler yerine düz nesneler tercih edin. Araç çağrısı değil de son yanıt için, OpenAI'ın structured outputs ve Anthropic'in tool-choice modları gibi sağlayıcı özellikleri belirli bir şekli zorlar. Structured outputs rehberimiz her iki yolu da kodla ele alır.

Ajan tool calling ve MCP: fark ne?

Yerel tool calling, kodunuz ile tek bir model sağlayıcısı arasındaki sözleşmedir: tool_call ve tool_result mesaj formatı. MCP, araçların nasıl keşfedildiğini ve uyumlu herhangi bir istemciye nasıl iletildiğini standartlaştıran bir protokol katmanıdır. MCP tesisatı değiştirir, güvenilirliği değil. Kötü tanımlanmış bir araç, her iki yolda da aynı şekilde hata verir; Model Context Protocol rehberimizin açıkladığı gibi.

Bir LLM ajanı için kaç araç çok fazla?

Ajan başına 5-10 aracı çalışma aralığı olarak kabul edin, yasa olarak değil. Seçim doğruluğu, görünür liste büyüdükçe düşer; özellikle adlar ya da açıklamalar örtüştüğünde. Çözüm daha büyük bir model değil, filtrelemedir: mevcut görevin ihtiyaç duyduğu alt kümeyi yükleyin, planlayıcı-çalışan bölünmesi kullanarak. Her şeyi namespace'leyin; böylece iki entegrasyon asla aynı anda çıplak bir search sunmasın.

Tool calling için en iyi model hangisi?

Tek bir yanıt yok ve yayınlanan benchmark'lar bu alanda hızla eskir. OpenAI, Anthropic ve Google'ın sınır modelleri temel araç kullanımı görevlerini rahatça geçer; iyi tasarlanmış araçlarla eşleştirilmiş küçük modeller ise token maliyetinin çok altında bir bedelle görevleri neredeyse aynı sıklıkta tamamlar. Uygulama 8'deki 15-30 görevlik eval paketini oluşturun ve adayları kendi araçlarınıza karşı test edin.

Tool calling'den kaynaklanan token maliyetini nasıl azaltırım?

Geri geleni kesin. Ham API payload'ları yerine kısa, yüksek sinyalli sonuçlar döndürün: Anthropic tek bir response_format değişikliğinden 206'dan 72 tokena bir düşüş belgeledi. UUID'leri adlara çözün, modelin asla kullanmadığı alanları atın ve her araç sonucunun takip eden her turda bağlam penceresine yeniden girdiğini unutmayın. Atomik araçlarla daha az çağrı, bütün sonuçları faturadan kaldırır.

Tool calling kalitesini nasıl değerlendiririm?

Dört metriği sırayla puanlayın: araç doğruluğu (doğru araç mı?), girdi isabeti (geçerli argümanlar mı?), görev tamamlama (hedef gerçekleşti mi?) ve görev verimliliği (token ve çağrı sayısı?). 15-30 görev yazın; her biri kontrol edilebilir argümanlara ve ikili geçme koşuluna sahip tek bir belirli çağrı beklesin. Paketi her araç değişikliğinden önce ve sonra çalıştırın; böylece bir açıklama yeniden yazımı asla ölçülmeden yayınlanmasın.

Sonuç

Optimize etmeden önce teşhis edin. Ajanınız yanlış aracı dört nedenden biriyle seçiyor ve yukarıdaki sekiz uygulamadan üçü (açıklamalar, düz şemalar ve filtreleme) çoğu production olayını tetikleyen seçim hatalarını düzeltiyor. Oradan başlayın; çünkü bir öğleden sonra sürerler ve bu sorunun düzeltilebilir olmasının nedeni onlardır. Doğrulama hatalarını bilgilendirici tutun, yıkıcı olan her şeyi insan onayına bağlayın ve her değişiklikte eval döngüsünü çalıştırın; böylece model değiştirmeden önce ölçersiniz. Yanlış araç sorunu bir model sorunu değildir. Bir araç tasarımı sorunudur ve tasarım sizindir.