Ako som za dva dni poskladal transparentného AI agenta pre OS Layer

Posledné dva dni som venoval novej generácii Agenta a Boardu pre OS Layer. Cieľ znel jednoducho: spustiť dlhšiu úlohu, nechať model pracovať vo viacerých krokoch, v správnom momente si vypýtať schválenie, vytvoriť výstupné súbory a na konci overiť, či bola úloha naozaj dokončená.

V praxi sa ukázalo, že medzi „model niečo napísal“ a „spoľahlivý agent dokončil úlohu“ je obrovský rozdiel.

Výsledkom je dnes Agent, ktorý plánuje, vykonáva kroky, čaká na signály, opravuje chyby a používa nezávislý modelový validator. Board pritom ukazuje presný prompt, provider requesty, tool cally, argumenty, výsledky a kompletné štatistiky.

A hlavne: už to nie je čierna skrinka.

Test, ktorý odhalil všetky slabé miesta

Ako integračný test som použil vyšetrovanie bezpečnostného incidentu.

Agent dostal pracovný adresár s logmi, konfiguráciami a bezpečnostnou politikou. Mal:

1. objaviť dôkazové súbory,

2. zostaviť časovú os,

3. porovnať dôkazy s bezpečnostnou politikou,

4. uložiť dôležité zistenia do durable memory,

5. zastaviť sa a počkať na presný signál APPROVE REMEDIATION,

6. vytvoriť incident report,

7. vytvoriť remediation plán,

8. oba súbory znovu prečítať a nezávisle overiť.

Na prvý pohľad ide o bežný agentový workflow. V skutočnosti postupne odhalil takmer každú triedu problému, ktorá sa pri lokálnych LLM môže objaviť.

Model preskakoval fázy, tvrdil, že vytvoril súbor, ktorý neexistoval, opakovane žiadal už udelené schválenie, vracal neplatné protokolové kombinácie a niekoľkokrát sa zacyklil pri oprave rovnakého JSON-u.

Každá z týchto chýb však ukázala, čo musí riadiť daemon a čo naopak môžeme nechať na modeli.

Durable Agent nesmie veriť modelovým tvrdeniam

Prvá dôležitá lekcia bola jednoduchá:

Text „súbor bol vytvorený“ nie je dôkaz, že súbor existuje.

Model dokázal vrátiť úspešné dokončenie a opísať oba výstupné artefakty, hoci jeden z nich fyzicky chýbal. Agent preto dostal deterministické completion assertions.

Pre každý očakávaný výstup dnes kontroluje minimálne:

• či súbor existuje,

• či ide o bežný súbor,

• či nie je prázdny,

• pri JSON-e, či sa dá parsovať,

• pri registrovanej schéme, či celý dokument vyhovuje kontraktu.

Model môže tvrdiť čokoľvek. Run sa označí ako dokončený až vtedy, keď prejde reálny stav súborového systému.

Kontrakty musia byť generické

Prvá implementácia validátora poznala konkrétnu schému remediation plánu priamo v Rust core. Vedela, že dokument musí obsahovať polia ako incident_severity, actions, reason, validation a rollback.

Fungovalo to, ale bola to zlá architektúra.

Agent nemá vedieť, či validuje incident report, release manifest, faktúru alebo výsledok vedeckého experimentu. Preto sa všetky doménové pravidlá presunuli do externého registra kontraktov.

agent/contracts/
├── os.incident.remediation.v1.schema.json
├── os.release.manifest.v1.schema.json
└── os.test.v1.schema.json

Core pozná iba všeobecný mechanizmus:

artifact path
→ nájdi contract podľa schema ID
→ načítaj reálny súbor
→ validuj
→ vráť presný zoznam porušení

Neznáma alebo poškodená schéma sa nesmie ticho považovať za úspech. Agent preto funguje fail-closed a skončí s chybou completion_contract_unavailable.

Deterministická validácia nestačí

Po zavedení kontraktov sa podarilo vytvoriť validný remediation plán. Incident report však obsahoval iba:

# Incident Report

## Executive Summary

This is a placeholder incident report.

Súbor existoval, nebol prázdny a technicky spĺňal základné file assertions.

Obsahovo bol úplne nepoužiteľný.

Tu sa osvedčil planner–worker–validator vzor. Deterministický verifier kontroluje tvrdé fakty. Nezávislý modelový validator kontroluje význam:

• či výstup spĺňa celý cieľ,

• či nejde o placeholder,

• či nechýbajú povinné časti,

• či tvrdenia odkazujú na dôkazy,

• či si jednotlivé artefakty neprotirečia,

• či worker iba nevyhlásil úspech bez reálnej práce.

Pipeline dnes vyzerá takto:

worker vytvorí kandidátny výsledok
        ↓
deterministické assertions
        ↓
semantic validator
        ↓
PASS → completed
FAIL → konkrétny repair krok pre workera
        ↓
nová deterministická a semantická kontrola

Validator môže byť vypnutý, advisory alebo required.

off
advisory
required

Pri lokálnych modeloch sa samozrejme môže pomýliť aj validator. Stále je však výrazne lepší než žiadna obsahová kontrola. Daemon navyše sleduje opakované identické verdikty a zabraňuje nekonečným repair slučkám.

Planner, worker a validator majú vlastné modely

Experimentovanie s lokálnymi modelmi vyžaduje možnosť konfigurovať každú rolu samostatne.

Agent preto rozlišuje:

• planner – voliteľný prvý plánovací turn,

• worker – vykonáva normálne a opravné kroky,

• validator – nezávisle hodnotí dokončenie.

Každá rola môže mať vlastný:

• profil,

• prompt,

• model,

• provider,

• endpoint,

• teplotu,

• seed,

• context size,

• prediction limit,

• tool režim,

• doplnkovú inštrukciu.

Napríklad planner môže bežať na menšom modeli bez toolov, worker na výkonnejšom modeli s lokálnymi nástrojmi a validator na modeli s nízkou teplotou.

Efektívna konfigurácia sa uloží do immutable run.created eventu. Každý experiment je preto reprodukovateľný aj po retry, páde daemonu alebo reštarte systému.

Lokálny model potrebuje čo najmenej balastu

Pri lokálnych LLM platí, že viac kontextu neznamená automaticky lepší výsledok.

Naopak, duplicitné pravidlá, dlhé vysvetlenia architektúry a opakované opisy nástrojov model často iba mätú.

Preto sa prompt skladá z minima potrebného pre konkrétnu rolu:

aktuálny goal
aktuálny durable step
relevantná história
relevantná memory
nové signály
completion state
presný výstupný protokol

Definície toolov sa do promptu vôbec nekopírujú.

Model ich dostáva cez štandardné provider API pole tools[], kde má každý nástroj meno, description a vstupnú JSON Schema. Rovnako funguje aj MCP: klient načíta nástroje cez tools/list a preloží ich do provider tool formátu.

Prompt preto nemusí hovoriť:

You have tools.
Use tools when necessary.
Do not invent tool results.

Tool registry je jediný autoritatívny zdroj toho, čo má model dostupné.

Lokálne tools, MCP alebo nič

Pri ladení vlastných tool descriptions a argument schemas nechcem, aby výsledok ovplyvňovali desiatky cudzích MCP nástrojov.

Vznikli preto štyri tool-source režimy:

default       lokálne OS Layer tools + MCP
--no-mcp      iba lokálne OS Layer tools
--only-mcp    iba MCP tools
--no-tools    žiadne tools

Agent režim uloží do Run konfigurácie a propaguje ho pri každom turne. Retry ani reštart daemonu ho nezmenia.

Pri --no-mcp presne viem, že ladím iba svoj prompt, svoj model a svoje tool schémy.

CWD musí byť skutočný pracovný adresár

Ďalší zásadný problém sa objavil pri zápise súborov.

Model zavolal:

{
  "path": "INCIDENT_REPORT.md",
  "content": "..."
}

V approval obrazovke bol obsah viditeľný, ale súbor sa neobjavil v Agent work directory.

Príčina bola v tom, že AI proces bežal v správnom adresári, no tool sa vykonával cez Runtime daemon vo vlastnom cwd.

Správne pravidlo je dnes jednoznačné:

cd ~/projekt
ai "vytvor report.md"

Relatívna cesta report.md znamená:

~/projekt/report.md

Pri Agentovi sa AI spustí v agent.work_dir, takže všetky relatívne tool cesty smerujú do workspace konkrétneho Runu.

Model nemusí mať cwd natlačené v prompte. Keď ho potrebuje poznať, môže zavolať bežný pwd alebo cwd tool.

Execution context však musí preniesť pracovný adresár až k reálne vykonávanému procesu nástroja.

Bez full debug režimu sa agent nedá vyvíjať

Najväčšou zmenou Boardu nie je nový panel ani farba hlavičky. Je to odstránenie čiernej skrinky medzi promptom a modelom.

Board dnes ukazuje presne:

• čo dostal model v messages,

• ktoré tools dostal v API tools[],

• aký model a options boli použité,

• čo provider vrátil,

• ktorý tool model zavolal,

• aké raw argumenty vygeneroval,

• aký výsledok toolu dostal späť,

• ako reagoval v ďalšom provider rounde.

Jeden Agent turn môže obsahovať viac provider requestov:

round 0 → model zavolá read_file
round 1 → dostane výsledok a zavolá write_file
round 2 → dostane výsledok a vráti AgentTurn

Pri označení model_tool_call preto Board okamžite ukáže detail:

Tool       write_file
Call ID    call_...
Round      1

Raw arguments
{"path":"INCIDENT_REPORT.md","content":"..."}

Parsed arguments
path     INCIDENT_REPORT.md
content  ...

Runtime transformácia zostáva dostupná, ale pre tuning je primárne to, čo skutočne vytvoril model.

Kompletné metriky

Board priebežne počíta štatistiky jednotlivých provider roundov, AI turnov aj celého Agent Runu.

Viditeľné sú napríklad:

• TTFT,

• prompt tokens,

• output tokens,

• total tokens,

• provider time,

• tool time,

• tokens za sekundu,

• počet provider roundov,

• počet tool callov,

• počet retry a repair udalostí,

• spotrebovaný Agent turn budget,

• metriky podľa roly a modelu.

Priemer tokens/s sa počíta vážene z reálne generovaných tokenov a generation time, nie ako obyčajný priemer čiastkových rýchlostí.

Full debug nie je luxusná funkcia. Pri vývoji LLM orchestration je to základná požiadavka.

Výsledok

Po odstránení problémov Agent dokončil celý incident workflow na prvý pokus.

Vytvoril plný incident report s časovou osou, potvrdenými a odvodenými zisteniami, bezpečnostnými porušeniami, root cause, exposure assessmentom a odkazmi na dôkazové súbory.

Zároveň vytvoril validný remediation plán s objednanými akciami, prioritou, dôvodom, validáciou a rollbackom.

Najväčší rozdiel však nie je v samotných súboroch.

Rozdiel je v tom, že dnes viem presne povedať:

• čo model dostal,

• čo si vybral,

• čo zavolal,

• s akými argumentmi,

• čo tool reálne vykonal,

• aký výsledok sa vrátil,

• prečo validator výsledok prijal alebo odmietol,

• koľko tokenov, času a repair pokusov celý proces spotreboval.

Z experimentu sa stal laditeľný systém.

Aktuálny stav

Po dvoch dňoch práce vznikli:

AI 1.45
Agent 0.11
Board 1.07

AI poskytuje presný model-facing debug a správne vykonávanie toolov v cwd.

Agent poskytuje durable kroky, signály, checkpointy, generické kontrakty, planner–worker–validator role a ochranu pred repair slučkami.

Board poskytuje úplnú viditeľnosť do promptov, provider requestov, modelových tool callov, výsledkov a metrík.

Nie je to koniec vývoja. Teraz však už ďalšie problémy nebudem riešiť naslepo.

A to je pri agentových systémoch pravdepodobne najdôležitejší míľnik.