Replicord · Fabryka Junior Agentów

01 · Przegląd pipeline

6 etapów od słów do gotowego agenta

Każdy etap to osobny Junior Agent. Dane przepływają przez ctx — JSON mergowany po każdym kroku. Każdy agent dodaje własne klucze z prefiksem.

interpretacja-intencji

opis_potrzeby ← human

ii_cel_agenta ii_dane_wejsciowe ii_dane_wyjsciowe ii_typ_logiki ii_zewnetrzne_api ii_robocza_nazwa

OpenAI gpt-4o-mini

↓ ctx z ii_*

projektowanie-agenta

pa_nazwa_katalogu pa_nazwa_skryptu pa_display_name pa_opis pa_input_spec pa_output_spec pa_wymagania pa_settings_spec pa_logika_krok_po_kroku

OpenAI gpt-4o-mini

↓ ctx z ii_* + pa_* · agent wypisuje projekt na stderr (widoczny w UI)

zatwierdzenie-projektu

zatwierdz_projekt ← human (TAK/NIE)

zp_zatwierdzone: true sys.exit(1) przy NIE

Human confirm

↓ tylko gdy TAK

generowanie-kodu-agenta

gk_kod_skryptu gk_kod_manifestu gk_nazwa_katalogu gk_nazwa_skryptu

OpenAI gpt-4o

↓ surowy kod do walidacji

walidacja-agenta

wa_skladnia_ok wa_manifest_ok wa_has_main wa_has_stdin wa_bledy[] sys.exit(1) przy błędach krytycznych

Python · bez LLM

↓ zwalidowany kod

zapis-agenta

za_sciezka_katalogu za_sciezka_skryptu za_sciezka_manifestu za_zapisano: true

Python · zapis plików

Po etapie 06 serwer automatycznie wykrywa nowego agenta przy kolejnym GET /api/junior-agents — katalog junior-agents/ jest skanowany dynamicznie.

02 · Szczegóły etapów

Co robi każdy Junior Agent

Etap 01 — interpretacja-intencji

Cel

Zamienia nieformalny opis użytkownika na ustrukturyzowaną specyfikację: cel, wejścia, wyjścia, typ logiki, sugerowana nazwa katalogu. LLM wyciąga potrzebne informacje nawet z bardzo skrótowego opisu.

Input / Output

opis_potrzeby	humannieformalny opis co ma robić agent
ii_cel_agenta	stringjedno zdanie — cel agenta
ii_dane_wejsciowe	arraylista {nazwa, typ, zrodlo, opis}
ii_dane_wyjsciowe	arraylista {nazwa, typ, opis}
ii_typ_logiki	enumapi_call / scraping / obliczenia / llm / plik
ii_zewnetrzne_api	stringbiblioteki/API np. "requests" lub ""
ii_robocza_nazwa	stringkebab-case, max 40 znaków

Kluczowe szczegóły implementacji

Model i parametry gpt-4o-mini (domyślnie) lub gpt-4o przez settings
temperature=0.2 · response_format=json_object
Oczekuje dokładnie 6 kluczy — przy braku sys.exit(1)

System prompt Instruuje LLM by wyciągnął strukturę z opisu.
Akceptuje niepełne/nieformalne opisy.
Narzuca odpowiedź wyłącznie jako JSON.

Etap 02 — projektowanie-agenta

Cel

Na podstawie specyfikacji z etapu 1 projektuje pełną strukturę agenta: docelową nazwę, manifest draft z konkretnymi polami input/output (w formacie BC17), listę zależności pip oraz opis logiki krok po kroku. Wynik jest wejściem dla generatora kodu.

Ważne: agent wypisuje czytelne podsumowanie na stderr — użytkownik widzi ten log gdy etap 3 pyta o TAK/NIE.

Output — 9 kluczy pa_*

pa_nazwa_katalogu	kebab-case nazwa katalogu
pa_nazwa_skryptu	snake_case.py
pa_display_name	nazwa do UI
pa_opis	opis do manifest.json (3–4 zdania)
pa_input_spec	obiekt sekcji input
pa_output_spec	obiekt sekcji output
pa_wymagania	lista pakietów pip (bez stdlib)
pa_settings_spec	sekcja settings lub {}
pa_logika_krok_po_kroku	numerowane kroki implementacji

Etap 03 — zatwierdzenie-projektu

Cel

Minimalny agent — jedyna rola to zatrzymanie pipeline i zebranie decyzji TAK/NIE. Projekt do przeglądu widoczny jest w logach etapu 02 (stderr).

sys.exit(1) przy każdej odpowiedzi innej niż TAK / T / YES / Y. Pipeline zostaje oznaczony jako "error" i zatrzymany.

Implementacja

zatwierdzenie_projektu.py — fragment

odpowiedz = ctx.get('zatwierdz_projekt', '').strip().upper()
if not odpowiedz.startswith('TAK') \
        and odpowiedz not in ('T', 'YES', 'Y'):
    log("Pipeline anulowany przez użytkownika.")
    sys.exit(1)

Etap 04 — generowanie-kodu-agenta

Cel

Generuje gotowy do użycia kod — pełny skrypt Python i manifest.json. Używa gpt-4o (najlepsza jakość kodu).

System prompt łączy zawartość prompts/prompt_new_skill_generation.md z pełnymi konwencjami projektu BC17 (wzorzec main, NAZWA_AGENTA, PROJECT_ROOT, log(), zapisz_audyt()) oraz few-shot przykładem poprawnego skryptu.

Output / Walidacja po odbiorze

gk_kod_skryptu	pełny kod Python jako string
gk_kod_manifestu	pełny JSON manifestu jako string
gk_nazwa_katalogu	echo pa_nazwa_katalogu
gk_nazwa_skryptu	echo pa_nazwa_skryptu

✕json.loads(gk_kod_manifestu) musi przejść — przy błędzie sys.exit(1)
✕gk_kod_skryptu nie może być pusty — sys.exit(1)

Etap 05 — walidacja-agenta

Cel

Statyczna walidacja bez LLM — czyste Python. Sprawdza składnię i kontrakt BC17. Przy błędach krytycznych zatrzymuje pipeline zanim pliki trafią na dysk.

Sprawdzenia i decyzje

✕Krytyczne — sys.exit(1): błąd ast.parse(), brak def main(), brak sys.stdin.read(), nieparseowalny JSON manifestu
⚠Ostrzeżenia — kontynuuje: brak json.dumps na stdout, brak pola name/script w manifeście
✓Pozytywne: wa_skladnia_ok, wa_manifest_ok, wa_has_main, wa_has_stdin ustawione na True

Etap 06 — zapis-agenta

Cel

Tworzy katalog i zapisuje pliki na dysk. Po sukcesie nowy agent jest natychmiast dostępny w systemie — serwer skanuje katalog junior-agents/ dynamicznie przy każdym wywołaniu API.

Implementacja

zapis_agenta.py — fragment

katalog = os.path.join(PROJECT_ROOT, 'junior-agents', gk_nazwa)
if os.path.exists(katalog):
    log("OSTRZEŻENIE: katalog już istnieje")
os.makedirs(katalog, exist_ok=True)
with open(manifest_path, 'w', encoding='utf-8') as f:
    f.write(gk_kod_manifestu)
with open(skrypt_path, 'w', encoding='utf-8') as f:
    f.write(gk_kod_skryptu)

03 · Pliki do stworzenia

12 nowych plików + 2 modyfikacje

Każdy junior agent to para: manifest.json + skrypt Python. Plus modyfikacje plików data/ by zarejestrować Senior Agenta i klucze API.

interpretacja-intencji/manifest.json

LLM · gpt-4o-mini

interpretacja-intencji/interpretacja_intencji.py

OpenAI → 6 kluczy ii_*

projektowanie-agenta/manifest.json

LLM · gpt-4o-mini

projektowanie-agenta/projektowanie_agenta.py

OpenAI → 9 kluczy pa_*

zatwierdzenie-projektu/manifest.json

Human confirm

zatwierdzenie-projektu/zatwierdzenie_projektu.py

TAK/NIE → sys.exit(1) przy NIE

generowanie-kodu-agenta/manifest.json

LLM · gpt-4o

generowanie-kodu-agenta/generowanie_kodu_agenta.py

OpenAI → manifest.json + skrypt.py

walidacja-agenta/manifest.json

Python · bez LLM

walidacja-agenta/walidacja_agenta.py

ast.parse + JSON check → wa_*

zapis-agenta/manifest.json

Python · zapis plików

zapis-agenta/zapis_agenta.py

tworzy katalog + zapisuje pliki

Plus modyfikacje:

data/agents.json

dodanie Senior Agenta "Narodziny Junior Agenta"

data/junior-agent-settings.json

dodanie wpisów model + openai_api_key dla 3 nowych agentów LLM

04 · Ryzyka i mitygacje

Co może pójść nie tak

Zatwierdzenie bez podglądu projektu

Architektura BC17 zbiera pola source: "human" ZANIM skrypt etapu 3 cokolwiek wyświetli. Mitygacja: etap 02 musi wypisać na stderr sformatowane podsumowanie projektu — logi są widoczne w UI w momencie gdy etap 03 pyta o TAK/NIE.

JSON w JSON przy generowaniu kodu

LLM ma zwrócić JSON gdzie gk_kod_skryptu to wieloliniowy kod Python. Modele czasem gubią cudzysłowy. Mitygacja: response_format=json_object wymusza JSON + defensywny json.loads() + logowanie pierwszych 500 znaków przy błędzie.

Halucynacje kontraktu BC17

LLM może wygenerować kod który nie używa sys.stdin.read() lub pisze debug na stdout. Mitygacja: few-shot w system prompcie (wzorcowe 20 linii main()) + etap 05 wychwytuje te przypadki i blokuje zapis.

Nadpisywanie istniejącego agenta

Etap 06 z exist_ok=True cicho nadpisuje pliki. Mitygacja: logowanie ostrzeżenia gdy katalog istnieje; do rozszerzenia o suffix _v2.

Rozmiar ctx po etapie 04

Po etapie 04 ctx zawiera stringi z pełnym kodem (duże). Mitygacja: etap 04 buduje user message tylko z wybranymi kluczami pa_* i ii_* — nie wysyła całego ctx do LLM.

05 · Weryfikacja end-to-end

Jak przetestować po implementacji

Uruchom serwer: npm start — sprawdź że 6 nowych agentów widoczne w GET /api/junior-agents

Utwórz Senior Agenta "Narodziny Junior Agenta" przez UI lub przez POST /api/senior-agents z listą 6 agentów

Uruchom z testem: "Agent ma pobierać aktualny kurs EUR/PLN z API NBP i zwracać kurs jako string"

Sprawdź logi etapów 1–2 — powinny zawierać sformatowaną specyfikację: cel, wejścia, wyjścia, logika krok po kroku

Na etapie 3 wpisz TAK — pipeline kontynuuje do generowania

Poczekaj na etap 4 (generowanie ~15–30s dla gpt-4o) — sprawdź że etap 5 przeszedł bez błędów krytycznych

Etap 6 tworzy junior-agents/pobieranie-kursu-nbp/ (lub podobna nazwa) — sprawdź katalog na dysku

Odśwież GET /api/junior-agents — nowy agent powinien być widoczny w systemie natychmiast

Przetestuj nowy agent przez POST /api/junior-agents/{nazwa}/test — walidacja kontraktu stdin/stdout