13. fejezet

Platform API

A Platform API külső backend integrátoroknak szóló REST felület – nem a chat-felület, és nem a plugin fejlesztő által implementált tool-ok aktiválási útja, hanem egy harmadik, önálló belépési pont a platform képességeihez.

13.1 Áttekintés

A Platform API két, egymástól független végpontcsaládot ad:

Platform AI feladat (/api/platform/task) – egyetlen hívással aktiválja a platform teljes intelligenciáját (orchestrátor, RAG, tool-ok), chat history és interaktív tisztázó kérdezés nélkül.
Async Task Service (/api/platform/async_task) – egy regisztrált IAsyncTaskTool feladat-végrehajtó explicit indítására és állapotának lekérdezésére szolgál (→ 13. fejezet).

ℹ️

Mindkét végpontcsalád OAuth2 hitelesítést igényel, egymástól eltérő scope-pal: a Platform AI feladat végpont a text-generation, az Async Task Service végpontok az async-task-management scope-ot várják.

13.2 POST /api/platform/task – Platform AI feladat

A kérés törzse egy PlatformRequest objektum:

Mező	Kötelező	Leírás
`prompt`	igen	A feladat / kérdés szövege – az orchestrátor, RAG és tool-ok erre alapoznak.
`domain`	nem	A domain kód, amelynek eszközeit és tudásbázisát kell aktiválni.
`systems`	nem	Rendszer-szűrők – ezekből a rendszerekből szerepeljenek dokumentumok a RAG keresésben.
`toolName`	nem	Explicit tool neve – ha megadott, az LLM-alapú tool routing megkerülésével közvetlenül ez a tool fut.
`outputFormat`	nem	`MARKDOWN` (alapértelmezett), `JSON` vagy `BASE64_PDF`.
`outputSchema`	`outputFormat=JSON` esetén igen	Az elvárt strukturált JSON válasz sémája.
`contextSizeToken`	nem	RAG kontextus maximális mérete tokenekben – ha nincs megadva, a modell maximuma érvényes.
`temperature`	nem	LLM temperature (0.0–2.0), alapértelmezett 0.1.
`stream`	nem	`true` esetén streaming válasz, `false`/hiányzó esetén szinkron blokkoló hívás.

Válasz módja

A válasz alakja a stream mezőtől és az Accept fejléctől függ:

stream: false vagy hiányzó → egyetlen, szinkron JSON válasz.
stream: true + Accept: text/event-stream → Server-Sent Events folyam.
stream: true + más Accept → NDJSON chunk-ok.

Streaming módban a végrehajtási állapotok (TextGenerationResponse eseményekként) folyamatosan érkeznek, a végeredmény az utolsó DONE eseményen jön meg.

Státuszkód	Leírás
200	Sikeres végrehajtás.
400	Hiányzó vagy érvénytelen paraméter (pl. `prompt` kötelező, vagy `outputFormat=JSON` esetén hiányzó `outputSchema`).
401 / 403	Hitelesítés hiányzik, vagy a hívó nem rendelkezik a `text-generation` scope-pal.
500	Belső szerver hiba.

⚠️

Interaktív tisztázó kérdezés (NEEDS_CLARIFICATION) a Platform API-n nem támogatott: az ilyen döntésre jutó tool-ok kihagyásra kerülnek, a válasz a rendelkezésre álló kontextussal készül el.

13.3 POST /api/platform/async_task – feladat indítása

A kérés törzse egy AsyncTaskRequest objektum:

Mező	Kötelező	Leírás
`domain`	igen	A domain kód, amelyhez a feladat tartozik.
`taskType`	igen	A feladat típusazonosítója – a domain-nel együtt egyedien azonosítja az indítandó, regisztrált feladat-végrehajtót (`IAsyncTaskTool.getTaskType()`).
`parameters`	igen	A feladat saját bemeneti paraméterei, tetszőleges JSON struktúraként – a feladat végrehajtója deszerializálja a saját, `getRequestClass()` által megadott paraméter-osztályára.

Sikeres indításkor a válasz egy AsyncTaskStartResponse: taskId (a feladat futásának egyedi azonosítója) és status (a feladat kezdeti állapota, BatchStatus formában, status: "QUEUED" értékkel).

Státuszkód	Leírás
202	A feladat elfogadva, feldolgozásra várólistára helyezve.
400	Nincs a megadott domain/feladattípus kombinációhoz regisztrált feladat-végrehajtó.
409	A megadott domain/feladattípus kombinációhoz már fut egy korábban indított feladat – az új indítás elutasításra kerül, a hibaüzenet tartalmazza a már futó feladat azonosítóját.
401 / 403	Hitelesítés hiányzik, vagy a hívó nem rendelkezik az `async-task-management` scope-pal.

ℹ️

Egy adott domain/feladattípus kombinációnak egyszerre csak egy futó példánya lehet – ez a korlátozás a feladat típusától függetlenül, minden IAsyncTaskTool implementációra egységesen érvényes. Ha egy korábbi feladat feldolgozása rendellenesen szakadt meg és emiatt tartósan blokkolja az újraindítást, a → 13.5 alfejezet ad rá megoldást.

13.4 GET /api/platform/async_task/{taskId} – állapot lekérdezése

A megadott taskId-hoz tartozó BatchStatus-t adja vissza:

Mező	Leírás
`createdAt`	A feladat indításának időpontja.
`status`	A feladat feldolgozottsági állapota (pl. `QUEUED`, `PROCESSING`, `DONE`, `FAILED`).
`finishedAt`	A feladat lezárásának időpontja, vagy `null`, amíg folyamatban van.
`errors`	A feldolgozás közben keletkezett hibák listája (`DocumentError`: `system`, `id`, `errorMessage`).
`phases`	Névvel azonosított fázisok egyidejű előrehaladása – map, kulcsa a feladat végrehajtója által megadott fázisnév.

Egy phases map-beli bejegyzés (PhaseProgress) mezői: startedAt, finishedAt (null, amíg a fázis folyamatban van), total (vagy null, ha nem ismert előre), succeeded, failed.

Státuszkód	Leírás
200	A feladat állapota.
400	A megadott feladat-azonosító nem létezik.
401 / 403	Hitelesítés hiányzik, vagy a hívó nem rendelkezik az `async-task-management` scope-pal.

💡

A phases map pontosan azokat a fázisneveket tartalmazza, amelyeket a feladat végrehajtója az AsyncTaskProgressReporter.reportPhase()/beginLiveProgress() hívásokban megadott – a lekérdező oldalnak a konkrét feladattípus dokumentációjából (vagy a válaszból magából) kell ismernie ezeket.

13.5 POST /api/platform/async_task/release – beragadt feladat feloldása

Ha egy feladat feldolgozása rendellenesen szakad meg – például a feldolgozó folyamat a végrehajtás közben leáll –, a feladat állapota tartósan QUEUED vagy PROCESSING maradhat, és emiatt a hozzá tartozó domain/feladattípus kombináció új indítási kísérlete mindaddig 409-cel elutasításra kerül, amíg valaki ezt fel nem oldja. Ez a végpont pontosan erre való: a kérés törzsében megadott domain/feladattípus kombinációhoz megkeresi a jelenleg aktívnak jelölt feladatot, hibával lezártnak jelöli, és ezzel egyidejűleg feloldja a kombináció zárolását is – utána a kombináció újra indítható.

A kérés törzse egy AsyncTaskRequest objektum, ugyanaz a típus, amivel a feladat indult – a domain és a taskType mező azonosítja a feloldandó kombinációt, a parameters mező figyelmen kívül marad. Sikeres hívás után a válasz a feladat lezárt BatchStatus-a (status: "DONE_WITH_ERROR").

Státuszkód	Leírás
200	A feladat lezárva, a zárolás feloldva.
400	A megadott domain/feladattípus kombinációhoz nincs aktív feladat.
401 / 403	Hitelesítés hiányzik, vagy a hívó nem rendelkezik az `async-task-management` scope-pal.

⚠️

A végpont nem ellenőrzi, hogy a feladat ténylegesen még fut-e valahol – kizárólag azt jelenti ki, hogy a hívó szerint a feladat futása megszakadt. Csak akkor hívd, ha erről ténylegesen meg vagy győződve, különben egy még ténylegesen futó feladat zárolását oldhatod fel idő előtt, ami két párhuzamos futást engedhet meg ugyanahhoz a domain/feladattípus kombinációhoz.

12. fejezet: Aszinkron feladatok 14. fejezet: MCP-integráció