Bevezető és architektúra áttekintés

1.1   Mi az Agent Orchestration / GraphRAG Platform?

Az Agent Orchestration / GraphRAG Platform egy on-premise rendszer, amelyet egészségügyi, közigazgatási, jogi és nagyvállalati szervezetek számára fejlesztettünk – mindenhol, ahol komoly szaktudás él a szervezetben, és annak védelme üzleti érdek. A platform koordinálja a domain-specifikus AI agenteket: hozzáférést ad a szervezet dokumentumaihoz, strukturált adataihoz és külső forrásaihoz, LLM-alapú feldolgozást végez rajtuk, majd a chatbot vagy a REST API felületén keresztül ellenőrizhető, forrásalapú eredményt ad vissza.

Négy tulajdonsága különbözteti meg az általános chatbot megoldásoktól:

• On-premise működés. Az adatok nem hagyják el a szervezet infrastruktúráját. A nyelvi modell és a teljes keresési réteg helyben fut, felhőhöz való csatlakozás nélkül is.
• Agentic viselkedés. A rendszer nem csupán keres és válaszol. Képes összetett, többlépéses feladatokat koordinálni: al-kérdésekre bontja a problémát, szükség esetén pontosítást kér a felhasználótól, és különböző képességeket sorban vagy párhuzamosan aktiválhat.
• Teljes izolációval bővíthető. A platform plugin architektúrával rendelkezik. Egyedi képességek JAR fájlként tölthetők be, és a platform biztosítja, hogy minden plugin pontosan a saját hatáskörén belül maradjon.
• Java/Spring Boot alapú, keretrendszer-független implementáció. Az Apache Spark JVM-natív – PySpark overhead nélkül fut. Nincs függőség kész RAG keretrendszerre (LangChain, LlamaIndex): saját OpenAI-kompatibilis kliens, saját retrieval pipeline, saját score fusion. A Java/Spring Boot kombináció az egészségügyi és közigazgatási szektorban évtizedek óta bizonyított enterprise-grade platform – kiszámítható verziózással, teljes JVM monitoring-gal és visszafelé kompatibilitással.

Rendszer-alapú vs. modell-alapú agentikus viselkedés

A modern AI trendek a modell felé tolják az orchestrációs logikát: a language model maga dönti el, mikor hív tool-t, milyen lépéseket tesz, hogyan értelmezi az eredményt (tool calling, function calling, ReAct). Ez gyors prototipizálást tesz lehetővé, de termelési rendszerben komoly hátrányokkal jár – a vezérlési folyamat nem determinisztikus, nehezen naplózható, és a modell viselkedése frissítéskor visszafelé nem kompatibilis.

Ez a platform rendszer-alapú agent orchestrációt valósít meg: az agenteket a Java kód aktiválja, koordinálja és sorba rendezi – nem a modell. Az LLM jól körülhatárolt, determinisztikus feladatokat kap: kérdés normalizálás, paraméter-kinyerés, osztályozás, végső válasz generálás. Minden tool-aktiválási döntés, prioritás és elágazás a kódban él, naplózható és tesztelhető. Ez az architektúra kiszámítható, auditálható agent viselkedést eredményez – függetlenül attól, hogy a mögöttes modell változik-e.

Egyetlen telepítésen belül több, egymástól teljesen független domain futhat párhuzamosan. Egy kórházi intézmény például üzemeltethet egyszerre egy betegdokumentációs, egy belső szabályzati és egy HR-es domain-t – ugyanazon a szerveren, de teljes adatizolációval. A felhasználó a bejelentkezéskor, illetve az API hívásakor mindig meghatározza, melyik domain-nel dolgozik.

1.2   Domain és system – az izolációs határok

A platform két fogalmat használ a hatáskör meghatározásához: a domain-t és a system-t. Ezek megértése kulcsfontosságú, mert a plugin-ek regisztrációja és aktiválódása mindkét dimenzió mentén szűrhető.

Domain – teljes izolációs határ

A domain a platform legerősebb szervezési egysége. Minden, ami a platformon belül történik – a keresés, a tool aktiválás, az orchestrátor döntései, a tudásbázis tartalma – a domain határain belül marad. Egy domain tudásbázisából semmi sem szűrődik át egy másik domain-be, és fordítva.

Praktikusan: ha a plugin egy adott domain-hez van regisztrálva, az csak akkor aktiválódik, ha a felhasználói kérés ahhoz a domain-hez érkezik. Más domain kéréseit a platform nem irányítja hozzá.

System – opcionális szűkítő a domainen belül

A system a domainen belüli szűkítés eszköze. Ha egy kéréshez system azonosítók vannak megadva, a platform a keresést és a tool aktiválást leszűkíti az adott system-hez tartozó adatokra és eszközökre.

Például egy egészségügyi domain-en belül a „belgyógyászat" és a „kardiológia" külön system-ként üzemelhet – azonos infrastruktúrán, de elkülönített adatkészlettel és esetleg eltérő eszközökkel.

A plugin szempontjából a system két dolgot jelent:

• Ha a tool nem deklarál system-t (null értéket ad vissza az erre vonatkozó metódusban), akkor csak akkor aktiválódik, ha a kérésben sincs system szűrő – ha a kérés konkrét system(eke)t ad meg, a null deklarációjú tool kimarad.
• Ha a tool az IChatbotTool.ALL értéket adja vissza, minden system mellett aktiválódik, függetlenül attól, hogy a kérésben van-e system szűrő – ez a domainen belül explicit, szándékos „minden system-hez elérhető" jelölés.
• Ha a tool konkrét system-t deklarál, akkor csak akkor aktiválódik, ha az a system szerepel az aktuális kérésben. Ez lehetővé teszi, hogy egy plugin-t szándékosan csak egy szűkebb szegmensre korlátozzunk.

1.3   Hogyan épül fel a rendszer?

A platform egy kérés-feldolgozási pipeline köré szerveződik. Minden felhasználói üzenet végighalad ezen a pipeline-on, amelynek egyes lépéseit a platform maga vezérli, más lépéseit viszont plugin-ek töltik ki tartalommal.

1.4   A pluginok mint AI agentek

A plugin a platformon belül egy AI agent: egy Java osztály, amelyet a platform aktivál, koordinál és megfelelő kontextussal lát el. Az agent hozzáférhet a szervezet bármely adatforrásához – adatbázishoz, API-hoz, dokumentumtárhoz –, LLM-mel feldolgozhatja az adatokat, és strukturált eredményt adhat vissza a pipeline-nak.

Az agentek egy része kontextust biztosít a chatbot válaszaihoz: lekérdez, szűr, majd a releváns dokumentumokat átadja az LLM-nek. Ez a leggyakoribb használati mód, de korántsem az egyetlen. Agentek generálhatnak dokumentumokat, indíthatnak webes keresést, hívhatnak külső API-t, vagy egy másik agent által előkészített adatokon végezhetnek LLM-alapú feldolgozást – a chatbot ebben csupán az egyik lehetséges belépési pont.

A platform REST API-n keresztül is teljes mértékben elérhető, így ugyanezek az agentek bármely meglévő vállalati rendszerbe integrálhatók – chatfelület nélkül is. Erről a 1.6 alfejezet szól részletesebben.

A platform négy fő bővítési irányt kínál. Ezek nem zárják ki egymást: egy plugin JAR fájl több tool-t is tartalmazhat, akár különböző típusokat vegyítve. Minden esetben van platform-szintű abstract alaposztály, amelyből örökölni lehet – a fejlesztőnek nem kell nulláról kezdenie.

Alap tool (IChatbotTool)

A platform LLM-alapú döntéssel határozza meg, hogy az adott kérdésre ezt a tool-t kell-e aktiválni. Az aktiváláshoz nincs szükség orchestrátorra. A platform a következő abstract alaposztályokat biztosítja közvetlen örököltetésre:

• AbstractWebSearchTool – valós idejű web- vagy egyéb külső keresés, amelynek eredménye kontextusként vagy kész válaszként kerülhet vissza

Ha ezek egyike sem illik a use case-re, a plugin közvetlenül az IChatbotTool interfészt implementálhatja – nincs kötelező alaposztály. Teljesen egyedi tool-ok (pl. időjárás-előrejelzés, menetrend-lekérdezés, külső API integráció) jellemzően így készülnek.

Orchestrátor tool (AbstractOrchestratorTool)

Az orchestrátor domain-specifikus vezérlési logikát valósít meg. Teljes kontrollt kap a kérés felett: maga dönti el, milyen al-kérdésekre bontja a feladatot, milyen sorrendben és párhuzamosan aktiválja a többi tool-t, és hogyan állítja össze a végső kontextust. A platform az AbstractOrchestratorTool abstract alaposztályt biztosítja, amely az összetett koordinációs logikát (prioritáskezelés, párhuzamos végrehajtás, clarification állapotkezelés) tartalmazza; a fejlesztőnek csak a domain-specifikus részt kell implementálnia.

Orchestrátor által aktivált tool (IOrchestratorActivatedTool)

Ezeket a tool-okat kizárólag egy orchestrátor aktiválhatja – a platform LLM-alapú routing mechanizmusa nem irányítja hozzájuk a kéréseket. Az orchestrátor explicit dönt arról, mikor és milyen prioritással indítja el őket.

A platform a következő abstract alaposztályokat biztosítja:

• AbstractPageAnalysisTool – oldalanalízis alapja; belőle két specializált ág örökölhető:
  • AbstractSummaryTool – gráf-alapú összefoglalás generálás
  • AbstractEntityAnalysisTool – entitás elemzés és vizualizáció
  • AbstractContextSearchTool – kontextus-előállítás deep fallback esetén
• AbstractRAGRetrievalTool – domain-specifikus RAG retrieval; az orchestrátor fallback-ként mindig aktiválja, ha más tool nem adott elegendő kontextust

Az IClarifiableTool ebbe a csoportba tartozik: az IChatbotTool és az IOrchestratorActivatedTool kombinációja, amely lehetővé teszi, hogy a tool hiányos információ esetén pontosító kérdéseket tegyen fel a felhasználónak. A párbeszéd állapotát a platform tartja fenn; a tool csak a kérdéseket és a válasz feldolgozási logikát definiálja.

Ingestion tool (IIngestionTool)

Offline pipeline, amely a tudásbázis feltöltéséért felelős. Az ingestion tool nem a valós idejű kérések kezelésében vesz részt, hanem a dokumentumokból strukturált tudást épít fel, amelyet a platform keresési rétege később felhasznál. A platform alap ingestion folyamata a REST API-n keresztül indítható el; az AbstractNERIngestionTool alaposztályból örökölve ez NER-alapú tudásgráf feltöltéssel egészíthető ki.

Mintaprojekt egy önálló, domain-független tool-hoz

Egy jó gyakorló feladat a plugin fejlesztés elsajátításához egy olyan egyszerű, önálló (orchestrátor nélküli) tool megírása, amely egy nyilvános, regisztráció és API kulcs nélkül hívható külső API-t csomagol be – például egy időjárás-előrejelző szolgáltatást.

Egy ilyen minta egyetlen fájlban mutatja be a legfontosabb plugin fejlesztői mintákat:

• IClarifiableTool implementáció – ha a felhasználó nem adta meg a szükséges paramétereket, a tool visszakérdez
• ILlmAssistant használata – az LLM kinyeri a paramétereket a felhasználói szövegből
• getDomain() = null – a tool minden domain-ben elérhető
• Külső HTTP hívás Java beépített HttpClient-tel, extra függőség nélkül
• ToolExecutionResult.asGuaranteedContext() – az eredmény szövegként kerül az LLM kontextusába, amely természetes nyelvű választ generál belőle

1.5   A plugin rendszer felépítése

Egy plugin a következő elemekből áll:

• plugin.jar – a tool implementációkat tartalmazó JAR fájl. Ez egy „vékony" JAR: csak a saját kódot tartalmazza, a platform függőségeit nem.
• lib/ könyvtár – a plugin saját, egyedi függőségei. A platform tranzitív függőségeit itt nem kell megismételni – azokat a platform-bom gondoskodik elérhetővé tenni.
• plugin.properties – opcionális konfigurációs fájl. Ha a plugin saját beállításokat igényel (pl. adatbázis host, API kulcs), ezeket itt lehet megadni. A platform a plugin betöltésekor beolvassa és a Spring Environment-be regisztrálja – a tool @Value annotált mezői már látják ezeket az értékeket. Az application.yml bármely értéket felülírhat (a plugin.properties a legalacsonyabb prioritással kerül be).
• ServiceLoader regisztráció – a JAR-ban egy szöveges fájl jelöli ki, melyik osztályok az IChatbotTool implementációk. A platform ezt a plugin betöltésekor olvassa be, és automatikusan regisztrálja a tool-okat.

A platform a plugin-t induláskor, illetve futás közben – amint a plugin könyvtára megjelenik a plugins könyvtárban – betölti, a tool-okat Spring kontextusba regisztrálja, és innentől automatikusan részt vehetnek a kérések kiszolgálásában. A plugin könyvtárának törlésekor a platform eltávolítja a tool-okat, cseréjekor az új verziót tölti be – mindezt újraindítás nélkül (→ 11. fejezet).

1.6   A platform REST API rétege

A platform valamennyi funkciója REST/SSE API-n keresztül is elérhető – a chatbot felület csupán az egyik kliens felette. Ez azt jelenti, hogy a platformon futó agentek rendszerszinten integrálhatók bármely meglévő vállalati alkalmazásba, ERP-be vagy munkafolyamat-kezelő rendszerbe: API híváson keresztül kérdezhetők, aktiválhatók, és az eredményük strukturált formában (Markdown, Base64-kódolt PDF, JSON) kapható vissza.

Az API rétegen keresztül kezelhető többek között:

• Rendszerszintű integráció. Chatbot helyett bármely alkalmazás közvetlenül hívhatja a platform agent pipeline-ját. A ranking stratégia, a kontextus-bővítési mód, a top-K és a kimenet formátuma mind paraméterezhető hívásonként.
• Domain létrehozása és konfigurálása. Mielőtt egy plugin egy adott domain-hez regisztrálódhat, a domain-t a platform REST API-ján kell létrehozni. A domain neve az a kulcs, amellyel a plugin tool-ok azonosítják saját hatáskörüket.
• Dokumentum feltöltés és alap ingestion. A platform alapból képes dokumentumokat (pl. PDF, Word) feldolgozni és a domain tudásbázisába indexelni, REST API híváson keresztül. Ha ennél összetettebb, domain-specifikus feldolgozásra van szükség, ahhoz kell az IIngestionTool plugin.

1.7   Amit az SDK elvonatkoztat

Az SDK tervezési elvei között az egyik legfontosabb: a plugin fejlesztőnek nem kell ismernie a platform belső működését. Az alábbi területek teljes egészében a platform felelőssége:

• Keresési réteg. A dokumentumok indexelése, vektorizálása és visszakeresése a platform feladata. A plugin CONTEXT módban dokumentumokat adhat a kontextushoz, de a keresési algoritmus felett nincs közvetlen kontrollja.
• LLM kommunikáció. A plugin nem hív LLM-et közvetlenül. Az ILlmAssistant interfészen keresztül küldhet promptot és kap strukturált választ. A modell kiválasztása, a streaming kezelés és a hibakezelés a platform dolga.
• Session és history kezelés. A chat előzmények tárolása, a felhasználói session azonosítása és a clarification állapot perzisztálása mind a platform szintjén történik.
• Autentikáció. A hitelesítés a plugin elől teljesen transzparens. A plugin annyit tud meg a felhasználóról, amennyit a platform az isEligible() hívásban átad.

1.8   Hogyan épül fel ez a dokumentáció?

A fejezetek egymásra épülnek, de az egyes témák önállóan is olvashatók:

• 2. fejezet – Projekt beállítás: Maven POM, platform-bom, plugin könyvtárstruktúra. Ez az alapja mindennek, érdemes átolvasni még akkor is, ha már van tapasztalatod Spring-gel.
• 3–4. fejezet – Az első egyszerű tool megírása és a tool típusok áttekintése. Ha nem tudod, melyik interfésztől érdemes örökölni, a 4. fejezet segít dönteni.
• 5–6. fejezet – Haladóbb témák: orchestrátor és interaktív tool. Csak akkor szükséges, ha komplex logikát vagy felhasználói párbeszédet tervezel.
• 7–8. fejezet – LLM hívások és a visszatérési módok részletei. Referencia jellegű, menet közben is visszakereshető.
• 9. fejezet – Ingestion pipeline. Csak akkor releváns, ha a plugin tudásbázist is tölt fel, nem csak lekérdez.
• 10. fejezet – Deploy. A csomagolás és a könyvtárstruktúra részletei, amelyek nélkül a plugin nem töltődik be.
• 11. fejezet – API referencia. Az SDK összes publikus interfészének és osztályának leírása, rövid megjegyzésekkel.