Passerelle et moteur de rotation

Le cœur d’AiHummer est un service de passerelle unique. C’est en même temps le plan de contrôle (API administrateur, paramètres, câblage de canal, place de marché) et le tourner le moteur (la boucle d’appel de fonction qui produit une réponse). Un déploiement typique est donc juste ce service plus PostgreSQL — il n’y a pas de couche de travailleur séparée que vous êtes obligé d’exécuter.

Un service, deux rôles

La passerelle écoute sur le publique port :8780 par défaut, contrôlé par AIHUMMER_GATEWAY_ADDR — ce port gère tout le trafic externe (API, jumelage, WS/SSE, webhooks entrants, le proxy de l’application/pocket et les sondes de santé). L’interface Web d’administration fonctionne sur un séparé, privé écouteur (par défaut :8781, AIHUMMER_WEBUI_ADDR), servi à la racine du chemin / et idéalement lié à une interface interne uniquement. Dans tous les cas, le processus est toujours le même service unique.

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

Le la seule dépendance obligatoire est PostgreSQL. Postgres est la source unique de vérité pour les agents, les paramètres, les conversations, la mémoire, l’état de livraison et l’audit. Tout le reste — services optionnels, un magasin vectoriel et des fournisseurs de modèles — n’est connecté que lorsque vous le configurez.

[!NOTE] Sans base de données, le portail démarre en mode santé uniquement: il répond GET /healthz ainsi un orchestrateur ou un répartiteur de charge peut voir que le processus est vivant, mais il ne rendra pas les services. GET /readyz vérifie PostgreSQL et retours 503 pendant que la base de données est inaccessible.

Ce qui se passe au démarrage

Au démarrage, la passerelle effectue quelques étapes dans un ordre strict :

ouvre le pool de connexions de la base de données,
applique toutes les migrations en attente sous un verrou consultatif Postgres,
résout la configuration (valeur de la base de données → variable d’environnement → intégré) par défaut), et
connecte les services — routeur, orchestrateur, canaux, outils, mémoire, livraison — dans une passerelle en fonctionnement.

La conséquence importante est que la plupart des fonctionnalités sont activées par option via une clé de paramètres. Une capacité qui n’est pas configurée n’est tout simplement pas activée, ce qui maintient le runtime par défaut petit et prévisible. Vous activez les fonctionnalités depuis l’interface d’administration web ou avec un AIHUMMER_* variable, et la passerelle les résout au prochain démarrage (ou à chaud, pour les boutons qui le supportent).

Le moteur de rotation

Lorsque un message atteint la passerelle, le moteur de rotation prend le relais. Il exécute un boucle d’appel de fonction: le modèle reçoit l’invite du système et la conversation, il peut appeler des outils (ou générer des sous-agents), chaque résultat d’outil est renvoyé, et la boucle continue jusqu’à ce que le modèle produise une réponse finale. Cette réponse est ensuite transmise à la couche de livraison.

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

Parce que la boucle est déterministe quant à l’origine de chaque entrée, les réponses sont résolues à partir de l’historique de la conversation et des résultats des outils — jamais en injectant du texte non fiable dans les instructions. Cette propriété est ce qui rend la superposition des invites ci-dessous à la fois sûre et rapide.

L’invite système en couches et optimisée pour le cache

L’invite système n’est pas un seul bloc. Elle est assemblée en couches, délibérément ordonnées de sorte que le les parties stables viennent en premier et les parties volatiles viennent en dernier. Cela importe parce que les fournisseurs de modèles mettent en cache une invite par son préfixe : tant que le début de l’invite est identique octet par octet, le préfixe mis en cache est réutilisé et seul le reste est retraité.

Zone	Couches (dans l’ordre)	Changements…
Préfixe stable (mis en cache)	identité de base + guide d’outil/mémoire → locataire → persona → compétences	rarement — par agent/locataire
Queue volatile (joint en dernier)	état d’intégration → hydratation de la mémoire → la date de mise en ligne	à chaque tournant

Le préfixe stable contient tout ce qui définit qui est l’agent : l’identité intégrée et le guide sur le fonctionnement des outils et de la mémoire, puis la couche du locataire, la persona de l’agent et le bloc de compétences rendu. Rien de tout cela ne change entre deux tours consécutifs du même agent, donc il forme un préfixe mis en cache réutilisable.

La queue volatile est ajoutée après le préfixe stable précisément afin qu’il n’invalide jamais le cache : l’état d’intégration, la mémoire hydratée pour cette conversation spécifique, et la date actuelle changent tous à chaque tour, mais comme ils se trouvent à la fin, ils ne coûtent que ce qu’ils ajoutent.

[!TIP] Cet ordre est la raison pour laquelle des données en direct telles que la date d’aujourd’hui peuvent être présentes dans chaque tour sans payer pour réencoder toute l’identité à chaque fois. Garder contenu personnalisé par agent dans les couches stables (personnalité, compétences) et laisser le le moteur possède la queue volatile.

Où aller ensuite

Voyez comment les locataires sont isolés dans Multilocativité et idempotence.
Apprenez comment les réponses sont renvoyées dans Livraison et récupération fiables.
Les capacités optionnelles s’exécutent en tant que Side-cars.