Akış Protokolü ve Gerçek Zamanlı Çıktı

Agent arayüzünüz 45 saniye boyunca hiçbir şey göstermiyor, sonra tüm yanıtı bir seferde aktarıyor. Kullanıcılar donmuş olduğunu düşünüyor. Çözüm tek bir bayrak — --output-format stream-json — ve birkaç satır NDJSON ayrıştırma.

stream-json protokolü, Claude CLI’ı gerçek zamanlı bir olay yayıcıya dönüştürür. Tüm yanıtı beklemek yerine, olaylar gerçekleşirken NDJSON olayları alırsınız — init meta verileri, token token metin, araç çağrıları, araç sonuçları, hız sınırları ve nihai özet. NDJSON (Newline Delimited JSON), satır başına bir JSON nesnesi anlamına gelir. Her olay, \n ile ayrılmış eksiksiz bir JSON nesnesidir. --input-format stream-json ile birleştirildiğinde, gerçek zamanlı arayüzler, agent zincirleri ve izleme panoları oluşturmak için çift yönlü iletişim sağlar.

Bu bölüme ihtiyacınız var eğer: özel arayüzler oluşturuyorsanız, gerçek zamanlı ilerleme çubukları uyguluyorsanız, panolar oluşturuyorsanız veya akış davranışını hata ayıklıyorsanız. Temel otomasyon için JSON modu daha basittir.

Akışı Etkinleştirme

Akış protokolünü etkinleştirmek için iki bayrak gerekir: --output-format stream-json çıktı modunu ayarlar ve --verbose tam oturum meta verilerini içeren init olayının yayılmasını sağlar. --verbose olmadan init olayı eksik olabilir — her zaman ikisini birlikte kullanın.

Çıktıdaki her satır eksiksiz, bağımsız bir JSON nesnesidir. Araç kullanımı olmayan basit bir prompt tam olarak dört olay üretir: system (init), assistant (yanıt), rate_limit_event (API durumu) ve result (nihai zarf).

Olay Türleri

Her olayın ne temsil ettiğini söyleyen bir type alanı vardır. Çoğu oturum 5 temel olay üretir: session_started -> input_sent -> started_working -> output_message -> completed. Diğerleri (tool_use, tool_result vb.) araç kullanımı, yeniden denemeler ve kısmi mesaj akışına bağlı olarak koşullu görünür.

İşte tam katalog:

Claude araç kullandığında, olaylar serpişir: bir assistant olayı araç çağrısını içerir (content[].type === "tool_use"), ardından araç sonucunu içeren bir user olayı gelir. Bu döngü, nihai assistant yanıtından önce her araç çağrısı için tekrarlanır.

Aşağıdaki etkileşimli görselleştirici gerçek bir akış oturumunu oynatır. Olayların nasıl sırayla geldiğini ve yanıtı nasıl oluşturduğunu izleyin.

Init Olayı

Her akıştaki ilk olay, oturum meta verilerini içeren bir system/init yüküdür. Bu, protokoldeki en zengin olaydır ve herhangi bir arayüz veya izleme sistemini başlatmanın anahtarıdır.

Init olayını sağlık kontrolleri (MCP sunucu bağlantılarını doğrulama), araç denetimleri (izin listelerini onaylama), sürüm sabitleme (claude_code_version kontrolü) ve arayüz başlatma (araç listeleri ve model adlarını doldurma) için kullanın.

Kısmi Mesajlar

Varsayılan olarak, yanıtın tamamını tek bir assistant olayında alırsınız. --include-partial-messages eklemek, her token parçası için stream_event girdileri ekleyerek metin üretildikçe render eden daktilo tarzı arayüzleri mümkün kılar.

stream_event girdilerinin sırası katı bir düzeni izler:

1. message_start — model kimliği, boş içerik
2. content_block_start — yeni metin bloğu başlar (indeks 0)
3. content_block_delta — artımlı token’lar: "\n\nHello", sonra "! How", sonra " can I help you today?"
4. content_block_stop — blok tamamlandı
5. message_delta — stop_reason: "end_turn", nihai kullanım istatistikleri
6. message_stop — akış tamamlandı

Tam assistant olayı (birleştirilmiş tam mesajla) tüm delta’lardan sonra görünür. Daktilo arayüzü için content_block_delta olaylarını gerçek zamanlı tüketin — assistant olayını beklemeyin.

Çift Yönlü İletişim

Akış protokolü yalnızca çıktı değildir. --input-format stream-json eklemek, stdout’ta olaylar alırken stdin aracılığıyla Claude’a mesaj göndermenizi sağlar — gerçek zamanlı arayüzler, agent orkestrasyon sistemleri ve özel IDE entegrasyonları oluşturmayı mümkün kılar.

# Tam çift yönlü mod
claude -p --input-format stream-json --output-format stream-json --verbose

Bu bayraklar için katı eşleşme kuralları vardır:

Birinin stream-json çıktısını diğerine pipe ederek Claude örneklerini de zincirleyebilirsiniz:

# İlk Claude analiz eder, ikinci Claude özetler
claude -p "Analyze auth.py" --output-format stream-json --verbose | \
  claude -p "Summarize the analysis" --input-format stream-json --output-format stream-json --verbose

İkinci örnek, birinciden gelen tüm olayları — araç sonuçları ve nihai yanıt dahil — kendi görevi için bağlam olarak alır.

Gerçek Akış Yükü

İşte gerçek bir CLI çağrısından tam dört olaylık akış. Bu, araç kullanımı olmayan basit bir prompt için --output-format stream-json --verbose’un tam olarak ürettiği şeydir.

Gerçek bir akışta, bu dört nesnenin her biri aralarında virgül veya köşeli parantez olmadan kendi satırında olurdu. Yukarıda gösterilen iç içe yapı, okunabilirlik için gruplandırılmıştır — gerçek NDJSON çıktısı satır başına bir JSON nesnesidir.

Akış Olaylarını Ayrıştırma

İşte bir Claude süreci başlatan ve ayrıştırılmış olayları geldikçe veren bir Node.js üreteci:

import { spawn } from 'child_process';
import { createInterface } from 'readline';

async function* streamClaude(prompt, { partial = false } = {}) {
    const args = ['-p', prompt, '--output-format', 'stream-json', '--verbose'];
    if (partial) args.push('--include-partial-messages');

    const proc = spawn('claude', args);
    const rl = createInterface({ input: proc.stdout });

    for await (const line of rl) {
        if (!line.trim()) continue; // bos satirlari atla
        try {
            yield JSON.parse(line);
        } catch (err) {
            console.warn(`Hatali JSON atlaniyor: ${line}`, err);
        }
    }
}

// Olay turune gore dagit
for await (const event of streamClaude('Explain recursion')) {
    switch (event.type) {
        case 'system':
            if (event.subtype === 'init') {
                console.log(`Model: ${event.model}, Tools: ${event.tools.length}`);
            }
            break;
        case 'assistant':
            console.log(`Response: ${event.message.content[0].text}`);
            break;
        case 'result':
            console.log(`Cost: $${event.total_cost_usd.toFixed(4)}`);
            break;
    }
}

Üretim ayrıştırıcıları şunları yönetmelidir: eksik satırlar (\n’ye kadar tamponla), hatalı JSON (günlükle ve atla), beklenmeyen olay türleri (uyar ama devam et). Yukarıdaki örnek temel hata yönetimini gösterir — stdin’i parçalar halinde işliyorsanız tamponlama mantığı ekleyin.

Daktilo efekti için kısmi mesajları etkinleştirin ve metin delta’larını filtreleyin:

process.stdout.write('Claude says: ');
for await (const event of streamClaude('Write a haiku', { partial: true })) {
    if (event.type === 'stream_event') {
        const delta = event.event?.delta;
        if (delta?.type === 'text_delta') {
            process.stdout.write(delta.text);
        }
    }
}
console.log();

Yeniden Deneme Olayları

API yeniden denenebilir bir hata döndürdüğünde (hız sınırı veya sunucu hatası), yeniden deneme girişiminden önce bir system/api_retry olayı görünür. Bunu, arayüzünüzde yeniden deneme ilerlemesini göstermek veya özel geri çekilme mantığı uygulamak için kullanın.

{
    "type": "system",
    "subtype": "api_retry",
    "attempt": 1,
    "max_retries": 5,
    "retry_delay_ms": 2000,
    "error_status": 529,
    "error": "server_error"
}