Gateway și motorul de tururi — AiHummer Documentație

Inima AiHummer este un singur serviciu de gateway. Acesta este în același timp planul de control (API admin, setări, cablarea canalelor, marketplace) și motorul de tururi (bucla de apelare a funcțiilor care produce un răspuns). O implementare tipică este, prin urmare, doar acel serviciu plus PostgreSQL — nu există un nivel separat de workeri pe care să fiți obligat să-l rulați.

Un serviciu, două roluri

Gateway-ul ascultă pe :8780 în mod implicit, controlat de AIHUMMER_GATEWAY_ADDR. Programul de instalare poate alege un alt port liber, dar procesul este întotdeauna același serviciu unic.

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

Singura dependență obligatorie este PostgreSQL. Postgres este sursa unică de adevăr: agenții, setările, conversațiile, memoria, outbox-ul și auditul trăiesc toate acolo. Orice altceva — sidecars, un magazin de vectori, o magistrală de mesaje, furnizorii de modele — este opțional și cablat doar atunci când îl configurați.

[!NOTE] Fără o bază de date, gateway-ul pornește în mod doar-sănătate: răspunde la GET /healthz astfel încât un orchestrator sau un load balancer să poată vedea că procesul este viu, dar nu va deservi tururi. GET /readyz verifică PostgreSQL și returnează 503 în timp ce baza de date este inaccesibilă.

Ce se întâmplă la pornire

La pornire, gateway-ul efectuează câțiva pași într-o ordine strictă:

deschide pool-ul de conexiuni la baza de date,
aplică orice migrări în așteptare sub un advisory lock Postgres,
rezolvă configurația (valoarea din baza de date → variabila de mediu → valoarea implicită încorporată) și
cablează serviciile — router, orchestrator, canale, instrumente, memorie, livrare — într-un gateway funcțional.

Consecința importantă este că majoritatea funcționalităților sunt opt-in printr-o cheie de setări. O capabilitate care nu este configurată pur și simplu nu este activată, ceea ce menține runtime-ul implicit mic și previzibil. Activați lucrurile din interfața web de administrare sau cu o variabilă AIHUMMER_*, iar gateway-ul le rezolvă la următoarea pornire (sau la cald, pentru reglajele care acceptă acest lucru).

Motorul de tururi

Când un mesaj ajunge la gateway, motorul de tururi preia controlul. Acesta rulează o buclă de apelare a funcțiilor: modelului i se dă promptul de sistem și conversația, poate apela instrumente (sau crea sub-agenți), fiecare rezultat de instrument este reintrodus, iar bucla continuă până când modelul produce un răspuns final. Acel răspuns este apoi predat stratului de livrare.

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

Deoarece bucla este deterministă în privința locului din care provine fiecare intrare, răspunsurile sunt rezolvate din istoricul conversației și din rezultatele instrumentelor — niciodată prin injectarea de text de încredere îndoielnică în instrucțiuni. Această proprietate este ceea ce face stratificarea promptului de mai jos atât sigură, cât și rapidă.

Promptul de sistem stratificat, prietenos cu cache-ul

Promptul de sistem nu este un singur bloc. Este asamblat în straturi, ordonate deliberat astfel încât părțile stabile vin primele, iar părțile volatile vin ultimele. Acest lucru contează deoarece furnizorii de modele păstrează în cache un prompt după prefixul său: atâta timp cât începutul promptului este identic octet cu octet, prefixul din cache este reutilizat și doar coada este reprocesată.

Zonă	Straturi (în ordine)	Se schimbă…
Prefix stabil (cacheabil)	identitate de bază + ghid de instrumente/memorie → tenant → personă → skills	rar — per agent/tenant
Coadă volatilă (adăugată ultima)	starea de onboarding → hidratarea memoriei → data în timp real	la fiecare tur

Prefixul stabil poartă tot ceea ce definește cine este agentul: identitatea încorporată și ghidul despre cum funcționează instrumentele și memoria, apoi stratul tenant, persona agentului și blocul de skills redat. Niciunul dintre acestea nu se schimbă între două tururi consecutive ale aceluiași agent, deci formează un prefix din cache reutilizabil.

Coada volatilă este adăugată după prefixul stabil tocmai pentru a nu invalida niciodată cache-ul: starea de onboarding, memoria hidratată pentru această conversație specifică și data curentă se schimbă toate de la tur la tur, dar pentru că stau la final, costă doar ceea ce adaugă.

[!TIP] Această ordonare este motivul pentru care datele în timp real, cum ar fi data de astăzi, pot fi prezente în fiecare tur fără a plăti pentru re-codificarea întregii identități de fiecare dată. Păstrați conținutul personalizat per agent în straturile stabile (personă, skills) și lăsați motorul să dețină coada volatilă.

Unde mergem mai departe

Vedeți cum sunt izolați tenanții în Multitenanță și idempotență.
Aflați cum sunt returnate răspunsurile în Livrare, outbox și recuperare.
Capabilitățile opționale rulează ca Sidecars.