Tool Use ve Function Calling: Agent Mimarisi için Multi-Step Prompt Tasarımı

Tek-turn chatbot'tan multi-step ajana

Bir chatbot kullanıcının sorusuna metin cevabı döner. Bir ajan ise: soruyu anlar, hangi araçları kullanması gerektiğini düşünür, araçları çağırır, sonuçları yorumlar, gerekirse başka araçlar çağırır, döngüyü tamamladığında nihai cevabı sunar. Aradaki fark planlama ve eylem.

2023'ten beri "agent" kavramı popülerleşti ama production-ready bir ajan kurmak halen kolay değil. Bu yazıda tool use protokolünün nasıl çalıştığını, JSON schema tasarımı, multi-step orchestration, hata yönetimi ve maliyet kontrolü pratik bir çerçeve olarak veriyorum.

Tool use protokolü nasıl çalışır

Üç major LLM sağlayıcısının paradigmaları aynı, isimleri farklı:

• Anthropic Claude: tools parametresi, tool_use ve tool_result content block'ları
• OpenAI: tools parametresi, function_call ve tool_response mesajları (GPT-5 ile birleşik)
• Google Gemini: tools.functionDeclarations, functionCall ve functionResponse

Tipik bir Claude tool definition:

{
  "name": "search_pubmed",
  "description": "PubMed veritabanında biyomedikal makale arama yapar. Anahtar kelime, yıl aralığı ve maksimum sonuç sayısı kabul eder. Sonuç olarak PMID listesi, başlık ve özet döner.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "PubMed query string, boolean operatörler desteklenir (AND, OR, NOT)"
      },
      "year_from": {
        "type": "integer",
        "description": "Başlangıç yılı, default 2020"
      },
      "max_results": {
        "type": "integer",
        "description": "Maksimum sonuç sayısı, default 20, üst sınır 100"
      }
    },
    "required": ["query"]
  }
}

Model bu tanımı gördüğünde, kullanıcı "diz osteoartriti yapay zeka segmentasyonu 2024'ten beri" diye sorduğunda şöyle bir tool_use üretir:

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "search_pubmed",
  "input": {
    "query": "(knee osteoarthritis) AND (artificial intelligence) AND (segmentation)",
    "year_from": 2024,
    "max_results": 20
  }
}

Uygulamanız bu çağrıyı alır, gerçek PubMed API'yi çağırır, sonucu tool_result olarak modele geri besler:

{
  "type": "tool_result",
  "tool_use_id": "toolu_abc123",
  "content": "[{\"pmid\": \"38123456\", \"title\": \"...\", \"abstract\": \"...\"}, ...]"
}

Model sonucu okur, kullanıcıya cevap üretir veya başka tool çağırır.

JSON schema disiplini

Tool use başarısı %80 schema tasarımına bağlıdır. Üç kural:

1. Description aşırı net olmalı. Model fonksiyonu seçmek için sadece tanımı okur. "search_pubmed" ismi yetmez, description'da ne yaptığı, ne dönüğü, ne zaman kullanılacağı yazılır.

Kötü: "description": "Searches PubMed" İyi: "description": "Searches PubMed for biomedical articles. Use this when the user asks about medical research, clinical studies, or wants to find publications. Returns PMID, title, abstract, journal, authors and publication date. Does NOT return full text. Maximum 100 results per query. For full text retrieval, use get_full_text_article instead."

2. Parametre tipleri katı olmalı. String yerine enum, generic object yerine spesifik schema, optional vs required net.

"modality": {
  "type": "string",
  "enum": ["CT", "MR", "X-RAY", "US"],
  "description": "Görüntüleme modalitesi"
}

vs

"modality": {
  "type": "string",
  "description": "Görüntüleme türü"
}

İlki modelin sıklıkla doğru değer üretmesini sağlar. İkincisi "Computed Tomography", "ct", "CT scan" gibi varyasyonlara açıktır.

3. Required field'lar minimum tutulmalı. Çok required olursa model fonksiyonu çağırmaktan çekinir veya boş değer üretir. Default'u olan field'ları optional yapın, gerçekten gerekli olanlar required.

Tool seçimi nasıl yönlendirilir

Modelin doğru tool'u seçmesi için iki teknik:

System prompt direktifi:

You have access to the following tools. Use them as follows:
- search_pubmed: First step when user asks about medical literature
- get_full_text_article: After identifying relevant articles, retrieve full text
- summarize_article: After retrieving full text, generate a summary
- create_systematic_review_table: Final step, organize summaries into PRISMA-style table

Always plan multi-step tasks before executing. Use tools in sequence.
Do not retrieve full text for more than 10 articles in a single conversation.

Tool choice parameter: Anthropic ve OpenAI'da tool_choice opsiyonu:

• auto: model serbest karar
• any: bir tool kullanmalı (hangisi kendi seçer)
• tool: {name: "X"}: spesifik tool zorla çağırılır

İlk turn'lerde auto, kritik karar noktalarında spesifik tool zorlama.

Multi-step orchestration pattern'ları

Üç temel agent pattern:

1. ReAct (Reasoning + Acting): Model her adımda thought + action + observation üretir. Yao 2022 makalesinin tanımladığı klasik döngü:

Thought: Kullanıcı diz osteoartritinde AI segmentasyonu sistematik derleme istiyor. Önce literatür taramam lazım.
Action: search_pubmed(query="...", year_from=2020)
Observation: 47 sonuç döndü.
Thought: 47 sonuç fazla, ilk 10'unu detaylı incelemeliyim.
Action: get_full_text_article(pmid="38123456")
...

2. Plan-and-Execute: Model önce tüm planı çıkarır, sonra sırasıyla uygular. Daha az LLM call, daha az maliyet. Ama plan kötüyse tüm execution boşa gider.

Plan:
1. PubMed search ile son 5 yıllık makaleleri bul
2. PRISMA flow için tarama-eleme yap
3. Dahil edilen makalelerin full text'ini al
4. Her birinin metodolojik kalitesini değerlendir
5. Veri çıkarımı yap
6. Final tablo oluştur

Executing step 1...

3. Tree of Thoughts (multi-branch exploration): Model her adımda birden fazla yol dener, en iyi olanı seçer. Karmaşık planning gerektirir, maliyet yüksek. Production'da nadiren gerekli.

Pratik öneri: Basit task'lar için Plan-and-Execute. Belirsiz / dinamik task'lar için ReAct. Tree of Thoughts araştırma kontextinde, production'da değil.

Hata yönetimi

Tool execution sırasında ne hata olabilir, nasıl handle edilir:

1. Tool execution failure. API down, timeout, rate limit. Tool_result'a hata mesajı yazılır:

{
  "type": "tool_result",
  "tool_use_id": "toolu_abc123",
  "is_error": true,
  "content": "PubMed API timeout after 30s. Retry suggested."
}

Model bu durumda retry, alternative tool seçimi veya kullanıcıya bilgi verme yoluna gidebilir.

2. Schema validation failure. Model required parametreyi unutmuş veya tipini yanlış üretmiş. Uygulama tarafında JSON schema validator (Ajv, Pydantic) ile yakalanır, modele "input invalid, please retry" diye geri beslenir.

3. Halüsinasyon araç. Model tanımlanmamış bir tool çağırmaya çalışır ("ben şimdi summarize_with_grok() çağırıyorum"). Uygulama unknown tool reject eder, modele bildirir.

4. Sonsuz döngü. Model aynı tool'u defalarca çağırır, ilerleme yok. Max iteration guard (örnek: 20 turn) zorunludur. Limit aşılınca konuşmayı sonlandır, kullanıcıya partial result ver.

5. Veri PII sızıntısı. Tool result'ta hassas veri varsa (TCKN, hasta adı), bu veri model context'ine girer, sonraki tool çağrılarında diğer servislere sızabilir. Tool layer'da PII filtering veya redaction zorunludur.

Maliyet optimizasyonu

Multi-step agent'lar tek-turn LLM call'a göre 5-20x daha pahalı olabilir. Üç optimizasyon:

1. Tool definitions cache. Anthropic prompt caching ile tool definition'lar (genelde 2-5 bin token) cache'lenir. Birden fazla turn aynı cache'i kullanır.

2. Tool result truncation. PubMed'den 100 makale dönerse, model'e 100 makale full göndermek gereksiz. İlk 10 başlık, kalan 90'ı özet (pagination ile sonradan istenebilir).

3. Model tiering. Planning ve tool selection büyük model (Claude Opus 4.7, GPT-5). Basit summarization küçük model (Claude Haiku 4.5, GPT-4o-mini). Tek bir agent içinde router pattern.

4. Erken durma. Eğer ilk 3 tool call sonucu kullanıcı sorusunu cevaplamaya yetiyorsa, model "yeter" demeli. System prompt'ta net: "Use minimum number of tool calls. Stop as soon as you have sufficient information."

Production checklist

Bir tool-use agent'ı production'a çıkarmadan önce:

• Tool schema'ları JSON Schema validator'dan geçiyor mu
• Her tool için unit test (mock LLM çağrısı)
• Integration test (gerçek LLM, gerçek tool)
• Max iteration guard set edilmiş mi (default 20)
• Tool execution timeout (default 30s, kritik tool'larda 60-120s)
• Rate limiting (kullanıcı başına dakika başına max tool call)
• Error tracking (Sentry, Datadog) tool failure rate
• Cost monitoring (token + tool execution cost)
• PII filter tool result'larda
• Audit log (kim hangi tool'u çağırdı, hangi argümanla)
• Fallback path (tool down ise insan'a escalate)

Real-world ajan örnekleri

Akademik araştırma asistanı:

• Tools: search_pubmed, get_full_text, extract_data, generate_prisma_diagram, format_vancouver_references
• Workflow: Soru → literatür ara → ilgili olanlar full text → veri çıkar → PRISMA + referans listesi
• Maliyet: ~1-3 USD per kullanım (15-30 dk insan iş)

Kurumsal müşteri destek ajanı:

• Tools: search_kb, lookup_order, create_ticket, send_email, escalate_to_human
• Workflow: Müşteri sorusu → bilgi bankası ara → spesifik müşteri bilgisi gerekirse order_lookup → çözülmezse ticket
• Maliyet: ~0.05-0.20 USD per konuşma

Veri analiz ajanı:

• Tools: query_database, run_python, plot_chart, summarize_findings
• Workflow: Analiz sorusu → SQL üret → veri al → Python analiz → görselleştir → özet
• Maliyet: ~0.50-2 USD per analiz

MCP ile tool tanımlama

Anthropic'in MCP (Model Context Protocol) tool definition'larını standardize ediyor. MCP server tools, prompts, resources sağlayan bir interface. Claude Code, Claude Desktop, custom uygulamalar aynı MCP server'a bağlanabilir.

Avantajı: tool tanımını bir kez yaz, birçok client'tan çağır. Anthropic, Google, OpenAI ekosistemleri MCP'yi 2025-2026 boyunca benimsedi.

Bir basit MCP server tipik şu yapıyı sunar:

• tools/list: mevcut araçlar
• tools/call: aracı çalıştır
• resources/list: erişilebilir kaynaklar (örnek: dokümanlar)
• prompts/list: hazır prompt template'leri

Bir kurumsal AI mimarisi MCP server'lar üzerinden tool'ları standardize edip Claude, GPT, Gemini agent'larını aynı backend'e bağlayabilir.

Pratik çekirdek kontrol listesi

Tool-use agent'ı sağlıklı kurmak için:

• Her tool için açık ve detaylı description
• Required parametre minimum, optional default'lu
• Enum kullan, generic string'den kaçın
• System prompt'ta tool kullanım rehberi
• Plan-and-Execute veya ReAct pattern seçimi netleşmiş
• Max iteration guard
• Tool timeout
• Schema validator tool input'unda
• Error handling her tool için (retry, fallback, escalate)
• PII filter tool result'unda
• Cost monitoring
• Audit log
• A/B testing yeni tool eklerken

Sık yapılan üç hata

Hata 1: Çok tool, az açıklama. 30 tool tanımlayıp her birine 1 cümle description vermek. Model kaybolur, yanlış tool seçer. 10 iyi tanımlanmış tool > 50 vague tool.

Hata 2: Hata recovery yok. Tool fail eder, model crash. Production'da her tool'un fail mode'u düşünülmeli, model'e "retry / alternative / give up" seçenekleri verilmeli.

Hata 3: Maliyet kör nokta. Multi-step agent build edip cost monitoring kurmamak. İlk hafta 50 USD beklerken 5000 USD fatura görürsünüz. Token + tool execution cost'u her turn track edin.

Tool use ve agent mimarisi için Serteser Danışmanlık desteği

Production-ready agent tasarımı LLM bilgisi + sistem mimarisi + sektörel domain expertise gerektirir. Serteser Danışmanlık şu alanlarda destek sunar:

• Tool use schema mimarisi (Anthropic, OpenAI, Gemini)
• MCP server tasarımı
• Multi-step agent pattern seçimi (ReAct vs Plan-Execute)
• RAG + agent hibrit sistemleri
• Hata yönetimi, retry mekanizması, fallback path
• Cost optimization, model tiering
• PII / KVKK uyumlu tool layer
• Audit log ve monitoring kurulumu
• Production deployment ve A/B testing

The Orthopaedic Journal of Sports Medicine'de yayınlanmış uluslararası hakemli klinik araştırma deneyimi ve aktif sistematik derleme yönetimi ile teknik sistem mimarisi + araştırma yöntemi iki disiplini birlikte sunan bir araştırma altyapısıyla, agent ve tool use projelerinde uçtan uca destek sağlıyoruz.