9 Agent AI ze skillem tok

Po spotkaniu: skonfigurujesz agenta AI w terminalu z pakietem tok-agent · zrecenzujesz model tok wygenerowany przez agenta, opierając się na opisie procesu · udokumentujesz pracę z agentem zgodnie z zasadami UJ · Czas: Nauka 35 min, Wyzwanie 55 min

9.1 Nauka

Agent, skill i instrukcje: przypomnienie

Na kursie „Modelowanie procesów informacyjnych” poznałeś agenta AI pracującego w terminalu (rozdział 10). Przypomnijmy trzy pojęcia:

  • Agent to model językowy, który nie tylko odpowiada, ale też działa: czyta i zapisuje pliki, uruchamia polecenia, ogląda ich wynik i na tej podstawie planuje kolejny krok.
  • Skill to folder z wiedzą o tym, jak wykonać określony rodzaj zadania: plik SKILL.md z instrukcją oraz materiały pomocnicze. Agent wczytuje skill, gdy zadanie pasuje do jego opisu.
  • AGENTS.md to stałe zasady pracy w danym folderze, które agent czyta na początku każdej sesji.

W laboratorium BPMN agent pisał plik XML, a skrypt bpmn.py sprawdzał go i rysował diagram. Dziś agent pisze model w tok, a sprawdza go narzędzie tok. Podział pracy jest taki sam: agent odpowiada za znaczenie, narzędzie za mechanikę, a Ty za ocenę.

Dlaczego tok ułatwia pracę agentowi

Język tok projektowano z myślą o dwóch rodzajach autorów: ludziach i agentach. Te same cechy pomagają obu:

Cecha tok Co daje agentowi Co daje Tobie
jeden wiersz, jeden element błąd dotyczy jednego wiersza; poprawka zmienia jeden wiersz recenzujesz model wiersz po wierszu, jak tekst
jawne identyfikatory odwołania nie „wiszą”; tok check wskazuje brakujący identyfikator w mapowaniu i recenzji odwołujesz się do identyfikatorów
cały język na kilku stronach ściągawka mieści się w kontekście agenta ta sama ściągawka jest w dodatku A
komunikaty z kodem i numerem wiersza, --json agent czyta wynik bez zgadywania rozumiesz, co agent poprawiał i dlaczego
forma kanoniczna (tok fmt) zawsze ten sam układ tekstu różnice między wersjami są małe i czytelne
brak współrzędnych agent nie musi niczego rysować diagram powstaje zawsze tak samo

Porównaj objętość: model „Wniosek o szkolenie” z laboratorium BPMN miał w XML kilkaset wierszy. Model o podobnej wielkości w tok ma ich kilkadziesiąt, a każdy jest czytelny dla człowieka. Recenzja staje się czytaniem tekstu, a nie klikaniem w elementy diagramu.

Pakiet tok-agent

Na zajęcia pobierasz pakiet:

Pobierz pakiet tok-agent (.zip)

Plik Do czego służy
AGENTS.md zasady pracy agenta w tym folderze: język polski, tylko pliki .tok, mapowanie przed modelem, rejestr poleceń
.github/skills/tok-modelowanie/SKILL.md przebieg pracy: mapowanie → model → tok check → tok fmt → widoki; tabela słów-wskazówek; najczęstsze błędy
references/sciagawka.md, komunikaty.md, spec.md ściągawka języka, lista komunikatów, pełna specyfikacja
rozgrzewka.md mały proces na pierwsze uruchomienie
proces.md proces laboratorium: „Zgłoszenie naruszenia praw autorskich w repozytorium uczelnianym”
PROMPT.md gotowe polecenie dla agenta
recenzja.md formularz Twojej recenzji z oświadczeniem o użyciu SI

Otwórz SKILL.md i przeczytaj go, zanim uruchomisz agenta. Zobaczysz w nim dokładnie to, czego agent się „uczy”: kolejność pracy, zasady nazewnictwa i tabelę wskazówek. Skill jest zwykłym tekstem. Możesz go poprawiać i rozwijać. To ważna umiejętność: kto potrafi napisać dobry skill, ten przekazuje agentowi wiedzę swojej instytucji.

Pętla pracy agenta

Agent pracuje w pętli, którą widać w historii sesji:

  1. czyta proces.md i tworzy mapowanie.md;
  2. pisze zgloszenie.tok;
  3. uruchamia tok check --json i czyta komunikaty;
  4. poprawia wiersze wskazane w komunikatach i wraca do kroku 3, aż nie będzie błędów;
  5. uruchamia tok fmt -w, tok bpmn i tok svg.

Śledź tę pętlę. Komunikaty, które agent dostawał po drodze, mówią dużo o tym, co sprawiło mu trudność. Błąd R002 (nieznany identyfikator) to zwykle literówka. Błąd E008 (przepływ komunikatów wewnątrz basenu) oznacza, że agent pomylił linię z basenem. To jest już błąd w rozumieniu procesu, a nie w zapisie.

Jak recenzować model tok

Recenzja odpowiada na jedno pytanie: czy model mówi to samo co opis? tok check sprawdza notację, ale nie zna opisu. Rekomendowany przebieg recenzji ma cztery przejścia:

  1. Uczestnicy i role. Czy baseny i linie odpowiadają opisowi? Czy Zgłaszający i Autor są basenami zamkniętymi (pool bez bloku)? Czy każdy element jest w linii tej roli, która wykonuje krok?
  2. Rodzaje elementów. Dla każdego kroku porównaj słowo kluczowe (user, service, manual, rule, send…) ze wskazówkami w opisie. Pomaga tabela poniżej.
  3. Przebieg. Przejdź wiersze flow od startu do każdego końca. Czy bramki rozdzielające i złączające są tego samego rodzaju? Czy pętla „uzupełnienie → ponowna ocena” wraca we właściwe miejsce?
  4. Wyjątki i komunikaty. Czy zdarzenia graniczne są na właściwych czynnościach i mają właściwy rodzaj (przerywające czy noninterrupting)? Czy każda wiadomość z opisu ma wiersz message?
Słowa w opisie Instrukcja tok
„w swojej skrzynce zadań w systemie” user
„system samodzielnie, bez udziału człowieka”, „automatycznie” service
„twarzą w twarz”, „na papierowej notatce”, „nie jest odnotowywany w systemie” manual
„wyłącznie według tabeli reguł”, „nikt nie ocenia wyniku” rule
„zadanie nadal zostaje u niego, ale jednocześnie…” boundary … noninterrupting
„jeśli system zgłosi błąd, czynność zostaje przerwana” boundary … error="…"
„co nastąpi pierwsze” eventgw i po nim catch
„obie czynności zawsze, niezależnie od siebie” and
„w dowolnym momencie trwania procesu”, „ta część nie ma poprzednika” eventsub

Ta tabela to tylko pomoc. Każdą ocenę uzasadniasz słowami z proces.md, a nie samą tabelą.

Precyzyjne polecenie poprawki

Gdy znajdziesz błąd, możesz poprawić plik .tok sam albo poprosić agenta. Dobre polecenie poprawki wskazuje krok, co jest źle, co powinno być i dlaczego, czyli podaje słowa z opisu:

Krok 9 powinien być zadaniem ręcznym (manual), a nie user, bo opis mówi
„rozmowa twarzą w twarz” i „nie jest odnotowywany w systemie”.
Popraw zgloszenie.tok, uruchom tok check, tok fmt -w i tok svg.

Unikaj poleceń ogólnych typu „popraw model”. Agent poprawi wtedy to, co sam uzna za błąd, a to nie musi być to, co znalazłeś w recenzji.

Dokumentowanie pracy z agentem

Zarządzenie nr 115 Rektora UJ z 27 listopada 2025 r. wymaga, by student świadomie i odpowiedzialnie korzystał z narzędzi sztucznej inteligencji i wyraźnie oznaczał treści przez nie wygenerowane, np. przez dołączenie poleceń. W tym kursie oznacza to trzy pliki:

  • prompty.md: agent dopisuje do niego dosłownie każde Twoje polecenie (tak każe mu AGENTS.md); sprawdź po sesji, czy rejestr jest kompletny;
  • mapowanie.md: decyzje agenta z uzasadnieniem;
  • oświadczenie w recenzja.md: co wygenerował agent, co poprawiłeś Ty, co napisałeś samodzielnie.

Recenzję i odpowiedzi na pytania piszesz sam. To one pokazują, czy rozumiesz proces i notację.

9.2 Wyzwanie

Polecenie: skonfiguruj agenta z pakietem tok-agent, wygeneruj model procesu „Zgłoszenie naruszenia praw autorskich w repozytorium uczelnianym”, zrecenzuj go i popraw.

Kroki:

  1. Rozpakuj pakiet, uruchom agenta w folderze tok-agent, sprawdź /skills list i wybierz model (/model).
  2. Wykonaj rozgrzewkę z rozgrzewka.md. Sprawdź wynik samodzielnie poleceniem tok check.
  3. Wklej polecenie z PROMPT.md. Obserwuj pętlę pracy agenta i zanotuj komunikaty tok check, które się pojawiły.
  4. Wypełnij recenzja.md w czterech przejściach z części Nauka. Popraw błędy precyzyjnymi poleceniami albo ręcznie.
  5. Odpowiedz na pytania podsumowujące i wypełnij oświadczenie.

Rezultat: pliki zgloszenie.tok, zgloszenie.bpmn, zgloszenie.svg, mapowanie.md, recenzja.md i prompty.md. tok check zgloszenie.tok nie zgłasza błędów.

Praca: indywidualnie.

Czas: 55 minut. Recenzję dokończ przed terminem zadania Z3.

Zadanie Z3. Model opracowany z agentem AI i jego recenzja (15%). Oddajesz model tok z eksportem, mapowanie agenta, swoją recenzję z oświadczeniem o użyciu SI i rejestr poleceń. Oceniana jest przede wszystkim recenzja: trafność ocen, uzasadnienia słowami z opisu i jakość poprawek. Pełne polecenie i kryteria są w dodatku C.

Na co zwrócić uwagę

  • Agent może się mylić w sposób przekonujący. Model bez błędów w tok check i z ładnym rysunkiem nadal może mieć złe rodzaje zadań albo zły rodzaj zdarzenia granicznego.
  • Krok 3 i krok 6 mają zdarzenia graniczne o różnym znaczeniu. Sprawdź oba szczególnie uważnie.
  • Jeśli wyczerpiesz limit zapytań planu Copilot, dokończ poprawki ręcznie w pliku .tok. Wpisz to w recenzji.
  • Nie wpisuj do poleceń danych prawdziwych osób. W procesie występują wyłącznie role.

9.3 Pytania sprawdzające

  1. Jak dzielą się zadania między agenta, narzędzie tok i Ciebie w tym laboratorium?
  2. Które cechy języka tok ułatwiają pracę agentowi, a które recenzję człowiekowi? Podaj po dwie.
  3. Czym różni się błąd zapisu od błędu odczytania opisu? Podaj przykład kodu komunikatu dla każdego.
  4. Jak wygląda precyzyjne polecenie poprawki? Napisz jedno dla wybranego kroku laboratorium.
  5. Jakie trzy pliki dokumentują pracę z agentem i czego wymaga w tej sprawie Zarządzenie nr 115 Rektora UJ?