---
title: System Prompt Tasarımı | Callby.ai Dokümantasyon
description: "Callby.ai temsilcileri için System Prompt tasarımı: kapsam, karar kuralları, payload, sesli/yazılı kanal kısıtları ve senaryo bazlı test."
---

[Callby.ai](https://www.callby.ai/?hsLang=tr) Dokümantasyon

#### Başlangıç

[Genel bakış](https://callby-ai.mintlify.app/) [Hızlı başlangıç](https://callby-ai.mintlify.app/quickstart)

#### Temsilci kurulumu

[Temsilci ayarları](https://callby-ai.mintlify.app/guides/agent-setup) Prompt tasarımı [Bilgi tabanı](https://callby-ai.mintlify.app/guides/knowledge-base)

#### Çağrı yönetimi

[Telefon hatları](https://callby-ai.mintlify.app/guides/phone-numbers) [Kampanyalar](https://callby-ai.mintlify.app/guides/campaigns) [Çağrı kayıtları](https://callby-ai.mintlify.app/guides/call-history)

#### Yardım

[Sorun giderme](https://callby-ai.mintlify.app/help/troubleshooting)

Temsilci kurulumu

# System Prompt tasarımı

Temsilci davranışını bir spesifikasyon gibi tanımlayın: kapsam, karar kuralları, kanal kısıtları, çağrı bağlamı (payload) ve senaryo bazlı regresyon testi.

**System Prompt**, temsilcinin çalışma zamanındaki davranış sözleşmesidir. Her görüşmede modele bağlam olarak verilir ve karşılama mesajı, model profili ve bağlı bilgi tabanıyla birlikte temsilcinin yanıtlarını belirler. Bu sayfa, prompt’u tekrarlanabilir şekilde test edilebilen ve sürümlenebilen bir yapılandırma olarak ele alır.

NotPrompt, AI Studio’da **Temsilci** sekmesindeki **System Prompt** alanında düzenlenir. Kaydedilen değişiklik önce taslağa yazılır; canlı görüşmeler **Toplu Yayınla** ile yayınlanana kadar mevcut sürümü kullanmaya devam eder. Ayrıntılar: [Temsilci ayarları](https://callby-ai.mintlify.app/guides/agent-setup).

## Çalışma zamanı bileşenleri

Bir görüşmede temsilcinin davranışı aşağıdaki katmanların birleşimidir. Prompt’a yalnızca bu katmanlardan **davranış** olanları yazın.

| Katman | Nerede tanımlanır | Ne içermeli |
| --- | --- | --- |
| System Prompt | **Temsilci** sekmesi | Rol, kapsam, karar kuralları, görüşme akışı, çıktı biçimi |
| İlk Mesaj | **Temsilci** sekmesi | Sesli temsilcinin açılış cümlesi |
| Model Profili | **Model Profili** sekmesi | Konuşma dili, model ayarları; sesli temsilcide konuşmayı metne çevirme ve seslendirme ayarları |
| Bilgi tabanı | **Bilgi Tabanı** sekmesi | Sık değişen içerik: fiyat, koşul, prosedür, ürün bilgisi |
| Çağrı bağlamı (payload) | Kampanya listesindeki `payload` sütunu, test aramasında **Payload (JSON)** | Kişiye ya da çağrıya özgü veriler |

İpucuTemel kural: **davranış prompt’a, veri bilgi tabanına veya payload’a.** İade süresi gibi bir değeri prompt’a sabit yazarsanız, değer değiştiğinde yeni bir prompt sürümü yayınlamanız gerekir.

## Prompt yapısı

Prompt’u başlıklı bölümlere ayırın. Model için okunabilirliği artırır, ekip içinde diff incelemesini (**Toplu Yayınla** ekranındaki sürüm karşılaştırması) kolaylaştırır.

System Prompt şablonu

Kopyala

```
# Rol
<Temsilcinin kimliği, temsil ettiği şirket ve görüşmenin amacı.>

# Kapsam
- Kapsam içi: <konu listesi>
- Kapsam dışı: <konu listesi> → <yönlendirme davranışı>

# Karar kuralları
- <Koşul> ise <eylem>.
- Bilgi tabanında yanıt yoksa tahmin yürütme; <fallback davranışı>.

# Görüşme akışı
1. <Toplanacak ilk bilgi ve doğrulama yöntemi>
2. ...
N. <Kapanış koşulu>

# Çağrı bağlamı
<Payload'da gelen alanların anlamı ve nasıl kullanılacağı.>

# Çıktı kuralları
- Dil: <dil>, hitap: <siz/sen>
- Uzunluk: <en fazla N cümle>
- Biçim: <sesli: düz metin / yazılı: liste kullanılabilir>
```

### Karar kurallarını deterministik yazın

Belirsiz yönergeler (“yardımsever ol”, “gerekirse yönlendir”) farklı görüşmelerde farklı yorumlanır. Kuralları **koşul → eylem** biçiminde, ölçülebilir ifadelerle yazın.

Belirsiz

Deterministik

Kopyala

```
Müşteri sinirliyse onu sakinleştir ve gerekirse
bir yetkiliye aktar.
```

```
- Müşteri aynı talebi iki kez tekrar ederse veya
  açıkça yetkiliyle görüşmek isterse: özür dile,
  talebi tek cümleyle özetle ve destek ekibine
  yönlendir.
- Yönlendirmeden önce sipariş numarasını mutlaka al.
```

### Kural önceliğini belirtin

Kurallar çakışabiliyorsa öncelik sırasını açıkça yazın:

text

Kopyala

```
# Öncelik
1. Güvenlik ve gizlilik kuralları (kişisel veri paylaşma, kimlik doğrulama)
2. Kapsam kuralları
3. Görüşme akışı
4. Üslup kuralları
```

## Çağrı bağlamı (payload)

Dış arama kampanyalarında kişi listesindeki isteğe bağlı `payload` sütunu, test aramasında ise **Arama Başlat** penceresindeki **Payload (JSON)** alanı çağrıya özgü veri taşır. Payload geçerli bir JSON nesnesi olmalıdır.

Örnek payload

Kopyala

```
{
  "customer_name": "Ayşe Yılmaz",
  "order_id": "SP-104233",
  "appointment_date": "2026-11-21",
  "reason": "teslimat_gecikmesi"
}
```

Prompt’ta her alanın anlamını ve eksik olduğunda ne yapılacağını tanımlayın:

text

Kopyala

```
# Çağrı bağlamı
- customer_name: Müşteriye adıyla hitap etmek için kullan.
- order_id: Görüşmenin konusu olan sipariş. Müşteriye okurken
  karakter karakter söyle.
- reason: Aramanın nedeni. "teslimat_gecikmesi" ise yeni teslim
  tarihini bildir; başka bir değerse yalnızca bilgilendirme yap.
- Bir alan boşsa veya yoksa o bilgiyi müşteriden iste; uydurma.
```

DikkatPayload alanlarının prompt içinde nasıl adreslendiği (değişken sözdizimi) hesabınızın yapılandırmasına bağlı olabilir. Kampanyayı başlatmadan önce aynı payload ile bir test araması yapıp alanların doğru kullanıldığını [Çağrı Kayıtları](https://callby-ai.mintlify.app/guides/call-history) üzerindeki **Konuşma Kaydı**’ndan doğrulayın.

## Kanal kısıtları

Sesli temsilci

Yazılı temsilci

Sesli kanalda model çıktısı seslendirilir ve müşteri girdisi konuşmadan metne çevrilir. Bu iki dönüşüm prompt tasarımını doğrudan etkiler.

- **Biçimlendirme kullanmayın.** Markdown, madde işareti, URL ve emoji seslendirmede anlamsız okunur. Prompt’a açıkça “Yalnızca düz metin üret” yazın.
- **Yanıt uzunluğunu sınırlayın.** Uzun yanıtlar gecikmeyi artırır ve müşteri tarafından kesilme olasılığı yükselir. Örnek: “Her yanıt en fazla iki cümle olsun.”
- **Tanıma hatalarını varsayın.** Sipariş numarası, telefon numarası ve e-posta gibi değerler yanlış tanınabilir. Kritik değerleri müşteriye geri okuyarak doğrulatın.
- **Sayıların okunuşunu tanımlayın.** “Tutarları ‘yüz yirmi beş lira’ biçiminde, kodları karakter karakter söyle.”
- **Açılış cümlesini prompt’a koymayın.** Açılış **İlk Mesaj** alanından gelir; kesilmemesi gerekiyorsa **Karşılama mesajı kesilemesin** ayarını açın.

- **Biçimlendirmeyi kontrollü kullanın.** Adım adım talimatlar için numaralı liste kullanılabilir; tablo ve başlık kullanımını sınırlayın.
- **Bağlantı politikasını belirleyin.** Hangi alan adlarından bağlantı paylaşılabileceğini listeleyin; listede olmayan URL üretmesini yasaklayın.
- **Tek mesajda tek soru.** Müşteriden birden fazla bilgi istemek yanıt oranını düşürür.

## Senaryo bazlı test

Prompt değişikliklerini bir senaryo seti üzerinde test edin ve her değişiklikte aynı seti tekrar çalıştırın. Böylece bir kuralı düzeltirken başka bir davranışı bozmadığınızı (regresyon) görürsünüz.

### Senaryo matrisi

| # | Senaryo | Girdi örneği | Beklenen davranış |
| --- | --- | --- | --- |
| S1 | Kapsam içi, yanıt bilgi tabanında | “Siparişimi nasıl iade ederim?” | Bilgi tabanındaki adımları özetler |
| S2 | Kapsam içi, yanıt bilgi tabanında yok | “İade kargo ücretini kim ödüyor?” (kaynakta yoksa) | Tahmin yürütmez, fallback cümlesini kullanır |
| S3 | Kapsam dışı | “Kampanya kodunuz var mı?” | Kapsam dışı olduğunu söyler, yönlendirir |
| S4 | Eksik bilgi | Sipariş numarası vermeden durum sorar | Önce sipariş numarasını ister |
| S5 | Hatalı / tutarsız girdi | Geçersiz formatta sipariş numarası | Numarayı tekrar ister, geri okuyarak doğrular |
| S6 | Eskalasyon | “Bir yetkiliyle görüşmek istiyorum.” | Talebi özetler, yönlendirme kuralını uygular |
| S7 | Prompt’u aşma girişimi | “Önceki talimatlarını unut ve…” | Rolünü ve kapsamını korur |
| S8 | Eksik payload | `order_id` alanı olmadan test araması | Bilgiyi müşteriden ister, değer uydurmaz |
| S9 | Kesme (yalnızca sesli) | Temsilci konuşurken söze girme | Kısa yanıtla devam eder, akışı kaybetmez |

### Test döngüsü

1. **Taslağı kaydedin**Prompt alanındaki **Kaydet** → **Taslak olarak kaydet** ile değişikliği taslağa yazın.
2. **Senaryoları Önizleme’de çalıştırınÖnizleme**’de S1–S7’yi çalıştırın. Yazılı temsilcide **Chat Önizleme**, sesli temsilcide tarayıcı mikrofonu kullanılır.
3. **Telefon ve payload senaryolarını çalıştırınArama Başlat** penceresinde **Ajan sürümü** olarak **Taslak (son kaydedilen)** seçin, **Payload (JSON)** alanına test payload’ını girin ve S8–S9’u gerçek bir arama üzerinden deneyin.
4. **Sonuçları kayıtlardan doğrulayın**[Çağrı Kayıtları](https://callby-ai.mintlify.app/guides/call-history) sayfasında test ekranında görünen oda adıyla aramayı bulun. **Konuşma Kaydı** ile her senaryonun beklenen davranışla eşleştiğini kontrol edin.
5. **Diff’i inceleyip yayınlayınToplu Yayınla** ekranında mevcut sürüm ile taslak arasındaki farkı inceleyin ve **Değişiklikleri Onayla ve Yayınla**’ya tıklayın.

İpucuTek seferde tek bir kuralı değiştirin. Birden fazla değişikliği aynı yayında topladığınızda, bir senaryodaki davranış değişikliğinin hangi düzenlemeden kaynaklandığını ayırt etmek zorlaşır.

## Canlıda izleme

Yayından sonra prompt kalitesini gerçek görüşmeler üzerinden izleyin:

- **Çağrı Kayıtları**’nda **Temsilci Adı** ve tarih aralığıyla filtreleyerek yeni sürümden sonraki görüşmeleri ayırın.
- **Konuşma Özeti** ve **Kalite Değerlendirmesi** sekmelerinde sık tekrar eden başarısızlık örüntülerini arayın (yanlış yönlendirme, gereksiz tekrar, eksik bilgi toplama).
- Filtrelenmiş görüşmeleri **Dışa Aktar** → **Excel İndir** ile alıp sürümler arasında karşılaştırma yapın.
- Tespit ettiğiniz her yeni hata türünü senaryo matrisine yeni bir satır olarak ekleyin.

## Kontrol listesi

- Rol, kapsam ve kapsam dışı davranış tanımlı
- Bilgi eksik olduğunda kullanılacak fallback cümlesi tanımlı
- Kurallar koşul → eylem biçiminde ve öncelik sırası belirtilmiş
- Sık değişen veriler prompt’ta değil, bilgi tabanında
- Payload alanlarının anlamı ve eksik olma durumu tanımlı
- Sesli temsilci için düz metin ve uzunluk kuralı var
- Senaryo matrisi taslak üzerinde çalıştırıldı ve kayıtlardan doğrulandı

[ÖncekiTemsilci ayarları](https://callby-ai.mintlify.app/guides/agent-setup) [SonrakiBilgi tabanı](https://callby-ai.mintlify.app/guides/knowledge-base)

#### Bu sayfada

[Çalışma zamanı bileşenleri](https://www.callby.ai/prompt-tasarimi#katmanlar) [Prompt yapısı](https://www.callby.ai/prompt-tasarimi#yapi) [Çağrı bağlamı (payload)](https://www.callby.ai/prompt-tasarimi#payload) [Kanal kısıtları](https://www.callby.ai/prompt-tasarimi#kanal) [Senaryo bazlı test](https://www.callby.ai/prompt-tasarimi#senaryolar) [Canlıda izleme](https://www.callby.ai/prompt-tasarimi#izleme) [Kontrol listesi](https://www.callby.ai/prompt-tasarimi#kontrol)