Шлюз і рухавік ходу — AiHummer Дакументацыя

Сэрца AiHummer — гэта адзіны сэрвіс шлюза. Ён адначасова з’яўляецца кіравальнай плоскасцю (адмін-API, налады, падключэнне каналаў, маркетплейс) і рухавіком ходу (цыкл выкліку функцый, які стварае адказ). Таму тыповае разгортванне — гэта проста гэты адзіны сэрвіс плюс PostgreSQL — няма асобнага ўзроўню працаўнікоў, які вы абавязаны запускаць.

Адзін сэрвіс, дзве ролі

Шлюз па змаўчанні слухае на :8780, што кантралюецца праз AIHUMMER_GATEWAY_ADDR. Усталёўшчык можа выбраць іншы вольны порт, але працэс заўсёды той самы адзіны сэрвіс.

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

Адзіная жорсткая залежнасць — PostgreSQL. Postgres — гэта адзіная крыніца ісціны: агенты, налады, размовы, памяць, outbox і аўдыт усе жывуць там. Усё астатняе — сайдкары, вектарнае сховішча, шына паведамленняў, правайдары мадэляў — неабавязковае і падключаецца толькі тады, калі вы яго наладжваеце.

[!NOTE] Без базы даных шлюз запускаецца ў рэжыме толькі стану здароўя: ён адказвае на GET /healthz, каб аркестратар ці балансіроўшчык нагрузкі бачыў, што працэс жывы, але ён не будзе абслугоўваць хады. GET /readyz правярае PostgreSQL і вяртае 503, пакуль база даных недасягальная.

Што адбываецца пры запуску

Пры запуску шлюз выконвае некалькі крокаў у строгім парадку:

адкрывае пул злучэнняў з базай даных,
ужывае любыя адкладзеныя міграцыі пад кансультатыўнай блакіроўкай Postgres,
вырашае канфігурацыю (значэнне з базы даных → пераменная асяроддзя → убудаванае змаўчанне), і
падключае сэрвісы — маршрутызатар, аркестратар, каналы, інструменты, памяць, дастаўку — у працуючы шлюз.

Важны вынік у тым, што большасць функцый уключаюцца праз ключ налад. Магчымасць, якая не наладжана, проста не актывуецца, што ўтрымлівае рантайм па змаўчанні малым і прадказальным. Вы ўключаеце рэчы з вэб-адмін-UI ці з дапамогай пераменнай AIHUMMER_*, і шлюз вырашае іх пры наступным запуску (або гарача — для тых ручак, якія гэта падтрымліваюць).

Рухавік ходу

Калі паведамленне дасягае шлюза, рухавік ходу бярэ на сябе кіраванне. Ён запускае цыкл выкліку функцый: мадэлі даюцца сістэмны промпт і размова, яна можа выклікаць інструменты (ці спараджаць суб-агентаў), кожны вынік інструмента вяртаецца назад, і цыкл працягваецца, пакуль мадэль не створыць канчатковы адказ. Гэты адказ затым перадаецца ўзроўню дастаўкі.

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

Паколькі цыкл дэтэрмінаваны адносна таго, адкуль паходзіць кожны ўваход, адказы вырашаюцца з гісторыі размовы і з вынікаў інструментаў — ніколі шляхам укаранення недавернага тэксту ў інструкцыі. Менавіта гэтая ўласцівасць робіць слаёнасць промпта ніжэй бяспечнай, а таксама хуткай.

Шматслаёвы, зручны для кэшавання сістэмны промпт

Сістэмны промпт — гэта не адзін блок. Ён збіраецца слаямі, наўмысна ўпарадкаваны так, што устойлівыя часткі ідуць першымі, а зменлівыя — апошнімі. Гэта мае значэнне, бо правайдары мадэляў кэшуюць промпт па яго прэфіксе: пакуль пачатак промпта байт-у-байт ідэнтычны, кэшаваны прэфікс перавыкарыстоўваецца, і толькі хвост перапрацоўваецца зноў.

Зона	Слаі (па парадку)	Змяняецца…
Устойлівы прэфікс (кэшаваны)	базавая ідэнтычнасць + гід па інструментах/памяці → арэндар → персона → навыкі	рэдка — на агента/арэндара
Зменлівы хвост (дадаецца апошнім)	стан анбордынгу → гідрацыя памяці → жывая дата	кожны ход

Устойлівы прэфікс нясе ўсё, што вызначае, хто такі агент: убудаваную ідэнтычнасць і гід па тым, як працуюць інструменты і памяць, затым слой арэндара, персону агента і адрэндараны блок навыкаў. Нічога з гэтага не змяняецца паміж двума паслядоўнымі ходамі аднаго агента, таму ён утварае перавыкарыстоўвальны кэшаваны прэфікс.

Зменлівы хвост дадаецца пасля устойлівага прэфікса менавіта так, што ён ніколі не інвалідуе кэш: стан анбордынгу, памяць, гідраваная для гэтай канкрэтнай размовы, і бягучая дата ўсе змяняюцца ад ходу да ходу, але паколькі яны сядзяць у канцы, яны каштуюць толькі тое, што дадаюць.

[!TIP] Гэтае ўпарадкаванне — прычына, чаму жывыя даныя, такія як сённяшняя дата, могуць прысутнічаць у кожным ходзе, не плацячы за паўторнае кадаванне ўсёй ідэнтычнасці кожны раз. Трымайце ўласны пер-агентны кантэнт ва ўстойлівых слаях (персона, навыкі) і дазвольце рухавіку валодаць зменлівым хвастом.

Куды далей

Гл., як арэндары ізаляваны ў Шматарэндарнасць і ідэмпатэнтнасць.
Даведайцеся, як адказы вяртаюцца ў Дастаўка, outbox і аднаўленне.
Неабавязковыя магчымасці працуюць як Сайдкары.