Gateway va turn engine — AiHummer Hujjatlar

AiHummer’ning qalbi bitta gateway xizmatidir. U ayni vaqtda control-plane (admin API, sozlamalar, kanal ulanishi, marketplace) va turn engine (javob yaratadigan funksiya-chaqiruv halqasi)dir. Shu sababli oddiy oʻrnatma shunchaki oʻsha bitta xizmat hamda PostgreSQL’dir — siz ishga tushirishingiz shart boʻlgan alohida ishchi qatlam yoʻq.

Bitta xizmat, ikki rol

Gateway standart holatda :8780 portida tinglaydi, bu AIHUMMER_GATEWAY_ADDR bilan boshqariladi. Oʻrnatuvchi boshqa boʻsh portni tanlashi mumkin, lekin jarayon har doim bir xil bitta xizmat.

# gateway.env — the only required setting
AIHUMMER_DATABASE_URL=postgres://user:pass@localhost:5432/aihummer?sslmode=disable
# Admin UI after start at http://localhost:8781/

Yagona qattiq bogʻliqlik — PostgreSQL. Postgres haqiqatning yagona manbai: agentlar, sozlamalar, suhbatlar, xotira, outbox va auditning barchasi shu yerda yashaydi. Qolgan hamma narsa — sidecar’lar, vektor saqlovi, xabar shinasi, model provayderlari — ixtiyoriy va faqat siz sozlaganingizda ulanadi.

[!NOTE] Maʼlumotlar bazasisiz gateway faqat-salomatlik rejimida ishga tushadi: u GET /healthz’ga javob beradi, shunda orkestrator yoki yuk balanslagich jarayon tirik ekanini koʻra oladi, lekin u turn’larga xizmat qilmaydi. GET /readyz PostgreSQL’ni tekshiradi va maʼlumotlar bazasi yetib boʻlmaydigan boʻlganda 503 qaytaradi.

Ishga tushishda nima sodir boʻladi

Ishga tushishda gateway bir nechta qadamni qatʼiy tartibda bajaradi:

maʼlumotlar bazasi ulanish hovuzini ochadi,
Postgres maslahat qulfi ostida har qanday kutilayotgan migratsiyalarni qoʻllaydi,
konfiguratsiyani aniqlaydi (maʼlumotlar bazasi qiymati → atrof-muhit oʻzgaruvchisi → ichki standart), va
xizmatlarni — router, orkestrator, kanallar, asboblar, xotira, yetkazish — ishlaydigan gateway’ga ulaydi.

Muhim oqibat shundaki, koʻp xususiyatlar sozlama kaliti orqali ixtiyoriy. Sozlanmagan imkoniyat shunchaki faollashtirilmaydi, bu standart runtime’ni kichik va bashorat qilinadigan saqlaydi. Siz narsalarni veb admin UI’dan yoki AIHUMMER_* oʻzgaruvchisi bilan yoqasiz, va gateway ularni keyingi ishga tushishda (yoki qoʻllab-quvvatlaydigan sozlamalar uchun qaynoq) aniqlaydi.

Turn engine

Xabar gateway’ga yetganda turn engine boshqaruvni oladi. U funksiya-chaqiruv halqasini ishga tushiradi: modelga tizim prompti va suhbat beriladi, u asboblarni chaqirishi (yoki sub-agentlarni paydo qilishi) mumkin, har bir asbob natijasi qaytarib uzatiladi, va halqa model yakuniy javobni yaratmaguncha davom etadi. Oʻsha javob keyin yetkazish qatlamiga topshiriladi.

inbound message
   └─▶ turn engine
         ├─ assemble layered system prompt
         ├─ call model ──▶ tool calls / sub-agents ──▶ tool results ─┐
         │       ▲                                                    │
         │       └────────────────────────────────────────────────-─┘
         └─ final answer ─▶ outbox ─▶ originating channel

Halqa har bir kirish qayerdan kelishi haqida determinik boʻlgani uchun, javoblar suhbat tarixidan va asbob natijalaridan aniqlanadi — hech qachon koʻrsatmalarga ishonchsiz matnni kiritish orqali emas. Aynan shu xususiyat quyidagi prompt qatlamlashni xavfsiz, shuningdek tez qiladi.

Qatlamli, kesh-doʻst tizim prompti

Tizim prompti bitta blok emas. U qatlamlarda yigʻiladi, ataylab shunday tartiblanganki barqaror qismlar birinchi, oʻzgaruvchan qismlar oxirgi keladi. Bu muhim, chunki model provayderlari promptni uning prefiksi boʻyicha keshlaydi: promptning boshlanishi bayt-bayt bir xil boʻlsa, keshlangan prefiks qayta ishlatiladi va faqat dum qayta qayta ishlanadi.

Zona	Qatlamlar (tartibda)	Oʻzgaradi…
Barqaror prefiks (keshlanadigan)	asosiy identifikatsiya + asbob/xotira yoʻriqnomasi → tenant → persona → koʻnikmalar	kamdan-kam — agent/tenant boʻyicha
Oʻzgaruvchan dum (oxirgi qoʻshiladi)	onboarding holati → xotira gidratsiyasi → jonli sana	har bir turn’da

Barqaror prefiks agent kimligini belgilaydigan hamma narsani olib yuradi: ichki identifikatsiya va asboblar hamda xotira qanday ishlashi boʻyicha yoʻriqnoma, keyin tenant qatlami, agentning personasi, va render qilingan koʻnikmalar bloki. Bularning hech biri bir xil agentning ketma-ket ikki turn’i orasida oʻzgarmaydi, shuning uchun u qayta ishlatiladigan keshlangan prefiksni shakllantiradi.

Oʻzgaruvchan dum barqaror prefiksdan keyin qoʻshiladi, aynan u keshni hech qachon yaroqsiz qilmasligi uchun: onboarding holati, ushbu aniq suhbat uchun gidratlangan xotira va joriy sana barchasi turn’dan turn’ga oʻzgaradi, lekin ular oxirida turgani uchun ular faqat qoʻshganlarini xarajat qiladi.

[!TIP] Bu tartiblash — bugungi sana kabi jonli maʼlumot har safar butun identifikatsiyani qayta kodlash uchun toʻlamasdan har bir turn’da mavjud boʻla olishining sababi. Maxsus agent boʻyicha kontentni barqaror qatlamlarda (persona, koʻnikmalar) saqlang va oʻzgaruvchan dumni engine’ga egalik qildiring.

Keyin qayerga

Tenant’lar qanday izolyatsiyalanishini koʻring: Koʻp-tenantlik va idempotentlik.
Javoblar qanday qaytarilishini oʻrganing: Yetkazish, outbox va tiklash.
Ixtiyoriy imkoniyatlar Sidecar’lar sifatida ishlaydi.