Agent Chat & Tool Orchestration
Interaktive Multi-Turn Kommunikation mit dem autonomen LoreKeeper Agenten und Abruf registrierter Function-Calling Tools
Agent Chat & Tools
Die Agent-Endpunkte ermöglichen eine direkte, interaktive Kommunikation mit dem autonomen LoreKeeper Agenten. Der Agent entscheidet eigenständig über Tool-Aufrufe gegen Directus, verarbeitet Ergebnisse in einer ReAct-/Tool-Calling-Schleife und liefert die finale Antwort inklusive des gedanklichen Ablaufes (thoughtProcess) und der ausgeführten Tools zurück.
1. POST /api/agent/chat
Führt einen Chat-Turn mit dem LoreKeeper Agenten aus.
Request Body
{
"bookId": "11111111-2222-3333-4444-555555555555",
"messages": [
{
"role": "user",
"content": "Welche Verletzungen hat Vaelin aktuell und wie beeinflussen sie seine Kampfkraft?"
}
],
"contextChapterId": "22222222-3333-4444-5555-666666666666",
"maxIterations": 6
}| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
bookId | string (UUID) | Ja | Das Buch bzw. das Universum, in dessen Kontext der Agent agiert. |
messages | Array<ChatMessage> | Ja | Die bisherige Konversationshistorie (role: user, assistant, system). |
contextChapterId | string (UUID) | Nein | Optionales Fokus-Kapitel für zeitliche Relevanz (Bitemporalität). |
maxIterations | number | Nein | Maximale Anzahl an Tool-Calling-Iterationen (Standard: 6, Min: 1, Max: 15). |
Response (200 OK)
{
"success": true,
"data": {
"reply": "Vaelin hat in Kapitel 3 eine tiefe Schnittwunde am linken Unterarm erlitten...",
"toolCallsExecuted": [
{
"name": "search_lore",
"arguments": {
"query": "Vaelin",
"type": "character"
},
"result": [
{
"id": "33333333-4444-5555-6666-777777777777",
"name": "Vaelin Al Sorna",
"type": "character",
"static_traits": { "hair": "dark", "origin": "Nordmark" }
}
]
},
{
"name": "get_entity_state",
"arguments": {
"entityId": "33333333-4444-5555-6666-777777777777"
},
"result": {
"entity": { "name": "Vaelin Al Sorna" },
"activeStates": [
{
"id": "state-uuid-1",
"state_patch": { "injury": "Schnittwunde linker Unterarm", "combat_penalty": "20%" }
}
]
}
}
],
"thoughtProcess": [
"Schritt 1: Agent fordert 1 Tool-Aufruf(e) an: search_lore",
"Schritt 2: Agent fordert 1 Tool-Aufruf(e) an: get_entity_state",
"Schritt 3: Finale Antwort generiert."
]
}
}2. GET /api/agent/tools
Liefert die vollständige JSON-Schema Spezifikation aller Tools, die dem Agenten aktuell zur Verfügung stehen.
Response (200 OK)
{
"success": true,
"count": 6,
"tools": [
{
"type": "function",
"function": {
"name": "search_lore",
"description": "Search for canon lore entities (characters, locations, factions, objects, rules)...",
"parameters": { ... }
}
},
{
"type": "function",
"function": {
"name": "get_entity_state",
"description": "Get the static traits and the latest active bitemporal state patches...",
"parameters": { ... }
}
},
{
"type": "function",
"function": {
"name": "record_lore_state",
"description": "Record a new bitemporal state patch for an entity...",
"parameters": { ... }
}
},
{
"type": "function",
"function": {
"name": "create_lore_entity",
"description": "Create a new canon entity in the book series universe...",
"parameters": { ... }
}
},
{
"type": "function",
"function": {
"name": "fetch_chapter_scenes",
"description": "Read previous scenes in a chapter to maintain continuity...",
"parameters": { ... }
}
},
{
"type": "function",
"function": {
"name": "persist_scene",
"description": "Save or update a generated narrative scene in Directus...",
"parameters": { ... }
}
}
]
}3. POST /api/agent/tools/execute
Ermöglicht das direkte, deterministische Ausführen eines einzelnen Agenten-Werkzeugs gegen Directus – ohne den ReAct-LLM-Loop zu durchlaufen. Dies ist ideal für programmatische Workflows, Tests oder Frontend-Tools.
Request Body
{
"toolName": "search_lore",
"arguments": {
"query": "Vaelin",
"type": "character"
},
"bookId": "43f83ad5-b4f9-4a4f-989c-5ea25325fd97"
}| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
toolName | string | Ja | Name des auszuführenden Tools (z. B. search_lore, get_entity_state, etc.). |
arguments | Record<string, unknown> | Nein | Eingabeargumente für das Tool gemäß JSON-Schema. |
bookId | string (UUID) | Nein | Buch-ID zur automatischen Auflösung der zugehörigen Buchserie (series_id). |
Response (200 OK)
{
"success": true,
"tool": "search_lore",
"result": [
{
"id": "6bd1b6b5-7ee0-4ccb-b37f-7022f7a2059d",
"series_id": "57ccc7ca-ac30-40b7-9e79-562b19dafc2c",
"type": "character",
"name": "Vaelin Al Sorna",
"static_traits": {
"hair": "schwarz",
"role": "Krieger der Schattenwacht",
"origin": "Nordmark"
}
}
]
}Alle Tool-Aufrufe werden transaktionssicher über das typisierte Directus SDK (@directus/sdk) im Scope der jeweiligen Buchserie ausgeführt.