Claude Sonnet 4: Geliştiriciler için Uygulamalı Bir Rehber

Anthropic kısa süre önce güncellenmiş Claude Sonnet 4.5, Claude Agents SDK ve Imagine with Claude sürümlerini yayımladı.

Claude Sonnet 4’ün yayımlanmasıyla geliştiriciler artık yerel kod çalıştırma, esnek bir Files API ve dinamik araç kullanımı dâhil olmak üzere güçlü yeni yeteneklere erişebiliyor. Bu özellikler, basit metin etkileşimlerinin ötesine geçen yapay zeka destekli uygulamalar oluşturmak için heyecan verici olanaklar sunuyor.

Bu eğitimde, terminalinizden gelişmiş matematik problemlerini çözebilen Python tabanlı bir ajan oluşturarak bu yeni özellikleri adım adım göstereceğim. Yeni tanıtılan yerel kod çalıştırma aracını ve files API’yi kullanmayı öğreneceksiniz.

Sonunda, aşağıdakilere benzer görselleri oluşturabilen, problemleri analiz eden, Python kodu yazıp çalıştıran Claude Sonnet 4 destekli çalışan bir ajana sahip olacaksınız.

Bu projenin GitHub deposuna göz atarak uygulamanın tüm kodlarını görebilirsiniz.

Eğer Claude gibi LLM’lerle geliştirme yapmaya yeni başlıyorsanız, AI geliştirici yol haritası başlangıç için temel araçları, becerileri ve öğrenme yollarını özetler.

Anthropic API’de Neler Yeni?

Eğitime geçmeden önce, Anthropic API aracılığıyla sunulan yeni özelliklere hızlıca bakalım. Zaten biliyorsanız bu kısmı atlayabilirsiniz.

Bence tüm Claude 4 duyurusu şu tek görselle özetlenebilir:

Claude 4 modelleri (Opus ve Sonnet 4), doğrulanmış yazılım mühendisliği görevlerinde rakiplerini kayda değer bir farkla geride bırakıyor. Anthropic bunu, modellerin davranış biçimlerine birkaç önemli değişiklik getirerek başardı:

1. Uzun çalışma süreleri: Her iki model de binlerce adımdan oluşan problemleri çözmek için saatlerce kesintisiz görev yürütmeyi destekler.
2. Araç kullanımıyla genişletilmiş muhakeme: Modeller artık uzatılmış düşünme sırasında web araması gibi araçları kullanabiliyor; Claude’un yanıtlarını iyileştirmek için akıl yürütme ile araç kullanımını dönüşümlü uygulayabiliyor.
3. Paralel araç çalıştırma: Modeller artık araçları sırayla değil, eşzamanlı olarak kullanabiliyor.
4. Daha isabetli talimat izleme: Geliştirilmiş yönlendirilebilirlik, kullanıcıların uygulamalar üzerinde ve Claude’un talimatlara nasıl yanıt verdiği üzerinde daha fazla denetim sağlar.
5. Geliştirilmiş bellek yetenekleri: Yerel dosyalara erişim verildiğinde, modeller sürekliliği korumak ve zaman içinde zımnî bilgi oluşturmak için temel bilgileri çıkarıp kaydedebilir.
6. Azaltılmış kestirme davranışı: Önceki sürümlere kıyasla, her iki modelin de görevleri tamamlamak için kestirmeler veya açıklardan yararlanma olasılığı %65 daha düşüktür (ayrıntılar için tam duyuru yazısına bakın).

Ayrıca, Claude 4 model ailesi duyurusunun bir parçası olarak Anthropic, dört yeni özellik ekledi: kod çalıştırma aracı, Files API, MCP bağlayıcısı ve genişletilmiş prompt önbellekleme. Bu araçlar, geliştiricilerin yapay zeka uygulamalarını nasıl inşa edebileceğini değiştiriyor.

Kod çalıştırma aracı: Python kodunu güvenli şekilde çalıştırın

Kod çalıştırma aracı, Claude’un Python kodunu güvenli bir sandbox ortamında çalıştırmasını sağlar. Claude artık yalnızca kod önerileri yazmakla kalmayıp kodu çalıştırabilir, sonuçları analiz edebilir ve çözümler üzerinde yineleme yapabilir.

Kod çalıştırma aracını kullanmak için, onu tools dizinize ekleyin ve gerekli beta başlığını dahil edin:

from anthropic import Anthropic

# Initialize client with the code execution beta header
client = Anthropic(
   default_headers={
       "anthropic-beta": "code-execution-2025-05-22"
   }
)

# Send a request that triggers code execution
response = client.messages.create(
   model="claude-sonnet-4-20250514",
   max_tokens=4096,
   messages=[{
       "role": "user",
       "content": "Solve the quadratic equation 2x² + 5x - 3 = 0 and plot the parabola"
   }],
   tools=[{
       "type": "code_execution_20250522",
       "name": "code_execution"
   }]
)

Claude kod çalıştırdığında, yanıt hem üretilen kodu hem de çalıştırma sonuçlarını içerir. Farklı bileşenleri şu şekilde ayrıştırabilirsiniz:

# Parse the response to extract code and results
for item in response.content:
   if item.type == "server_tool_use":
       # This contains the actual Python code Claude wrote
       print(f"Code executed:\n{item.input['code']}")
   elif item.type == "code_execution_tool_result":
       # This contains the output from running the code
       print(f"Output:\n{item.content['stdout']}")
       if item.content.get('stderr'):
           print(f"Errors:\n{item.content['stderr']}")

Sandbox kısıtlamaları: Kod çalıştırma ortamında bir dizi yerleşik güvenlik kısıtlaması bulunur. Claude, internet erişimi olmayan, sınırlı hesaplama kaynaklarına sahip (1 GB RAM, 5 GB disk alanı ve 1 CPU) ve yerel dosya sisteminize erişemeyen ayrık bir kapsayıcıda çalışır. Ortam, numpy, pandas, matplotlib ve scipy gibi popüler kütüphaneler önceden yüklenmiş olarak gelir; ancak çalıştırma sırasında ek paketler kuramazsınız.

Files API: Karmaşık görevler için kalıcı dosya bağlamı

Files API, belgeleri bir kez yükleyip birden çok konuşmada referans vermenize olanak tanır. Bu, büyük belgeleri her API isteğine dahil etme ihtiyacını ortadan kaldırır.

İlk olarak dosyanızı Anthropic’in sunucularına yükleyin:

# Upload a file once - this stores it on Anthropic's servers
uploaded_file = client.beta.files.upload(
   file=open("sales_data.csv", "rb"),
   purpose="user_upload"
)
# The uploaded_file.id can now be referenced in multiple conversations

Yüklendikten sonra, API çağrılarınızda container_upload içerik tipini kullanarak dosyaya referans verin:

# Reference the uploaded file in a conversation
response = client.messages.create(
   model="claude-sonnet-4-20250514",
   max_tokens=4096,
   messages=[{
       "role": "user",
       "content": [
           {"type": "text", "text": "Create a quarterly sales report from this data"},
           {"type": "container_upload", "file_id": uploaded_file.id}
       ]
   }],
   tools=[{
       "type": "code_execution_20250522",
       "name": "code_execution"
   }]
)

Claude kod çalıştırma sırasında dosyalar oluşturduğunda (grafikler veya işlenmiş veriler gibi) bunları çıkarıp indirebilirsiniz:

# Extract file IDs of any files Claude created during execution
def extract_created_files(response):
   file_ids = []
   for item in response.content:
       if item.type == 'code_execution_tool_result':
           content = item.content
           if content.get('type') == 'code_execution_result':
               # Look for file objects in the execution results
               for file_obj in content.get('content', []):
                   if 'file_id' in file_obj:
                       file_ids.append(file_obj['file_id'])
   return file_ids

# Download any files Claude created
created_files = extract_created_files(response)
for file_id in created_files:
   file_content = client.beta.files.download(file_id)
   file_content.write_to_file(f"output_{file_id}.png")

MCP bağlayıcısı: Claude’u herhangi bir iş akışına bağlayın

MCP bağlayıcısı, Model Context Protocol desteğini doğrudan API’ye getirir. MCP’ler, özel entegrasyon kodu olmadan Claude’un veritabanları, API’ler ve verimlilik araçları gibi harici hizmetlere bağlanmasını sağlar.

Önceden MCP sunucularına bağlanmak için istemci altyapısı inşa etmek gerekiyordu. Artık API isteğinizde uzak bir MCP sunucu URL’si vermeniz yeterli; Claude mevcut araçları otomatik olarak keşfeder, bağlantıları yönetir ve kimlik doğrulamayı ele alır.

Bu, Zapier ve Asana gibi şirketlerden büyüyen bir MCP sunucuları ekosistemine erişim açarak, ajanın takviminizi okumasını, proje yönetim araçlarını güncellemesini veya yüzlerce başka hizmetle entegrasyon kurmasını mümkün kılar.

Claude Sonnet 4 ile Başlarken: Proje Genel Bakışı ve Kurulum

Artık yeni API özelliklerini anladığımıza göre, etkileşimli matematik problemi çözücümüzü inşa edelim. Claude’un kod çalıştırma yeteneklerini dosya işleme ile birleştirerek eksiksiz bir matematik asistanı oluşturacağız.

Uygulamamız doğal dildeki matematik sorularını kabul edecek, bunları çözmek için Python kodu çalıştıracak, görselleştirmeler oluşturacak ve kapsamlı raporlar kaydedecek.

Bu gibi projeleri yapılandırılmış bir yaklaşımla geliştirmek için Developing AI Applications eğitim yoluna göz atın.

> Not: Uzun kod bloklarını açıklamalarla böleceğimiz için, parçalarda girintileme her zaman tam doğru olmayabilir. Bu nedenle, takip ederken bu projenin GitHub deposunu ayrı bir sekmede açmanızı öneririz.

Adım 0: Claude Sonnet 4 proje ortamınızı kurun

Herhangi bir kod yazmadan önce geliştirme ortamımızı ve bağımlılıkları ayarlayalım.

Projeniz için yeni bir dizin oluşturun ve gerekli dosyaları ayarlayın:

mkdir math-solver
cd math-solver
touch math_solver.py demo_problems.py requirements.txt README.md

requirements.txt dosyasında gerekli bağımlılıkları oluşturun:

anthropic>=0.42.0

Bağımlılıkları yükleyin:

pip install -r requirements.txt

Anthropic API anahtarınızı bir ortam değişkeni olarak ayarlayın:

export ANTHROPIC_API_KEY="your-api-key-here"

Adım 1: Uygulama yapısını tasarlayın

MathSolver sınıfımızın temel yapısını oluşturarak başlayalım. Bu sınıf, ana işlevlerin tümünü yönetecek: API iletişimi, dosya yönetimi ve kullanıcı etkileşimi.

Önce, ithalatları ve temel yapıyı ayarlayalım:

#!/usr/bin/env python3
"""
Interactive Math Problem Solver using Claude 4 Code Execution Tool

This application allows users to ask math questions in natural language,
gets solutions using Claude's code execution capabilities, and saves
both visualizations and detailed markdown reports.
"""

import os
import json
import datetime
from pathlib import Path
from typing import List, Dict, Any
from anthropic import Anthropic

Şimdi ana sınıf yapımızı tanımlayalım:

class MathSolver:
   def __init__(self, api_key: str = None):
       """Initialize the Math Solver with Anthropic client."""
       # API setup and directory creation will go here
       pass

   def solve_problem(self, question: str) -> Dict[str, Any]:
       """Send a math question to Claude and get solution with code execution."""
       pass
Here are the methods for file and report handling:
def extract_files_from_response(self, response) -> List[str]:
       """Extract file IDs from Claude's response."""
       pass

   def download_files(self, file_ids: List[str]) -> List[str]:
       """Download files created by code execution to local storage."""
       pass

   def extract_code_blocks(self, response) -> List[str]:
       """Extract all code blocks from the response."""
       Pass

Son olarak, oturum yönetimini ve giriş noktasını ekleyelim:

def generate_markdown_report(self, result: Dict[str, Any], downloaded_files: List[str]) -> str:
       """Generate a comprehensive markdown report of the solution."""
       pass

   def run_interactive_session(self):
       """Run the main interactive session loop."""
       pass


def main():
   """Main entry point for the application."""
   pass

Bu yapı bize açık bir yol haritası sunuyor: başlatma, problem çözme, dosya işleme, rapor oluşturma ve kullanıcı etkileşimi. Her yöntem, matematik çözüm hattımızda belirli bir sorumluluğa sahip.

Claude Sonnet 4 Kod Çalıştırma ile Bir Matematik Çözücü İnşa Etme

Şimdi, Claude’un kod çalıştırma aracını ve akış (streaming) yanıtlarını kullanarak temel işlevselliği uygulayalım.

Adım 2: Claude’u güvenli API başlıklarıyla başlatın

__init__() yöntemini, API istemcisi kurulumunu ve dizin oluşturmayı ele alacak şekilde uygulayalım.

Önce, API anahtarı yönetimini ele alıyoruz:

def __init__(self, api_key: str = None):
   """Initialize the Math Solver with Anthropic client."""
   if not api_key:
       api_key = os.getenv("ANTHROPIC_API_KEY")
       if not api_key:
           raise ValueError(
               "Please set ANTHROPIC_API_KEY environment variable or provide api_key"
           )

Ardından, gerekli beta başlıklarıyla Anthropic istemcisini ayarlıyoruz:

# Initialize client with both code execution and files API headers
   self.client = Anthropic(
       api_key=api_key,
       default_headers={
           "anthropic-beta": "code-execution-2025-05-22,files-api-2025-04-14"
       },
   )

Son olarak, çıktı dizini yapısını oluşturuyoruz:

# Create organized output directories
   self.output_dir = Path("math_solver_output")
   self.images_dir = self.output_dir / "images"
   self.reports_dir = self.output_dir / "reports"

   self.output_dir.mkdir(exist_ok=True)
   self.images_dir.mkdir(exist_ok=True)
   self.reports_dir.mkdir(exist_ok=True)

   print(f"📁 Output directories created:")
   print(f"   • Images: {self.images_dir}")
   print(f"   • Reports: {self.reports_dir}")

Bu başlatma üç önemli şeyi yapar:

1. API anahtarı yönetimi: Önce ortam değişkenlerinde anahtarı kontrol eder, ardından parametreye geri döner.
2. İstemci kurulumu: Kod çalıştırma ve files API için her iki beta başlığıyla bir Anthropic istemcisi oluşturur.
3. Dizin yapısı: Görselleri ve raporları depolamak için düzenli klasörler oluşturur.

Adım 3: Çekirdek çözücü işlevini yazın

solve_problem() yöntemi, uygulamamızın kalbidir. İstekleri akış desteğiyle Claude’a gönderir.

İşlev imzası ve başlangıç kurulumuyla başlayalım:

def solve_problem(self, question: str) -> Dict[str, Any]:
   """
   Send a math question to Claude and get solution with code execution.
   """
   print(f"\n🤔 Thinking about: {question}")

   try:
       # Use streaming to show real-time progress
       with self.client.messages.stream(
           model="claude-sonnet-4-20250514",
           max_tokens=4096,
Now we configure the message and tool specification:
messages=[
               {
                   "role": "user",
                   "content": f"""Solve this math problem using code execution:

Problem: {question}

Please:
1. Solve the problem with actual Python code
2. Create visualizations using matplotlib if helpful
3. Save any plots as PNG files using plt.savefig()
4. Show your calculations step by step
5. Use descriptive filenames for saved plots

Execute Python code to solve this problem.""",
               }
           ],
           tools=[{"type": "code_execution_20250522", "name": "code_execution"}],
       ) as stream:
The streaming event processing handles real-time updates:
print("\n💭 Claude is working...")

           # Process streaming events and show progress
           for event in stream:
               if event.type == "content_block_start":
                   if hasattr(event.content_block, "type"):
                       if event.content_block.type == "text":
                           print("\n📝 Response:", end=" ", flush=True)
                       elif event.content_block.type == "server_tool_use":
                           print(f"\n🔧 Using tool: {event.content_block.name}")

Farklı akış olay türlerini ele alıyoruz:

	elif event.type == "content_block_delta":
                   if hasattr(event.delta, "text"):
                       print(event.delta.text, end="", flush=True)

               elif event.type == "content_block_stop":
                   print("", flush=True)  # New line

               elif event.type == "message_delta":
                   if hasattr(event.delta, "stop_reason"):
                       print(f"\n✅ Completed: {event.delta.stop_reason}")

Son olarak sonucu döndürüyoruz veya hataları ele alıyoruz:

	# Get the final message
           final_message = stream.get_final_message()

           return {
               "response": final_message,
               "question": question,
               "timestamp": datetime.datetime.now().isoformat(),
           }

   except Exception as e:
       print(f"❌ Error solving problem: {e}")
       return None

Bu işlev birkaç önemli kavramı gösterir:

• Akış desteği: Gerçek zamanlı geri bildirim almak için client.messages.create() yerine client.messages.stream() kullanıyoruz.
• Olay işleme: Akış API’si farklı olay türleri gönderir:
• content_block_start: Claude metin yazmaya veya bir aracı kullanmaya başladığında
• content_block_delta: İçerik üretilirken
• content_block_stop: Bir içerik bloğu tamamlandığında
• message_delta: Tüm ileti tamamlandığında
• Araç belirtimi: tools dizisine tam olarak "code_execution_20250522" türüyle kod çalıştırma aracını dahil ediyoruz.
• Yapılandırılmış istem: İstemimiz, Claude’u kod çalıştırmaya ve tüm görselleştirmeleri kaydetmeye açıkça yönlendirir.

Adım 4: Akış tabanlı kod çalıştırmayla matematik problemlerini çözün

Claude kod çalıştırma sırasında dosyalar oluşturduğunda (matplotlib grafikleri gibi), dosya kimliklerini çıkarmamız ve bunları yerel olarak indirmemiz gerekir.

Dosya çıkarma yöntemi, yanıt yapısı içinde gezinir:

def extract_files_from_response(self, response) -> List[str]:
   """Extract file IDs from Claude's response."""
   file_ids = []

   for item in response.content:
       if item.type == "code_execution_tool_result":
           content_item = item.content
          
           if isinstance(content_item, dict):
               if content_item.get("type") == "code_execution_result":
                   content_list = content_item.get("content", [])

Ardından, içerikte dosya kimliklerini ararız:

  for file_item in content_list:
                       if isinstance(file_item, dict) and "file_id" in file_item:
                           file_ids.append(file_item["file_id"])

   return file_ids

İndirme süreci, dosyaları getirir ve yerel olarak kaydeder:

def download_files(self, file_ids: List[str]) -> List[str]:
   """Download files created by code execution to local storage."""
   downloaded_files = []

   for file_id in file_ids:
       try:
           # Get file metadata and download content
           file_metadata = self.client.beta.files.retrieve_metadata(file_id)
           filename = file_metadata.filename
          
           file_content = self.client.beta.files.download(file_id)
           local_path = self.images_dir / filename
           file_content.write_to_file(str(local_path))

İndirilen dosyaları takip eder ve hataları ele alırız:

downloaded_files.append(str(local_path))
           print(f"✅ Downloaded: {filename}")

       except Exception as e:
           print(f"❌ Error downloading file {file_id}: {e}")

   return downloaded_files

• Dosya çıkarma mantığı: extract_files_from_response() yöntemi, yanıt yapısında dosya kimliklerini bulmak için gezinir. Kod çalıştırma sonuçları belirli bir biçimde iç içe geçmiştir ve dosyalar content dizisinde görünür.
• Dosya indirme süreci: download_files() yöntemi şunları yapar:
• Her dosya için (orijinal dosya adı dâhil) meta verileri alır
• Files API’yi kullanarak içeriği indirir
• Dosyaları düzenli dizin yapımıza kaydeder
• Daha sonra kullanım için yerel dosya yollarının bir listesini döndürür