Bir persona ile sohbet oturumu kur

Bu rehber, ürettiğin bir persona ile nasıl konuşulduğunu adım adım gösterir: oturum aç, mesaj gönder, gelen yanıtın yanındaki drift zarfını (envelope) oku, istersen token-token akıt, geçmişi (transcript) geri al, oturumu kapat.

Bir persona ile konuşmak iki kavramı birleştirir. Sohbet oturumu (chat session) persona'nın çalışma zamanı konteyneridir — bağlam penceresini (context window), bellek göstericilerini ve mesaj geçmişini taşır. Drift zarfı ise her yanıtın yanında dönen küçük JSON: bu mesaj karakterin sesine ne kadar yakın?

Bu rehberi bitirdiğinde

• Bir persona'ya karşı oturum açıp mesaj gönderebileceksin.
• Yanıtın yanındaki driftScore / driftThreshold / driftAlert alanlarını yorumlayabileceksin.
• Token-token akış (streaming) ile yanıtları akıtabileceksin.
• Geçmişi sayfa sayfa okuyabilecek, oturumu temiz kapatabileceksin.

Ön koşul: bir persona kimliği (per_…) ve API anahtarın olmalı. Persona'n yoksa önce İlk persona'yı baştan sona üret ile geç.

1. Bir oturum aç

Her oturum bir persona'ya bağlıdır. metadata isteğe bağlıdır; serbest metin → metin sözlüğüdür ve denetim kaydında + webhook gönderimlerinde görünür — oturumu kendi ürün yüzeyine (destek bileti, konuşma kimliği vb.) bağlamak için kullan.

import Moonborn from '@moonborn/sdk';
 
const client = new Moonborn({ apiKey: process.env.MOONBORN_API_KEY });
 
const session = await client.chat.sessions.create({
  personaId: 'per_01H...',
  metadata: { ticketId: 'cs-4421' },
});
 
console.log(session.id);

Beklenen yanıt:

{
  "id": "ses_01H...",
  "personaId": "per_01H...",
  "status": "active",
  "createdAt": "2026-05-17T10:00:00Z"
}

Oturum kimliğini (ses_…) sonraki her mesajda kullanacaksın.

2. Bir mesaj gönder

const reply = await client.chat.messages.create({
  sessionId: session.id,
  content: 'Üretmeye devam etmeni ne tetikliyor?',
});
 
console.log(reply.content);
console.log({
  driftScore: reply.driftScore,
  driftThreshold: reply.driftThreshold,
  driftAlert: reply.driftAlert,
});

Beklenen yanıt (kısaltılmış):

{
  "id": "msg_01H...",
  "role": "assistant",
  "content": "Beni tetikleyen şey aradaki boşluk. Durduğum an birinin başkası olarak ortaya çıkacağını hissediyorum.",
  "driftScore": 0.14,
  "driftThreshold": 0.30,
  "driftAlert": false
}

Drift zarfını nasıl okurum?

Her yanıt karakterin voice fingerprint'ine olan benzerliğine göre puanlanır:

• driftScore — yanıtın imza sesten uzaklığı. 0'a yakınsa karakterdedir, 1'e yakınsa jenerik asistan tonuna kaymıştır.
• driftThreshold — çalışma alanının eşiği (varsayılan 0.30). Bu değer yapılandırmadan gelir.
• driftAlert — driftScore > driftThreshold olduğunda true döner.

3. Yanıtı token-token akıt (stream)

Akış (streaming), her token'ın önemli olduğu kullanıcı deneyimi için (sohbet botu, agent paneli) doğal seçimdir.

const stream = await client.chat.messages.stream({
  sessionId: session.id,
  content: 'Üretmeye devam etmeni ne tetikliyor?',
});
 
for await (const chunk of stream) {
  if (chunk.type === 'token') {
    process.stdout.write(chunk.delta);
  }
  if (chunk.type === 'completed') {
    console.log('\n\ndrift:', chunk.driftScore, chunk.driftAlert);
  }
}

SSE parça (chunk) deseni:

event: token       data: {"delta": "Beni tetikleyen"}
event: token       data: {"delta": " şey aradaki boşluk."}
event: completed   data: {"messageId": "msg_...", "driftScore": 0.14, "driftAlert": false}

Hat formatı detayı: Akış desenleri.

4. Geçmişi oku

Geçmiş imleç (cursor) + sınır (limit) ile sayfalanır.

const page = await client.chat.messages.list({
  sessionId: session.id,
  limit: 20,
});
 
for (const m of page.data) {
  console.log(`[${m.role}]`, m.content);
}
 
if (page.nextCursor) {
  const next = await client.chat.messages.list({
    sessionId: session.id,
    cursor: page.nextCursor,
  });
}

5. Oturumu kapat

await client.chat.sessions.end({ sessionId: session.id });

end (sonlandır), geriye dönük sorgular için geçmişi ve belleği korur (yumuşak kapanış). Veriyi tamamen silmek istiyorsan DELETE /v1/chat/sessions/{id} kullan — yumuşak silme penceresi çalışma alanı yapılandırmasından gelir (privacy.retention.chat_sessions_days).

Yaygın sorunlar

Başardın

Elinde bir ses_… kimliği, bir msg_… ile başlayan yanıt ve drift zarfı (driftScore, driftThreshold, driftAlert) varsa rehber bitti.

Sonraki adım