Gateway- und Drehmotor — AiHummer Dokumente

Das Herz von AiHummer ist ein einzelner Gateway-Dienst. Es ist gleichzeitig das Kontrollebene (Admin-API, Einstellungen, Kanalverkabelung, Marktplatz) und die Motor starten (die Funktionsaufruf-Schleife, die eine Antwort erzeugt). Eine typische Bereitstellung ist daher genau dieser eine Dienst plus PostgreSQL – es gibt keine separate Worker-Ebene, die Sie betreiben müssen.

Ein Dienst, zwei Rollen

Das Gateway hört auf dem öffentlichen Port :8780 standardmäßig, gesteuert von AIHUMMER_GATEWAY_ADDR — dieser Port trägt allen externen Verkehr (API, Kopplung, WS/SSE, eingehende Webhooks, die App/Pocket-Proxy und Gesundheitsprüfungen). Die Admin-Web-UI läuft auf einem separat, privat Listener (Standard) :8781, AIHUMMER_WEBUI_ADDR), bereitgestellt am Stammverzeichnis / und idealerweise an ein nur intern nutzbares Interface gebunden. In jedem Fall ist der Prozess immer derselbe einzelne Dienst.

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

Der die einzige starke Abhängigkeit ist PostgreSQL. Postgres ist die einzige Wahrheitquelle für Agenten, Einstellungen, Konversationen, Speicher, Lieferstatus und Prüfprotokolle. Alles andere — optionale Dienste, ein Vektorspeicher und Modellanbieter — wird nur eingebunden, wenn Sie es konfigurieren.

[!NOTE] Ohne eine Datenbank startet das Gateway in Nur-Gesundheitsmodus: es antwortet GET /healthz damit ein Orchestrator oder Lastverteiler sehen kann, dass der Prozess ist lebendig, aber es wird keine Dienste leisten. GET /readyz überprüft PostgreSQL und kehrt zurück 503 während die Datenbank nicht erreichbar ist.

Was passiert beim Start

Beim Start führt das Gateway einige Schritte in einer strikten Reihenfolge aus:

öffnet den Datenbank-Verbindungs-Pool,
wendet alle ausstehenden Migrationen unter einem Postgres-Beratungsschloss an,
löst die Konfiguration auf (Datenbankwert → Umgebungsvariable → eingebaut) Standard), und
verdrahtet die Dienste — Router, Orchestrator, Kanäle, Werkzeuge, Speicher, Lieferung — in ein laufendes Gateway.

Die wichtige Konsequenz ist, dass Die meisten Funktionen sind über einen Einstellungsschlüssel optional zugänglich. Eine Fähigkeit, die nicht konfiguriert ist, wird einfach nicht aktiviert, was die Standardlaufzeit klein und vorhersehbar hält. Sie schalten Dinge über die Web-Admin-Oberfläche oder mit einem AIHUMMER_* variabel, und das Gateway löst sie beim nächsten Start (oder live, für die Regler, die dies unterstützen).

Der Wendemechanismus

Wenn eine Nachricht das Gateway erreicht, übernimmt die Turn-Engine. Sie führt eine Funktionsaufruf-Schleife: Dem Modell werden die Systemaufforderung und das Gespräch gegeben, es kann Werkzeuge aufrufen (oder Unteragenten starten), jedes Werkzeugergebnis wird zurückgeführt, und die Schleife setzt sich fort, bis das Modell eine endgültige Antwort liefert. Diese Antwort wird dann an die Auslieferungsschicht übergeben.

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

Da die Schleife deterministisch darüber ist, woher jede Eingabe stammt, werden Antworten aus dem Gesprächsverlauf und aus den Werkzeugergebnissen abgeleitet — niemals durch das Einfügen von nicht vertrauenswürdigem Text in die Anweisungen. Diese Eigenschaft macht auch das untenstehende Prompt-Layering sicher und gleichzeitig schnell.

Der schichtweise, cache-freundliche Systemprompt

Die Systemaufforderung ist kein einzelner Block. Sie wird in Schichten zusammengesetzt, bewusst so geordnet, dass die Stabile Teile kommen zuerst und die flüchtigen Teile kommen zuletzt. Das ist wichtig, weil Modellanbieter ein Prompt nach seinem Präfix zwischenspeichern: Solange der Anfang des Prompts byte-gleich ist, wird das zwischengespeicherte Präfix wiederverwendet und nur der Rest erneut verarbeitet.

Zone	Schichten (in der Reihenfolge)	Änderungen…
Stabiler Präfix (cachefähig)	Basisidentität + Werkzeug-/Speicherleitfaden → Mieter → Persona → Fähigkeiten	selten — pro Agent/Mieter
Flüchtiger Schwanz (zuletzt angehängt)	Onboarding-Zustand → Speicherauffrischung → das Live-Datum	jede Kurve

Das stabile Präfix enthält alles, was definiert, wer der Agent ist: die eingebaute Identität und die Anleitung, wie Werkzeuge und Speicher funktionieren, dann die Tenant-Schicht, die Persona des Agenten und der gerenderte Fertigkeitenblock. Nichts davon ändert sich zwischen zwei aufeinanderfolgenden Zügen desselben Agenten, daher bildet es ein wiederverwendbares zwischengespeichertes Präfix.

Der volatile Schwanz wird angehängt nach das stabile Präfix genau so, dass es den Cache nie ungültig macht: der Onboarding-Status, der für dieses spezielle Gespräch aufgefüllte Speicher und das aktuelle Datum ändern sich von Runde zu Runde, aber da sie am Ende stehen, kosten sie nur das, was sie hinzufügen.

[!TIP] Diese Reihenfolge ist der Grund, warum Live-Daten wie das heutige Datum vorhanden sein können in jede Runde, ohne jedes Mal für eine Neukodierung der gesamten Identität zu bezahlen. Keep benutzerspezifische Inhalte pro Agent in den stabilen Schichten (Persönlichkeit, Fähigkeiten) und lassen Sie die Motor besitzt den flüchtigen Schwanz.

Wohin als Nächstes

Sehen Sie, wie Mieter isoliert werden in Mandantenfähigkeit & Idempotenz.
Erfahren Sie, wie Antworten zurückgegeben werden in Zuverlässige Lieferung und Wiederherstellung.
Optionale Funktionen werden ausgeführt als Sidecars.