Message block'larını yönetmek

Bu modül için tahmini süre: 6 dakika

Genel bakış

Claude’un tool functionality’si ile çalışırken, daha önce gördüğünüz basit text response’lardan farklı bir yanıt yapısıyla karşılaşırsınız. Tek bir text block almak yerine, Claude artık hem text hem de tool kullanım bilgisi içeren multi-block message’lar döndürebilir. Bu derste tool-enabled API çağrılarının nasıl yapıldığını, multi-block message yapısını ve bunları conversation history’de nasıl saklayacağınızı göreceksiniz.

Tool destekli API çağrıları yapmak

Claude’un tool kullanabilmesi için API çağrınıza bir tools parametresi eklemeniz gerekir. İsteği şu şekilde yapılandırırsınız:

messages = []
messages.append({
    "role": "user",
    "content": "What is the exact time, formatted as HH:MM:SS?"
})

response = client.messages.create(
    model=model,
    max_tokens=1000,
    messages=messages,
    tools=[get_current_datetime_schema],
)

tools parametresi, Claude’un çağırabileceği mevcut fonksiyonları açıklayan JSON schema’ların listesini alır.

Multi-block message’ları anlamak

Claude bir tool kullanmaya karar verdiğinde, content list’inde birden çok block bulunan bir assistant message döndürür. Bu, daha önce çalıştığınız text-only yanıtlardan önemli bir değişikliktir.

Multi-block bir message tipik olarak şunları içerir:

• Text Block — Claude’un ne yaptığını açıklayan insan tarafından okunabilir metin (“I can help you find out the current time. Let me find that information for you” gibi)
• ToolUse Block — Hangi tool’un çağrılacağı ve hangi parametrelerin kullanılacağı konusunda kodunuza talimatlar

ToolUse block şunları içerir:

• Tool çağrısını takip etmek için bir ID
• Çağrılacak fonksiyonun adı (“get_current_datetime” gibi)
• Dictionary olarak formatlanmış input parametreleri
• “tool_use” type tanımı

Multi-block message’larla conversation history yönetmek

Claude’un conversation history’i saklamadığını unutmayın — bunu manuel olarak yönetmeniz gerekir. Tool yanıtlarıyla çalışırken tüm content yapısını, tüm block’lar dahil olmak üzere korumalısınız.

Multi-block bir assistant message’ı conversation history’e nasıl düzgün şekilde eklersiniz:

messages.append({
    "role": "assistant",
    "content": response.content
})

Bu, hem text block’u hem de tool use block’u korur; sonraki API çağrılarında conversation context’i sürdürmek için kritiktir.

Tam tool usage flow’u

Tool usage süreci şu pattern’i takip eder:

1. User message’ı tool schema ile Claude’a gönder
2. Text block ve tool use block içeren assistant message al
3. Tool bilgisini çıkar ve gerçek fonksiyonu çalıştır
4. Tool sonucunu tam conversation history ile birlikte Claude’a geri gönder
5. Claude’dan final response al

Her adım, Claude’un doğru yanıt sağlaması için ihtiyaç duyduğu tam context’e sahip olmasını garanti etmek üzere message yapısının dikkatli yönetimini gerektirir.

Helper function’ları güncellemek

add_user_message() ve add_assistant_message() gibi helper’lar kullanıyorsanız, bunları multi-block content’i yönetebilecek şekilde güncellemeniz gerekir. Mevcut versiyonlar muhtemelen sadece tek text block’u destekler; artık tool use block’larını da içeren daha karmaşık content yapılarını da kabul etmeleri gerekiyor.

Bu multi-block message yönetimi, Claude’un tool yeteneklerini sorunsuzca entegre ederken düzgün conversation flow’u koruyan sağlam uygulamalar inşa etmek için esastır.

Temel çıkarımlar

• tools parametresi API çağrısına bir JSON schema listesi olarak verilir
• Tool tetiklendiğinde assistant message artık text + ToolUse block’larından oluşan multi-block bir yapıdadır
• ToolUse block: id, fonksiyon adı, input dictionary ve type: tool_use içerir
• response.content’i olduğu gibi conversation history’e eklemek tüm block’ları korur — Claude’un sonraki turlarda context’e ihtiyacı vardır
• add_user_message / add_assistant_message gibi helper’lar artık string yerine block listesi de kabul etmeli
• Tool flow 5 adımdır: send → tool_use → execute → tool_result → final response