Gateway və dövr mühərriki — AiHummer Sənədlər

AiHummer-in ürəyi tək gateway xidmətidir. O eyni zamanda həm control-plane (admin API, parametrlər, kanal qoşulması, marketplace), həm də dövr mühərrikidir (cavab istehsal edən funksiya-çağırma dövrü). Tipik bir tətbiq buna görə sadəcə həmin bir xidmət plus PostgreSQL-dir — işlətməyə məcbur olduğunuz ayrıca işçi qatı yoxdur.

Bir xidmət, iki rol

Gateway standart olaraq :8780-də dinləyir, bu da AIHUMMER_GATEWAY_ADDR ilə idarə olunur. Quraşdırıcı fərqli boş port seçə bilər, lakin proses həmişə eyni tək xidmətdir.

# 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/

Yeganə sərt asılılıq PostgreSQL-dir. Postgres həqiqətin tək mənbəyidir: agentlər, parametrlər, söhbətlər, yaddaş, outbox və audit hamısı orada yaşayır. Qalan hər şey — sidecar-lar, vektor anbarı, mesaj şini, model provayderləri — opsionaldır və yalnız konfiqurasiya etdikdə qoşulur.

[!NOTE] Verilənlər bazası olmadan gateway yalnız-sağlamlıq rejimində başlayır: o, orkestrator və ya yük balanslaşdırıcının prosesin canlı olduğunu görə bilməsi üçün GET /healthz-ə cavab verir, lakin dövrlərə xidmət etməyəcək. GET /readyz PostgreSQL-i yoxlayır və verilənlər bazasına çatmaq mümkün olmadıqda 503 qaytarır.

Başlanğıcda nə baş verir

Başlanğıcda gateway bir neçə addımı ciddi ardıcıllıqla yerinə yetirir:

verilənlər bazası bağlantı hovuzunu açır,
Postgres advisory lock altında gözləyən hər hansı miqrasiyaları tətbiq edir,
konfiqurasiyanı həll edir (verilənlər bazası dəyəri → mühit dəyişəni → daxili standart), və
xidmətləri — router, orkestrator, kanallar, alətlər, yaddaş, çatdırılma — işləyən gateway-ə qoşur.

Vacib nəticə budur ki, əksər funksiyalar parametr açarı vasitəsilə opt-in olur. Konfiqurasiya edilməmiş bir imkan sadəcə aktivləşdirilmir, bu da standart işləmə mühitini kiçik və proqnozlaşdırıla bilən saxlayır. Şeyləri veb admin UI-dən və ya AIHUMMER_* dəyişəni ilə açırsınız və gateway onları növbəti başlanğıcda həll edir (və ya bunu dəstəkləyən knoblar üçün isti).

Dövr mühərriki

Mesaj gateway-ə çatdıqda, dövr mühərriki idarəni ələ alır. O, funksiya-çağırma dövrü işlədir: modelə sistem promptu və söhbət verilir, o, alətləri çağıra bilər (və ya alt-agentlər yarada bilər), hər alət nəticəsi geri verilir və dövr model yekun cavab istehsal edənə qədər davam edir. Həmin cavab sonra çatdırılma təbəqəsinə ötürülür.

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

Dövr hər girişin haradan gəldiyi barədə determinik olduğu üçün, cavablar söhbət tarixçəsindən və alət nəticələrindən həll olunur — heç vaxt etibarsız mətni təlimatlara yeritməklə deyil. Aşağıdakı prompt təbəqələşməsini həm təhlükəsiz, həm də sürətli edən elə bu xüsusiyyətdir.

Təbəqəli, keş-dostu sistem promptu

Sistem promptu tək bir blok deyil. O, təbəqələrlə yığılır, qəsdən elə sıralanır ki, sabit hissələr əvvəl, dəyişkən hissələr sonda gəlsin. Bu vacibdir, çünki model provayderləri promptu prefiksinə görə keşləyir: promptun əvvəli bayt-bayt eyni qaldığı müddətcə, keşlənmiş prefiks təkrar istifadə olunur və yalnız quyruq yenidən emal edilir.

Zona	Təbəqələr (ardıcıllıqla)	Dəyişiklik…
Sabit prefiks (keşlənə bilən)	baza kimliyi + alət/yaddaş bələdçisi → kirayəçi → persona → bacarıqlar	nadirən — agent/kirayəçi üzrə
Dəyişkən quyruq (sona əlavə olunur)	onboarding vəziyyəti → yaddaş hidratasiyası → canlı tarix	hər dövr

Sabit prefiks agentin kim olduğunu təyin edən hər şeyi daşıyır: daxili kimlik və alətlərlə yaddaşın necə işlədiyinə dair bələdçi, sonra kirayəçi təbəqəsi, agentin personası və render edilmiş bacarıqlar bloku. Bunların heç biri eyni agentin iki ardıcıl dövrü arasında dəyişmir, ona görə də o, təkrar istifadə oluna bilən keşlənmiş prefiks təşkil edir.

Dəyişkən quyruq sabit prefiksdən sonra məhz ona görə əlavə olunur ki, o, heç vaxt keşi etibarsız etməsin: onboarding vəziyyəti, bu konkret söhbət üçün hidratasiya edilmiş yaddaş və cari tarix hamısı dövrdən-dövrə dəyişir, lakin sonda durduqları üçün yalnız əlavə etdikləri qədər baha olur.

[!TIP] Bu sıralama, bugünkü tarix kimi canlı məlumatın hər dövrdə hər dəfə bütün kimliyi yenidən kodlaşdırmaq üçün ödəniş etmədən mövcud ola bilməsinin səbəbidir. Xüsusi agent-üzrə məzmunu sabit təbəqələrdə (persona, bacarıqlar) saxlayın və dəyişkən quyruğa sahib olmağı mühərrikə buraxın.

Növbəti hara

Kirayəçilərin necə təcrid olunduğunu görün: Çoxkirayəçilik və idempotentlik.
Cavabların necə qaytarıldığını öyrənin: Çatdırılma, outbox və bərpa.
Opsional imkanlar Sidecar-lar kimi işləyir.