Wzorzec Nadzorcy (Hierarchiczny Multi-Agent)

1. Przegląd koncepcji i problem systemowy

Tworząc systemy wieloagentowe, programiści często napotykają na trudności związane z koordynacją. Jeśli agenci po prostu wysyłają wiadomości do wspólnego wątku rozmowy (Group Chat):

• Utrata celu: Agenci zaczynają komentować wypowiedzi kolegów, zapominając o pierwotnym zapytaniu użytkownika.
• Niekontrolowany wzrost kontekstu: Każdy agent widzi pełny log wiadomości wszystkich pozostałych agentów, co prowadzi do kwadratowego zużycia tokenów oraz degradacji uwagi modelu.
• Brak determinizmu: Nie można zagwarantować, że zadanie zostało faktycznie rozwiązane, a nie jedynie „zagłuszone” w szumie informacyjnym.

Supervisor Pattern wprowadza klasyczną hierarchię inżynierską: centralny orkiestrator (Supervisor) interaguje z użytkownikiem, buduje plan wykonania, dzieli go na izolowane taski, przypisuje je docelowym agentom (Specialist Workers) i agreguje finalny wynik.

2. Taksonomia architektoniczna i model mentalny

                       ┌─────────────────────────┐
                       │       USER PROMPT       │
                       └────────────┬────────────┘
                                    │
                                    ▼
                       ┌─────────────────────────┐
                       │    SUPERVISOR AGENT     │
                       │  (State, Plan & Router) │
                       └───┬────────┬────────┬───┘
                           │        │        │
           ┌───────────────┘        │        └───────────────┐
           │ Task A                 │ Task B                 │ Task C
           ▼                        ▼                        ▼
┌────────────────────┐   ┌────────────────────┐   ┌────────────────────┐
│   RESEARCH AGENT   │   │    CODER AGENT     │   │     QA AGENT       │
│ (Search, Docs, RAG)│   │ (AST, Git, Patch)  │   │(Evals, Tests, Lint)│
└──────────┬─────────┘   └──────────┬─────────┘   └──────────┬─────────┘
           │                        │                        │
           └───────────────┐        │        ┌───────────────┘
                           ▼        ▼        ▼
                       ┌─────────────────────────┐
                       │   AGGREGATED ARTIFACT   │
                       └─────────────────────────┘

1. State Machine / Router: Supervisor zawiera skończony automat stanów. Po każdym kroku ocenia sytuację: Czy zakończone? -> Zwróć odpowiedź użytkownikowi, lub Czy potrzebny kolejny krok? -> Wywołaj odpowiedniego workera.
2. Task Encapsulation: Każdy worker otrzymuje wyłącznie niezbędne dane wejściowe oraz własny zestaw narzędzi (Tooling Scope). Na przykład Coder Agent nie ma dostępu do wyszukiwania w Google, a Research Agent nie ma uprawnień do modyfikacji systemu plików.

3. Techniczny pipeline i mechanika wewnętrzna

Algorytm działania supervisora:

1. Analiza zadania wejściowego: Model supervisora jest wywoływany z systemowym promptem opisującym kompetencje każdego workera oraz schematem zwracanych decyzji (Function Calling / Structured Output).
2. Generacja decyzji routingu:

   {
     "next_worker": "coder_agent",
     "task_description": "Implement authentication middleware in src/auth.ts using Better Auth",
     "expected_artifacts": ["src/auth.ts"]
   }
   

3. Izolowane uruchomienie workera: Orkiestrator inicjalizuje kontekst workera, uruchamia jego autonomiczną pętlę i oczekuje na zwrot wyniku.
4. Kontrola jakości (Evaluation Gate): Po otrzymaniu wyniku supervisor może go zatwierdzić, przekazać do QA-agenta w celu przetestowania lub odesłać z powrotem do workera w celu poprawek (Self-Correction Loop).

4. Praktyczne scenariusze inżynierskie w środowisku produkcyjnym

01. Autonomiczne tworzenie złożonej funkcjonalności

Użytkownik prosi: „Dodaj do projektu eksport raportów do PDF z wykresami”. Supervisor wywołuje kolejno:

1. Research Worker – znajduje odpowiednią bibliotekę, sprawdza licencję.
2. Backend Worker – tworzy API endpoint oraz generator raportu.
3. Frontend Worker – dodaje przycisk w UI oraz wskaźnik ładowania.
4. Tester Worker – uruchamia testy Playwright.

02. Triaż i usuwanie incydentów bezpieczeństwa

Supervisor reaguje na alert w Sentry, przekazuje stack-trace agentowi diagnostycznemu, waliduje zaproponowany hotfix przez agenta testującego i tworzy pull request.

5. Pułapki, typowe błędy i aspekty bezpieczeństwa

• Deadlock Loops (Zapętlenie między supervisorem a workerem): Supervisor uznaje, że zadanie nie zostało w pełni rozwiązane, i odsyła je z powrotem do workera. Worker zwraca ten sam kod. Rozwiązanie: ustawienie max_iterations = 5 wraz ze zgłoszeniem błędu człowiekowi.
• Context Bleed (Zanieczyszczenie pamięci supervisora): Jeśli worker zwraca surowe, obszerne dane (np. cały kod), pamięć supervisora szybko się przepełnia. Workery powinny zapisywać wyniki w systemie plików lub bazie danych, zwracając supervisorowi jedynie krótkie podsumowanie lub ścieżkę do artefaktu.
• Single Point of Failure: Awaria lub błąd logiczny w module supervisora paraliżuje cały system. Należy przewidzieć mechanizmy fallbackowe oraz szczegółowe logowanie decyzji routingowych dla celów debugowania.