Autonomer Agent & Tool Loop (Coder-Ansatz)
Der autonome ReAct-Loop des LoreKeeper Agenten mit nativer Tool-Ausführung gegen Directus und LiteLLM
Autonomer Agent & Tool Execution Loop
Neben der sequenziellen Pipeline (generateScene) verfügt der LoreKeeper Service über einen autonomen Agenten (AgenticChatService). Dieser fungiert als intelligenter Assistent und "Coder" für Autoren, Lektoren und Lore-Verwalter.
Statt vorgegebener Einzelschritte entscheidet der Agent im Gespräch autonom, welche Daten er aus Directus benötigt, wann er Entitäten anlegen muss oder wann eine Szene persistiert werden soll.
Architektur des Agentic Loops
sequenceDiagram
autonumber
actor Client as User / Frontend
participant Fastify as Fastify API (/api/agent/chat)
participant Agent as AgenticChatService
participant LiteLLM as LiteLLM (Gemini 2.5)
participant Directus as Directus Headless CMS
Client->>Fastify: POST /api/agent/chat (Prompt, History, BookId)
Fastify->>Agent: chat(input)
Agent->>Directus: Hole Buch & Series-Kontext
loop Multi-Iteration ReAct Loop (max 6 Iterationen)
Agent->>LiteLLM: chat.completions.create(messages, tools)
alt LLM verlangt Tool-Call(s)
LiteLLM-->>Agent: tool_calls: [search_lore, get_entity_state, ...]
Agent->>Directus: executeTool(name, args)
Directus-->>Agent: Daten / Records
Agent->>Agent: Tool-Ergebnis in Chat-Historie einspeisen
else LLM liefert finale Antwort
LiteLLM-->>Agent: content: "Finale Antwort..."
end
end
Agent-->>Fastify: Result { reply, toolCallsExecuted, thoughtProcess }
Fastify-->>Client: 200 OKDie 6 Kern-Tools des Agenten
Der Agent besitzt über das @directus/sdk Zugriff auf folgende native Werkzeuge:
| Tool | Zweck | Directus Ziel-Tabelle |
|---|---|---|
search_lore | Durchsucht Charaktere, Orte, Fraktionen, Regeln im Universum | lore_entities |
get_entity_state | Lädt statische Traits sowie die jüngsten aktiven Bitemporal Patches | lore_entities + lore_states |
record_lore_state | Schreibt einen neuen State-Patch (Verletzung, Wissen, Loyalität) | lore_states |
create_lore_entity | Legt eine neue kanonische Entität im Universum an | lore_entities |
fetch_chapter_scenes | Holt vorherige Szenen eines Kapitels für den Anschluss | scenes |
persist_scene | Speichert eine generierte narrative Szene in Directus | scenes |
Ausführungsphasen
1. Universums-Bindung & System Prompt
Der Service validiert die bookId in Directus und extrahiert die zugehörige series_id. Der System-Prompt instruiert das Modell strikt, keine Behauptungen ohne Tool-Verifikation aufzustellen.
2. Autonome Tool-Entscheidung
Das LLM (writer-model via LiteLLM) analysiert den Benutzerwunsch. Wenn Fakten oder Zustände benötigt werden, generiert das Modell Function Calls (z. B. search_lore nach "Vaelin").
3. Sichere Directus-Ausführung
AgenticChatService.executeTool führt die Abfrage über den mit Rechten versehenen Directus Client aus. Fehler werden isoliert und als Tool-Ergebnis an das LLM zurückgegeben, sodass der Agent sich selbst korrigieren kann.
4. Bitemporale Zustands-Aktualisierung
Ändert sich im Handlungsverlauf der Zustand einer Figur (z. B. "Vaelin bricht sich den linken Arm"), ruft der Agent record_lore_state auf. Der State-Patch wird mit Verweis auf das Kapitel und die Quell-Szene gespeichert.
5. Finale Ausgabe & Audit-Trace
Sobald das Modell alle notwendigen Aktionen abgeschlossen hat, erzeugt es die finale Antwort. Der Aufrufer erhält neben dem Text auch den kompletten Trace aller ausgeführten Tools und Gedankenschritte (thoughtProcess).