Claude API ile AI Uygulama Geliştirme

AquilaFlow'u geliştirirken Claude API ile derin bir entegrasyon kurdum. Multi-agent sistemler, streaming response, prompt caching ve tool use özelliklerini production'da deneyimledim. Bu yazıda Laravel uygulamasına Claude API'yi nasıl entegre edeceğinizi, maliyet optimizasyonu ve prompt engineering konularını aktarıyorum.

Temel Kurulum: Laravel'de Claude API

// config/services.php
'anthropic' => [
    'api_key' => env('ANTHROPIC_API_KEY'),
    'model'   => env('ANTHROPIC_MODEL', 'claude-sonnet-4-6'),
],

// app/Services/ClaudeService.php
class ClaudeService
{
    private string $apiKey;
    private string $model;
    private string $baseUrl = 'https://api.anthropic.com/v1';

    public function __construct()
    {
        $this->apiKey = config('services.anthropic.api_key');
        $this->model  = config('services.anthropic.model');
    }

    public function message(string $userMessage, string $systemPrompt = ''): string
    {
        $response = Http::withHeaders([
            'x-api-key'         => $this->apiKey,
            'anthropic-version' => '2023-06-01',
            'content-type'      => 'application/json',
        ])->post("{$this->baseUrl}/messages", [
            'model'      => $this->model,
            'max_tokens' => 4096,
            'system'     => $systemPrompt,
            'messages'   => [['role' => 'user', 'content' => $userMessage]],
        ]);

        if ($response->failed()) {
            throw new \RuntimeException('Claude API hatası: ' . $response->body());
        }

        return $response->json('content.0.text');
    }
}

Prompt Caching ile Maliyet Optimizasyonu

Prompt caching, uzun ve tekrarlı system prompt'lar için maliyeti %90'a kadar azaltabilir. Uzun dokümantasyonu veya örnek setleri içeren system prompt'lara cache_control ekleyin:

'system' => [
    [
        'type' => 'text',
        'text' => $longSystemPrompt,
        'cache_control' => ['type' => 'ephemeral'],
    ]
],
// Header ekle
'anthropic-beta' => 'prompt-caching-2024-07-31'

Streaming Response (SSE)

Uzun yanıtlar için kullanıcı ilk karakteri anında görmek ister. Server-Sent Events ile streaming implementasyonu:

public function stream(Request $request): StreamedResponse
{
    return response()->stream(function () use ($request) {
        $curl = curl_init();
        curl_setopt_array($curl, [
            CURLOPT_URL => 'https://api.anthropic.com/v1/messages',
            CURLOPT_POST => true,
            CURLOPT_HTTPHEADER => [
                'x-api-key: ' . $this->apiKey,
                'anthropic-version: 2023-06-01',
                'content-type: application/json',
            ],
            CURLOPT_POSTFIELDS => json_encode([
                'model' => $this->model,
                'max_tokens' => 4096,
                'stream' => true,
                'messages' => [['role' => 'user', 'content' => $request->message]],
            ]),
            CURLOPT_WRITEFUNCTION => function($ch, $data) {
                echo $data;
                ob_flush(); flush();
                return strlen($data);
            },
        ]);
        curl_exec($curl);
        curl_close($curl);
    }, 200, ['Content-Type' => 'text/event-stream', 'Cache-Control' => 'no-cache']);
}

Tool Use (Function Calling)

Claude'un veritabanınıza sorgu yapmasını, hesaplamalar yapmasını veya harici API'leri çağırmasını sağlayabilirsiniz. AquilaFlow'da kullandığım bir örnek:

'tools' => [
    [
        'name' => 'get_customer_orders',
        'description' => 'Belirtilen müşterinin siparişlerini getirir',
        'input_schema' => [
            'type' => 'object',
            'properties' => [
                'customer_id' => ['type' => 'integer'],
                'status' => ['type' => 'string', 'enum' => ['pending', 'completed', 'cancelled']],
            ],
            'required' => ['customer_id'],
        ],
    ],
]

Model Seçimi ve Maliyet Rehberi

• Claude Haiku 4.5: Hızlı, ucuz — basit sınıflandırma, triaj, kısa özetler
• Claude Sonnet 4.6: Güç/maliyet dengesi — çoğu production kullanım için ideal
• Claude Opus 4.7: En yetenekli — karmaşık analiz, kod yazma, çok adımlı reasoning

Production'da genellikle Sonnet ile başlayın. Belirli görevler için Haiku'ya, çok kritik analizler için Opus'a yönlendirin.