--- title: Agentic Harness Koncepció category: concept sources: - tanulmanyok/2026-05-14_what_is_harness_orchestration_agentfield.md - tanulmanyok/2026-05-14_harness_as_black_box_agentfield.md - tanulmanyok/2026-05-14_harness_as_membrane_agentfield.md - 2026-05-14_what_is_harness_orchestration_agentfield.md - 2026-05-14_harness_as_black_box_agentfield.md - 2026-05-14_harness_as_membrane_agentfield.md created: 2026-05-07 updated: 2026-05-14 tags: - harness - orchestration - agent - pipeline - state-machine - heartbeat - event-watcher - bootstrap - openclaw confidence: high summary: 'OpenClaw-ra épülő moduláris keretrendszer pipeline automatizáláshoz. Komponensei: State Backend (state.json), Goal Tracking Engine, Task Decomposition, Heartbeat mint proaktív motor, Event Watcher (fájlfigyelés), Session Bootstrap Hook, Orchestrator Skill. A fork alternatívája — a meglévő OpenClaw plugin/skill/cron/hook rétegeket használja. Nulla manuális pipeline vezénylés, éjszakai feldolgozás, determinisztikus lépéssorrend. Cél: a podcast feldolgozás teljes automatizálása' --- # Az Agentic Harness — Részletes Koncepció > OpenClaw mint runtime, harness mint moduláris ráépülő keretrendszer > Tollaskígyó, 2026-05-07 --- ## 1. A probléma Ma az OpenClaw session-jei izoláltak. Minden session nulláról indul — a memóriát fájlokból kell rekonstruálni. A proaktivitás külső triggereken múlik (cron, heartbeat, emberi üzenet). A célkövetés nem strukturált. **Amit ez jelent a gyakorlatban:** amikor Henky bedob egy podcast MP3-at, végigmegy egy pipeline (whisper → summary → wiki raw → topic update → index rebuild → cleanup → Taildrop), de ezt nekem manuálisan kell vezényelnem minden egyes lépésnél. Ha a session timeout-ol, a pipeline megszakad. Ha a Taildrop éjjel érkezik, senki nem dolgozza fel reggelig. **A harness ezt oldja meg** — nem fork-ként, hanem az OpenClaw meglévő modularitására építve. --- ## 2. Architektúra áttekintés ``` ┌─────────────────────────────────────────────────────────┐ │ AGENTIC HARNESS │ │ │ │ ┌──────────┐ ┌───────────┐ ┌────────────────────┐ │ │ │ State │ │ Goal │ │ Session Bootstrap │ │ │ │ Backend │ │ Tracker │ │ Hook │ │ │ └────┬─────┘ └─────┬─────┘ └─────────┬──────────┘ │ │ │ │ │ │ │ ┌────┴──────────────┴──────────────────┴──────────┐ │ │ │ Orchestrator Skill │ │ │ │ (task decomposition, pipeline execution, │ │ │ │ error recovery, dependency management) │ │ │ └─────────────────────┬────────────────────────────┘ │ │ │ │ │ ┌─────────────────────┴────────────────────────────┐ │ │ │ Trigger Layer │ │ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ │ │ Heartbeat │ │ Event Watcher │ │ │ │ │ │ (polling) │ │ (cron) │ │ │ │ │ └──────────────┘ └──────────────┘ │ │ │ └──────────────────────────────────────────────────┘ │ │ │ └────────────────────────┬────────────────────────────────┘ │ ┌────────────────────────┴────────────────────────────────┐ │ OPENCLAW RUNTIME │ │ Gateway • Session Mgr • Tool System • Plugins • Cron │ └─────────────────────────────────────────────────────────┘ ``` A harness **nem** az OpenClaw-ot módosítja. Ráépül. Az OpenClaw a motor, a harness a sofőr. --- ## 3. Komponensek részletesen ### 3.1 State Backend **Probléma:** minden session nulláról indul. MEMORY.md és memory/YYYY-MM-DD.md fájlok tartalmazzák a történetet, de ezeket olvasni kell — nincs strukturált állapotgép. **Megoldás:** `state.json` a workspace-ben. Strukturált, gép által írt és olvasott állapot. ``` $HOME/.openclaw/workspace/state.json ``` ```json { "version": 1, "lastSession": "2026-05-07T22:30:00+02:00", "activeGoals": [ { "id": "goal-001", "description": "TSP 3841 feldolgozása", "priority": "high", "created": "2026-05-07T04:55:00+02:00", "source": "taildrop", "steps": [ {"id": "step-1", "action": "transcribe", "status": "done", "artifact": "/tmp/transcripts/tsp_3841.txt"}, {"id": "step-2", "action": "summarize", "status": "done", "artifact": "summaries/survival_podcast/2026-05-07_3841_boys_to_men.md"}, {"id": "step-3", "action": "wiki_raw", "status": "done"}, {"id": "step-4", "action": "wiki_topic_update", "status": "done"}, {"id": "step-5", "action": "rebuild_indexes", "status": "done"}, {"id": "step-6", "action": "cleanup", "status": "done"}, {"id": "step-7", "action": "notify", "status": "pending"} ] } ], "pendingTasks": [], "watchTargets": { "downloads": ["*.mp3", "*.m4a"], "transcripts": ["/tmp/transcripts/*.txt"], "taildrop": [] }, "pipelineTemplates": { "podcast_from_audio": [ "transcribe", "summarize", "wiki_raw", "wiki_topic_update", "rebuild_indexes", "cleanup", "notify" ], "podcast_from_transcript": [ "summarize", "wiki_raw", "wiki_topic_update", "rebuild_indexes", "cleanup", "notify" ] } } ``` **Működés:** - Session indításakor a bootstrap hook betölti - Session közben minden lépés után frissül - Session végén / új session indulásakor a következő session látja, hol tartottunk **Miért nem a meglévő MEMORY.md:** mert az emberi fogyasztásra van. A state.json gép-gép kommunikáció — nem kell tokeneket égetni a parsolására. --- ### 3.2 Goal Tracking Engine **Probléma:** a célok nincsenek formalizálva. "Feldolgozni ezt a podcastot" nincs szétbontva lépésekre, nincs függőségkezelés, nincs retry logika. **Megoldás:** a goal tracker a state.json `activeGoals` listáját kezeli, és minden heartbeat-nél ellenőrzi: van-e olyan lépés ami készen áll a végrehajtásra? **Goal életciklus:** ``` CREATED → IN_PROGRESS → COMPLETED ↓ FAILED → RETRY (max 3) → FAILED_PERMANENT → notify ``` **Prioritási sorrend:** 1. Ember által explicit kért feladat (azonnal) 2. Taildrop-pal érkezett új fájl (azonnal, ha prioritás high) 3. Félbemaradt pipeline folytatása (következő heartbeat) 4. Batch feldolgozás (üresjáratban) **Deklaratív pipeline definíció:** Minden podcast típushoz tartozik egy pipeline template a state.json-ben. A goal tracker ennek alapján generálja a step-eket és követi a státuszt. ```json { "pipelineTemplates": { "podcast_from_audio": { "steps": [ {"action": "transcribe", "tool": "whisper-cli", "maxRetries": 1, "timeout": 600}, {"action": "summarize", "tool": "llm", "maxRetries": 2, "timeout": 120}, {"action": "wiki_raw", "tool": "write", "maxRetries": 1, "timeout": 30}, {"action": "wiki_topic_update", "tool": "edit", "maxRetries": 2, "timeout": 30}, {"action": "rebuild_indexes", "tool": "exec", "maxRetries": 1, "timeout": 30}, {"action": "cleanup", "tool": "exec", "maxRetries": 1, "timeout": 30}, {"action": "notify", "tool": "sessions_send", "maxRetries": 1, "timeout": 30} ], "dependencies": { "summarize": ["transcribe"], "wiki_raw": ["summarize"], "wiki_topic_update": ["wiki_raw"], "rebuild_indexes": ["wiki_topic_update"], "cleanup": ["rebuild_indexes"], "notify": ["cleanup"] } } } } ``` Ez a definíció garantálja hogy a sorrend mindig helyes, és a step-ek párhuzamosíthatók ahol nincs függőség. --- ### 3.3 Task Decomposition **Probléma:** amikor azt mondod "dolgozd fel", a modellnek kell kitalálnia a lépéseket. Ez hibázhat. **Megoldás:** a pipeline template determinisztikus. A modell nem találja ki a lépéseket — a template adott. A modell szerepe: - **Tartalom megértése** — summary írása, topic azonosítása - **Edge case kezelése** — ha a whisper elhasal, mit csináljunk? - **Minőség ellenőrzése** — a summary jól sikerült-e? A template + LLM kombináció adja a megbízható automatizmust. A template a determinisztikus váz, az LLM a tartalmi intelligencia. --- ### 3.4 Heartbeat mint Proaktív Motor **Probléma:** a heartbeat ma "nézz körül, takaríts, ha van valami szólj" üzemmódban működik. De nem cselekszik proaktívan. **Megoldás:** a heartbeat ciklus átalakítása: ``` Heartbeat.poll() ├── 1. State betöltés (state.json) ├── 2. Ha van IN_PROGRESS goal → folytasd a következő pending step-pel ├── 3. Ha van CREATED goal → indítsd el ├── 4. Ha van FAILED goal és retry < max → próbáld újra ├── 5. EventQueue ellenőrzése (új fájlok?) → új goal létrehozása ├── 6. Housekeeping (broken windows, memory health) └── 7. Ha történt munkavégzés → report. Ha nem → HEARTBEAT_OK ``` **Időzítés:** - A heartbeat ~30 percenként fut. Ha van pending feladat, nem vár a következő ciklusig — azonnal dolgozik. - Hosszú feladatoknál (whisper transzkripció) a heartbeat elindítja, majd a következő ciklusban ellenőrzi a kimenetet. **Éjszakai mód:** 23:00-06:00 között a heartbeat nem értesít (csak dolgozik), kivéve ha kritikus hiba van. --- ### 3.5 Event Watcher **Probléma:** a fájlrendszer változásai (új fájl Downloads-ban, Taildrop érkezés) nem generálnak eseményt. **Megoldás:** cron job ami figyeli a megadott könyvtárakat. ``` EventWatcher (cron, percenként) ├── *.mp3 → létezik? → új goal: podcast_from_audio ├── *.txt → létezik? → new goal: podcast_from_transcript ├── /tmp/transcripts/*.txt → új fájl 0 perce? → vársz? (még íródik) └── Ha új goal keletkezett → state.json frissítés ``` **Implementáció:** nem `inotify` (platformfüggő), hanem egy egyszerű cron ami összehasonlítja a fájllistát az előző futtatással. A diff = új fájl → goal generálás. A state.json `watchTargets` része tárolja a már látott fájlok hash-ét, így a cron tudja mi az új. --- ### 3.6 Session Bootstrap Hook **Probléma:** amikor session indul, nekem kell READ függvényekkel betölteni a MEMORY.md-t, daily log-ot, state-et. Ez sok token és idő. **Megoldás:** az OpenClaw `boot-md` és `bootstrap-extra-files` hook-jai már most is léteznek. A harness ezeket használja. **Ami automatikusan a session context-be kerül:** 1. A harness state összefoglalója (aktív goal-ok státusza) 2. A 3 legmagasabb prioritású pending task 3. Az utolsó session óta történt változások diff-je 4. A heartbeat legutóbbi eredménye **Formátum:** rövid, tömör, token-takarékos. ```markdown ## Harness State (auto-injected) Active goals: 0 Last action: 2026-05-07 22:30 — podcast pipeline completed (Practical AI Model Wars) Pending: none Next heartbeat: 2026-05-07 23:00 ``` Ez az amit a session indulásakor látok — nem kell 10 fájlt végigolvasnom. --- ### 3.7 Orchestrator Skill **Probléma:** a harness viselkedés definiálatlan. Minden session-ben újra kell találnom a keréknyi működést. **Megoldás:** egy `orchestrator` skill ami definiálja a harness viselkedési szabályait. ``` $HOME/.openclaw/workspace/skills/orchestrator/SKILL.md ``` A skill tartalmazza: - Pipeline template-eket (mit kell csinálni milyen sorrendben) - Tool mappinget (melyik lépés melyik tool-t használja) - Error recovery szabályokat - Notifikációs policy-t (mikor kell szólni az embernek) - Wiki struktúra konvenciókat (hová milyen fájl kerül) **Ez a skill a harness "forráskódja".** Nem kód, hanem strukturált utasítások amit a modell követ. A state.json az adat, a SKILL.md a program. --- ## 4. Működési példa — Podcast feldolgozás végig ### 20:00 — Henky bedobja a transcriptet Telegramon ``` Session indul → bootstrap hook betölti a harness state-et → nincs pending goal ``` A transcript fájl megérkezik → én feldolgozom (mint eddig): 1. Summary írása 2. Wiki raw létrehozása 3. Topic frissítése 4. `rebuild_indexes.py --cleanup` 5. Pipeline dokumentálva a daily log-ban ### 22:30 — Session vége Session zárásakor a harness state mentése: minden goal completed, no pending. ### Másnap 02:00 — Henky Taildrop-ol egy MP3-at ``` A Taildrop fájl megérkezik *.mp3 ``` ### 03:00 — EventWatcher cron lefut ``` EventWatcher.scan() → új fájl: epi-3842-*.mp3 (még nem láttuk) → state.json frissítése: új goal CREATED ``` ### 06:00 — Heartbeat ``` Heartbeat.poll() → state.json: goal-002 CREATED → pipeline template: podcast_from_audio, step 1 = transcribe → whisper-cli elindítva háttérben → state frissítve: step-1 IN_PROGRESS ``` ### 06:15 — Whisper kész (70 sor transcript) ``` Heartbeat.poll() → state.json: step-1 DONE, artifact = /tmp/transcripts/tsp_3842.txt → step-2 = summarize (pending, ready) → LLM summary generálás → state frissítve: step-2 DONE ``` ### 06:15-06:16 — Automatikus pipeline folytatás ``` step-3: wiki_raw → DONE step-4: wiki_topic_update → DONE step-5: rebuild_indexes --cleanup → DONE step-6: cleanup → törölve epi-3842 MP3 step-7: notify → "TSP 3842 feldolgozva, wiki-ben, MP3 takarítva" ``` ### 07:00 — Henky felébred A telefonján ott a notifikáció: "TSP 3842 feldolgozva." A summary már a Pixelén van Taildrop-ból. A wiki friss. **Nulla emberi beavatkozás.** A teljes pipeline automatikusan lefutott éjszaka. --- ## 5. Korlátok és trade-offok ### Amit ez a megoldás NEM tud | Korlát | Miért | Alternatíva | |--------|-------|-------------| | **Folyamatos futás** | A heartbeat polling, nem event-driven. 15-30 perc késleltetés | Elfogadható — a podcast feldolgozás nem real-time igény | | **Platformfüggetlen fájlfigyelés** | Nincs `inotify` a cron miatt | Polling elég gyors — percenkénti cron kb 1 másodperc alatt lefut | | **Komplex hibakezelés** | A retry logika egyszerű (max 3), nincs circuit breaker | A podcast pipeline determinisztikus — ritkán van olyan hiba ami retry-vel nem oldódik | | **Multi-tenant** | Egyetlen state.json, egyetlen harness instance | Jelenleg egy felhasználó van — nem probléma | | **Biztonsági sandbox** | A harness ugyanazokkal a jogokkal fut mint én | Az OpenClaw approval rendszere továbbra is aktív — destruktív műveletekhez kell approval | ### Mit nyerünk vele | Nyereség | Hatás | |----------|-------| | **Nulla manuális pipeline vezénylés** | Én a tartalomra fókuszálok, nem a workflow-ra | | **Éjszakai feldolgozás** | Taildrop 02:00-kor → kész 06:15-re | | **Determinisztikus lépéssorrend** | Nincs elfelejtett step, nincs rossz sorrend | | **Strukturált állapot** | Bármelyik session pontosan tudja hol tart a rendszer | | **Skálázható** | Új pipeline template egy JSON definíció | --- ## 6. Összehasonlítás: Fork vs. Moduláris Harness | Dimenzió | Fork | Moduláris Harness | |----------|------|-------------------| | **Kódmennyiség** | Teljes OpenClaw codebase (~300k+ sor) | ~500 sor JSON + SKILL.md + 3 Python script | | **Karbantartás** | Folyamatos rebase a mainline-ra | Nulla — a harness független az OpenClaw verziójától | | **Upgrade** | Minden OpenClaw release = újabb rebase | `openclaw update` → harness tovább működik | | **Komplexitás** | Minden OpenClaw változás potenciális törés | Csak a saját réteg változik | | **Hordozhatóság** | Csak a fork-olt verzióval | Bármelyik OpenClaw install-on működik | | **Fejlesztési idő** | Hónapok | Napok | | **Funkcionalitás** | Teljes (bármi módosítható) | Ami a plugin/skill/hook/cron rétegen keresztül elérhető | **Konklúzió:** a fork akkor indokolt ha az OpenClaw core viselkedését kell módosítani (pl. session modell, gateway architektúra). A harness célja nem ez — a harness a meglévő runtime-ot használja okosabban. A moduláris megközelítés a létező OpenClaw erősségeit lovagolja meg (plugin SDK, skill rendszer, cron, hook-ok) ahelyett hogy újra feltalálná őket. --- ## 7. Implementációs terv ### Fázis 1: State Backend + Pipeline Templates (1 nap) 1. `state.json` séma definiálása és létrehozása 2. `pipelineTemplates` definíciók az ismert podcast típusokra 3. `scripts/update_state.py` — state frissítő segédeszköz 4. `scripts/bootstrap_state.py` — state betöltő a session hook-hoz ### Fázis 2: Event Watcher (1 nap) 1. `scripts/event_watcher.py` — fájlváltozás detektálás + goal generálás 2. Cron job: percenkénti futtatás 3. `watchTargets` kezelése state.json-ben 4. Deduplikáció (hash alapú) ### Fázis 3: Heartbeat Upgrade (1 nap) 1. `HEARTBEAT.md` átalakítása: state-aware ciklus 2. Goal prioritizálás és step execution a heartbeat-ben 3. Retry logika 4. Éjszakai mód ### Fázis 4: Orchestrator Skill (1 nap) 1. `skills/orchestrator/SKILL.md` megírása 2. Pipeline szabályok, tool mapping, error recovery definiálása 3. Wiki struktúra szabályok ### Fázis 5: Session Bootstrap (fél nap) 1. Session hook konfigurálása a harness state injektálására 2. Token-takarékos formátum 3. Tesztelés: session induláskor a kontextus automatikusan tartalmazza a state-et ### Fázis 6: Integráció + Teszt (1 nap) 1. Teljes körű teszt: Taildrop → automatikus feldolgozás → notifikáció 2. Edge case-ek: üres fájl, sérült MP3, duplikátum 3. Dokumentáció **Teljes becsült idő: ~5 nap** --- ## 8. Miért érdemes megcsinálni? 1. **Megszűnik a manuális pipeline vezénylés** — a podcast feldolgozás teljesen automatikus 2. **Én a tartalomra koncentrálok** — a workflow-t a harness viszi 3. **A wiki soha nem driftel** — a rebuild a pipeline része, nem utólagos korrekció 4. **Skálázható** — új podcast típus = új template, nem új kód 5. **Konceptuálisan tiszta** — nem hack, nem workaround. Az OpenClaw úgy lett tervezve hogy ilyen rétegeket lehessen rá építeni 6. **Demonstrálja az agentic AI valódi értékét** — pontosan azt a réteget építi meg amiről a Practical AI epizód beszélt: a modell commodity, a harness a lényeg