Агейтуэй & ахаҿ адвигатель — 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] Адырраҭарадза агейтуэй health-only режим аҿы иалагоит: уи иҭакуеит GET /healthz уи аоркестратор ма аиҟәырԥшы апроцесс ибзоу ишаауеит, аха ахаҿқәа имаҵура изуам. GET /readyz PostgreSQL иаԥшуеит насгьы 503 иҭакуеит адырраҭарадза изыхалартә ишамоу аамҭазы.

Аусура анадоу иҟало

Анадоу аамҭазы агейтуэй ишьҭыбжьалатәу аарыхәԥкаара иҟанаҵоит:

адырраҭарадза адхалара аԥҟа иаунакыруеит,
иазыԥшу амиграциақәа ируеит Postgres advisory lock ала,
аконфигурациа иршьоит (адырраҭарадза ахәҭа → асреда аизменӡа → иарбоу адефолт), ацны
амаҵурақәа иавирит — ароутер, аоркестратор, аканалқәа, аусхкқәа, агәынкьара, ашьҭаҵара — иаауазаалак агейтуэй ахь.

Аихтыҵ зыршаахо иабоу акоуп: ифункциақәа реиҳарак опт-ин-уп аиқәыршәара аҭыӡҭыԥ ала. Иаиқәырмҵаз алшара иаразнак иаамхуам, уи адефолт рантайм аӡбахьа насгьы иазҵаамгахо иаанха. Уара иаунакыруеит веб-админ 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 & аиҭашьақәыргылара.
Изыхәҭоу алшарақәа Асайдкарқәа ҳасабла иауеит.