Code execution ve Files API

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

Genel bakış

Anthropic API’nın iki güçlü feature’ı — Files API ve Code Execution — birlikte çalıştığında karmaşık task’ları Claude’a delege etmeyi mümkün kılar. Bu derste dosyaları nasıl upload edeceğini, Claude’un izole Docker container’da Python çalıştırmasını ve üretilen output’ları indirme akışını öğreneceksin.

Anthropic API, birlikte istisnai biçimde iyi çalışan iki güçlü feature sunar: Files API ve Code Execution. İlk başta ayrı görünseler de, ikisini birleştirmek Claude’a karmaşık task’ları delege etme konusunda gerçekten ilginç olanaklar açar.

Files API

Files API, file upload’larını ele almak için alternatif bir yol sağlar. Image’ları veya PDF’leri mesajlarında base64 data olarak doğrudan encode etmek yerine, dosyaları önceden upload edip daha sonra referans verebilirsin.

Şöyle çalışır:

• Dosyanı (image, PDF, text, vb.) ayrı bir API çağrısıyla Claude’a upload et
• Benzersiz bir file ID içeren file metadata objesi al
• Gelecekteki mesajlarda ham file data yerine o file ID’ye atıfta bulun

Bu yaklaşım, aynı dosyaya birden çok kez atıfta bulunmak istediğinde veya her request’e dahil etmenin sıkıntılı olacağı daha büyük dosyalarla çalışırken özellikle faydalıdır.

Code Execution tool

Code execution, implementasyon sağlamanı gerektirmeyen server-based bir tool’dur. Request’inde önceden tanımlı bir tool schema’sını dahil edersin ve Claude opsiyonel olarak izole bir Docker container’da Python code çalıştırabilir.

Code execution ortamının temel özellikleri:

• İzole bir Docker container’da çalışır
• Network erişimi yok (external API çağrıları yapamaz)
• Claude tek bir conversation sırasında code’u birden çok kez execute edebilir
• Sonuçlar Claude tarafından yakalanır ve final response için yorumlanır

Files API ve Code Execution’ı birleştirmek

Gerçek güç, bu feature’ları birlikte kullanmaktan gelir. Docker container’ların network erişimi olmadığı için, Files API execution ortamına data girip çıkarmanın birincil yolu olur.

Tipik bir workflow:

1. Data dosyanı (CSV gibi) Files API kullanarak upload et
2. Mesajına file ID ile bir container upload block dahil et
3. Claude’tan veriyi analiz etmesini iste
4. Claude dosyanı işlemek için code yazar ve execute eder
5. Claude indirebileceğin output’lar (plot gibi) üretebilir

Pratik örnek

Streaming service data’sı kullanan gerçek bir örneğe bakalım. CSV dosyası subscription tier’lar, izleme alışkanlıkları ve churn ettiler mi (abonelik iptal ettiler mi) bilgisi dahil user bilgilerini içerir.

Önce, bir helper function ile dosyayı upload et:

file_metadata = upload('streaming.csv')

Sonra hem upload edilen dosyayı hem de bir analiz talebini içeren bir mesaj oluştur:

messages = []
add_user_message(
    messages,
    [
        {
            "type": "text",
            "text": """Run a detailed analysis to determine major drivers of churn.
            Your final output should include at least one detailed plot summarizing your findings."""
        },
        {"type": "container_upload", "file_id": file_metadata.id},
    ],
)

chat(
    messages,
    tools=[{"type": "code_execution_20250522", "name": "code_execution"}]
)

Response’u anlamak

Claude code execution kullandığında, response birden fazla block tipi içerir:

• Text blocks — Claude’un analizi ve açıklamaları
• Server tool use blocks — Claude’un çalıştırmaya karar verdiği gerçek code
• Code execution tool result blocks — Code’u çalıştırmaktan gelen output

Claude, tek bir response sırasında analizini iteratif şekilde inşa ederek code’u birden fazla kez execute edebilir. Her execution döngüsü code’u ve sonuçlarını içerir.

Üretilen dosyaları indirmek

En güçlü feature’lardan biri, Claude’un dosyalar (plot veya rapor gibi) üretip indirme için kullanılabilir hale getirme yeteneğidir. Claude bir visualization oluşturduğunda container’da saklanır ve onu Files API kullanarak indirebilirsin.

Response’da type: "code_execution_output" block’larını ara — bunlar üretilen içerik için file ID’leri içerir:

download_file("file_id_from_response")

Sonuç, üretilmesi önemli miktarda manuel coding gerektirecek profesyonel visualization’lar ile kapsamlı bir analizdir.

Data analysis’in ötesinde

Data analysis doğal bir uyum olsa da, Files API ve code execution kombinasyonu birçok olanak açar:

• Image processing ve manipülasyonu
• Document parsing ve transformation
• Matematiksel hesaplamalar ve modelleme
• Özel formatlama ile rapor üretimi

Anahtar şu: Files API üzerinden input ve output’lar üzerinde kontrolü korurken karmaşık, computational task’ları Claude’a delege edebilirsin. Bu, Claude’un çözümleri gerçekten execute edip üzerinde iterate edebilen bir coding assistant olduğu güçlü bir workflow yaratır.

Temel çıkarımlar

• Files API ile dosya önceden upload edilip file ID ile referans verilir; base64’e gerek kalmaz
• Code Execution, izole bir Docker container’da Python çalıştırır; network erişimi yoktur
• Container’a data Files API üzerinden girer; çıktılar yine Files API ile indirilir
• Response birden fazla block içerir: text, server tool use, code execution result
• Data analysis, image processing, raporlama gibi computational işler bu kombinasyon ile Claude’a delege edilebilir