Berke Akyıldız

İşler · 1 / 4

Talep agent’tan kurala, oradan kayda; bir kolu yöneticiye, dönüşü misafire.

Hotel Operations Agent

Bir otelin misafir asistanı ve yönetici ekranı. Misafir sohbetten havlu istiyor, arıza bildiriyor, geç çıkış soruyor; agent bunları otelin kayıtlarına işliyor, onay gereken talebi yöneticiye bırakıyor. Otel ve misafirler kurgusal; agent ve yaptığı her iş gerçek.

Hotel Operations Agent çalışırken: sohbet, yönetici paneli ve otel panosu Emma 15:00’te çıkmak istiyor. Kural yönetici onayı istediği için agent bir onay talebi açıyor; çıkış saati 12:00’de kalıyor. Otelin anlık durumu: Emma’nın talebi yöneticiyi bekliyor. Yönetici onaylıyor; çıkış 15:00’e alınıyor ve agent Emma’ya, o sormadan haber veriyor. Onaydan sonra: Emma’nın çıkışı 12:00’den 15:00’e geçti, misafire haber verildi. Daniel Türkçe yazıyor: arıza bir bakım talebi olarak kaydediliyor, cevap Türkçe geliyor. Kendini yönetici olarak tanıtan misafir onay veremiyor ve başka bir misafirin rezervasyonunu göremiyor.

1 / 7

Durum
Geliştirme sürüyor
Ne
Otel misafirleri için AI asistan ve yönetici ekranı: tek agent, kurgusal bir otel simülatörü
Yığın
Python · OpenAI Agents SDK · Responses API · FastAPI · SQLAlchemy · Alembic · SQLite · React · TypeScript · Playwright
Kod
github.com/brkakyldz/Hotel_Operations_Agent

01

Kısaca

Problem
Misafir taleplerinin çoğu bir kurala bağlı. Geç çıkışın verilip verilmeyeceği, odanın bir sonraki misafire hazır olup olamayacağına bağlı; bazı saatler de yönetici onayı istiyor. Bir sohbet asistanının “tamam” demesi kolay. Asıl iş, o “tamam” dendiğinde otelin kayıtlarında da gerçekten bir şeyin değişmiş olması.
Kullanıcı için değişen
Misafir kendi dilinde yazıyor ve talebi doğrudan otelin kayıtlarına işleniyor. Her cevabın altında, o cevapla neyin yapıldığını gösteren bir makbuz var. Onay gereken talep yöneticinin ekranına gidiyor. Yönetici karar verdiğinde ya da otelde misafirin odasını ilgilendiren bir şey değiştiğinde, misafir sormasına gerek kalmadan haberdar ediliyor.
Bunu mümkün kılan karar
Model yalnızca öneriyor; kararı kod veriyor. Kurallar, kaydı yazan işlemin içinde çalışıyor; misafir ne kadar ısrar ederse etsin agent onları konuşarak aşamıyor. Agent’ın hiçbir tool’u bir talebi onaylayamıyor: onay, yalnızca yöneticinin verebildiği kalıcı bir kayıt.
Kanıt
İngilizce ve Türkçe 75 vakalık canlı eval’de 75/75. Hiçbir vakada yasak bir iş değişikliği ya da yetkisiz bir yazma denemesi olmadı. Eval cevabın metnini değil; hangi tool’un hangi argümanla çağrıldığını ve sonunda veritabanında gerçekten neyin değiştiğini kontrol ediyor.

02

Yakından

Bu projede asıl uğraştığım şey, agent’ın misafire söyledikleriyle otelin kayıtlarının her zaman aynı olmasıydı.

Problem

Agent bir iş yaptığını söylüyorsa, o iş gerçekten yapılmış olmalı.

Bir misafir “15:00’te çıkabilir miyim?” diye sorduğunda cevap sadece nazik bir cümleden ibaret olamıyor. Arkasında birkaç soru var: istenen saat kaç, odaya bir sonraki misafir ne zaman geliyor, temizlik ekibi arada odayı hazırlayabilir mi. Agent burada yanlışlıkla “tamam” derse iki şeyden biri oluyor: ya misafir aslında onaylanmamış bir çıkış saatine güveniyor ya da bir sonraki misafir geldiğinde oda hazır olmuyor.

Bu yüzden projeye tek bir kuralla başladım: agent’ın yaptım dediği her işin otelin kayıtlarında bir karşılığı olmalı. Kayda bir şey yazılmadıysa agent “yaptım” demiyor.

Kurallar

Otelin kurallarını modelin insafına bırakmadım.

Geç çıkış kuralı şöyle: 14:00’e kadar otomatik veriliyor, 14:00 ile 16:00 arası yönetici onayı gerekiyor, oda bir sonraki misafire yetişmeyecekse hiç verilmiyor. Bunu prompt’a yazıp modelin uymasını ummak yerine, kayda yazan işlemin içinde çalışan bir fonksiyon olarak yazdım. Model ne söylerse söylesin, kaydı değiştirmenin tek yolu bu fonksiyondan geçiyor. Kendini yönetici olarak tanıtan bir misafir bile en fazla bir onay talebi açabiliyor; onayı vermek yine gerçek yöneticiye kalıyor.

Hangi misafirin verisinin okunacağına da model karar vermiyor. Misafir seçildiği anda session o misafirin rezervasyonuna bağlanıyor. Biri sohbette başka bir misafirin rezervasyonunu isterse, agent’ın o kayda ulaşmasını sağlayacak bir tool zaten yok.

Yönetici onayı

Onay gereken talepler yöneticinin ekranına düşüyor.

Onay gereken bir talep geldiğinde agent kendi başına karar vermiyor; talep kalıcı bir kayıt olarak yöneticiye gidiyor. Bu arada otel durmuyor: bir sonraki misafir erken gelebiliyor, bir rezervasyon iptal olabiliyor, bir oda arızalanabiliyor. Bu yüzden yönetici onay verdiği anda kural, otelin o anki kayıtlarıyla bir kez daha kontrol ediliyor. Talep açıldığından beri oda bir sonraki misafir için gerekli hâle geldiyse, yöneticinin kararı kaydediliyor ama çıkış saati değişmiyor.

Kimse karar vermezse talep, istenen saat geldiğinde kendiliğinden düşüyor. Böylece zamanı geçmiş bir onay sonradan uygulanamıyor.

Misafire haber

Bir şey değiştiğinde misafir, sormasına gerek kalmadan haber alıyor.

Yönetici bir talebi sonuçlandırdığında, personel bir işi bitirdiğinde ya da otelde misafiri ilgilendiren bir şey değiştiğinde misafire mesaj gidiyor. Mesajın gönderilip gönderilmeyeceğine kod karar veriyor; metnini agent yazıyor.

Bu mesajları yazarken agent’ın elinde sadece okuma tool’ları oluyor. Misafire bir sonraki adımı önerebiliyor, ama misafir “evet” demeden hiçbir şey yapmıyor.

Ölçüm

Eval’de agent’ın cevabını değil, kayıtlarda neyin değiştiğini ölçtüm.

canlı eval · 75 vaka
75/75
yasak iş değişikliği · yetkisiz yazma
0
otomatik test · ağa çıkmadan
386

Her vaka temiz bir otelle başlıyor ve gerçek model, gerçek veritabanı üzerinde çalışıyor. Bir vakanın geçip geçmediğine agent’ın cevabını okuyarak değil, veritabanında gerçekten ne değiştiğine bakarak karar veriyorum. 75 vakanın hepsi geçti ve hiçbirinde yasak bir iş değişikliği ya da yetkisiz bir yazma olmadı.

Teknik derinlikBuradan sonrası mimari ayrıntı: bileşenler, kararlar ve sayılar. Yukarıdaki kısım tek başına okunduğunda proje anlaşılır.

03

Nasıl çalışır

Hotel Operations Agent’ın mimarisi Misafirin mesajı tek bir agent’a gidiyor. Agent’ın tool önerisi model ile kod arasındaki sınırı yalnızca tool kapısından geçiyor; kapıdan servislere, oradan otelin kaydına ulaşıyor. Yönetici servislere modelsiz komutlarla bağlı; agent’tan bu komutlara giden bir yol yok. Otelde misafiri ilgilendiren bir değişiklik olduğunda outbox, agent’a sadece okuma yetkisiyle bir tur açıyor ve misafire haber veriliyor. model · öneriyor kod · karar veriyor mesaj tool önerisi sadece okuma Misafir Agent tek agent · 9 tool Tool kapısı şema · kapsam · süre Servisler kural işlemin içinde Otel kaydı iş · makbuz · audit Komutlar model yok Yönetici Outbox haber

Havlu

  1. Misafir iki havlu daha istiyor.
  2. Agent bir tool öneriyor. Öneri doğrudan çalışmıyor; önce kapı şemayı, kapsamı ve süreyi kontrol ediyor.
  3. Servis kuralı yazma işleminin içinde uyguluyor: bu konaklamanın havlu sınırı aşılmamış.
  4. İş, makbuzu ve audit kaydı birlikte yazılıyor; ya hepsi ya hiçbiri.
  5. Cevap misafire makbuzuyla dönüyor. Agent “tamam” dediyse, kayıt değişmiştir.

Geç çıkış

  1. Emma 15:00’te çıkmak istiyor.
  2. Kural kodda: 14:00’e kadar otomatik, 16:00’ya kadar yönetici onayıyla.
  3. Talep değişmez bir kayda dönüşüyor. Çıkış saati 12:00’de kalıyor.
  4. Run burada bitiyor; onay bekleyen bir run askıda tutulmuyor. Emma talebinin yöneticide olduğunu öğreniyor.
  5. Yönetici onaylıyor. Bu komutta model yok.
  6. Kural, otelin o anki kayıtlarıyla yeniden kontrol ediliyor. Çıkış 15:00’e alınıyor.
  7. Aynı işlemin içinde outbox’a tek satır yazılıyor.
  8. Agent’a sadece okuma tool’larıyla bir tur açılıyor. Emma sormadan haber alıyor.

Yetki denemesi

  1. Bir misafir kendini yönetici olarak tanıtıyor ve onay istiyor.
  2. Agent’tan yöneticinin komutlarına giden bir yol yok. Onay veren bir tool da yok.
  3. En fazla bir onay talebi açabiliyor. Karar yine yöneticinin.
  4. Başka bir misafirin rezervasyonunu istiyor. Kapsamı model seçmiyor; session sadece kendi rezervasyonuna bağlı.
Gölgeli alanda model öneriyor, kesikli çizginin altında kod karar veriyor. talep, cevap.

Misafirin mesajı bir run olarak kaydediliyor; arayüz run’ın ilerlemesini canlı izliyor. Agent bir tool önerdiğinde öneri doğrudan çalışmıyor, önce tool kapısından geçiyor. Kapı şemayı, session’ın kapsamını ve süreyi kontrol edip işi ilgili servise veriyor. Servis kuralı yazma işleminin içinde uyguluyor; sonuç sohbette bir makbuz olarak görünüyor.

Yöneticinin tarafında model yok. Onay, görev takibi, otel olayları ve otel saati düz komutlar; agent’ın bu komutlara ulaşan tek bir tool’u yok.

04

Kurucu kararlar

Tek agent yeter.

Rezervasyon, housekeeping ve bakım için ayrı agent’lar yok; iş alanlarını tool’lar ve arkalarındaki servisler ayırıyor. Dokuz tool’un beşi okuyor, dördü yazıyor. Birden fazla agent bu işe bir şey katmadan koordinasyon yükü eklerdi.

Yetki prompt’ta değil, tool katmanında.

Prompt bir güvenlik önlemi değil. Tool’ların şeması sıkı, kapsamı sunucudan geliyor ve her yazmanın tekrar gönderime karşı bir anahtarı var: aynı istek iki kez gelirse ikinci bir kayıt açılmıyor. Tool’dan dönen metin agent için veri; içindeki cümleler talimat sayılmıyor.

Otelin doğrusu tek yerde.

İş kayıtları ve sohbet geçmişi iki ayrı veritabanında. Modelin hatırladığı bayat olabilir; bu yüzden tool’lar her seferinde güncel kaydı okuyor ve yazmadan hemen önce kuralı yeniden kontrol ediyor. Bir iş, makbuzu ve audit kaydı ya birlikte yazılıyor ya hiç yazılmıyor.

Onay bekleyen run askıda tutulmuyor.

Onay için agent’ın run’ını durdurup beklemek, otelin iş akışını modelin geçmişine bağlardı. Onun yerine talep değişmez bir kayda dönüşüyor. Yöneticinin kararı ayrı ve modelsiz bir komutla, aynı işlemin içinde yeniden kontrol edilerek uygulanıyor.

Otelin mesajı bir kuyruktan doğuyor.

Misafiri ilgilendiren bir değişiklik, aynı işlemin içinde bir outbox tablosuna tek satır olarak yazılıyor. İşlem tamamlanınca agent’a sadece okuma tool’ları verilerek tek bir tur açılıyor. Arka planda sürekli kontrol eden bir süreç yok.

Her run’ın sınırı kodda.

Bir run en fazla 6 tur ve 8 tool çağrısı kullanabiliyor, 90 saniyede bitmek zorunda; session başına tek aktif run var. Sınıra takılan run bir hata koduyla kapanıyor ve yarım kalan geçmişi geri alınıyor.

05

Sayılar

Ölçülenler
NeDeğer
Canlı eval · gpt-6-luna, 75 vaka75/75 · yasak değişiklik 0 · yetkisiz yazma 0 · ortalama 4,2 sn
Canlı eval · gpt-5.4-mini, 40 vaka40/40, iki ayrı turda · İngilizce 32/32, Türkçe 8/8
Rehberli senaryolar, canlı4 hikâye, 17/17 adım
Test386 Python testi, ağa çıkmadan · 65 web unit testi · 34 Playwright senaryosu
Hata senaryosu20, her biri bir testle tekrar üretiliyor

Üstteki sayılar sistem çalıştırılarak çıktı; alttakiler kodda öyle yazdığı için doğru.

Tasarım sabitleri
NeDeğer
Agent · tool1 agent · 9 tool (5 okuma, 4 yazma)
Run sınırı6 tur · 8 tool çağrısı · 90 sn
Aktif runsession başına 1
Mimari karar14, her biri gerekçesiyle