Multi-Agent

Dlaczego Multi-Agent?#

Problem: Jeden agent, wiele ról#

code
Kopiuj
Jeden agent który musi:
- Planować
- Pisać kod
- Testować
- Reviewować
- Dokumentować

→ Konflikt ról, context bloat, suboptymalne wyniki

Rozwiązanie: Specjalizacja#

code
Kopiuj
Agent 1 (Planner): Rozbija task na kroki
Agent 2 (Coder): Implementuje
Agent 3 (Reviewer): Code review
Agent 4 (Tester): Pisze i uruchamia testy

Wzorce Multi-Agent#

1. Pipeline#

code
Kopiuj
[Planner] → [Coder] → [Reviewer] → [Tester]
    ↓           ↓           ↓           ↓
  Plan       Code       Review      Tests

Liniowy przepływ, każdy agent przekazuje output dalej.

2. Hierarchiczny#

code
Kopiuj
           [Orchestrator]
          /      |       \
    [Agent A] [Agent B] [Agent C]

Orchestrator deleguje i agreguje wyniki.

3. Peer Review#

code
Kopiuj
    [Agent 1] ←→ [Agent 2]
         ↓           ↓
      Output 1   Output 2
         ↓           ↓
       [Aggregator]

Agenci recenzują nawzajem swoją pracę.

4. Debate#

code
Kopiuj
[Proponent] ←→ [Opponent]
      ↓
   [Judge]

Agenci argumentują za/przeciw, trzeci ocenia.

Koszt koordynacji — rachunek, którego nikt nie pokazuje#

Każde przekazanie pracy między agentami kosztuje trzykrotnie:

1. •Utrata kontekstu — agent B nie widział rozmowy agenta A. Dostaje streszczenie, a streszczenie zawsze coś gubi. Im subtelniejsze zadanie, tym więcej ginie w przekazaniu.
2. •Ryzyko niespójności — dwóch agentów podejmie dwie różne mikro-decyzje w tym samym stylu pracy. Osobno obie dobre, razem — szew, który ty musisz wygładzić.
3. •Twoja uwaga na łączeniu — wyniki trzeba scalić, sprzeczności rozstrzygnąć, całość odebrać. Koordynacja to praca, i to twoja.

Zasada: Dziel pracę, gdy zadania są od siebie niezależne i mają jasny interfejs. Nie dziel, gdy zadanie wymaga jednej spójnej wizji.

Kiedy jeden agent > zespół#

• •Zadanie mieści się w jednym kontekście i jednej sesji — dzielenie dodaje koszt, nie wartość.
• •Wynik ma mieć jeden głos: tekst, architektura, decyzja. Sklejka z trzech agentów zawsze brzmi jak sklejka.
• •Nie umiesz opisać interfejsu między częściami — to znak, że sam jeszcze nie rozumiesz podziału. Najpierw zrozum, potem dziel.

Kiedy zespół wygrywa#

• •Części są naprawdę niezależne: osobne pliki, osobne dokumenty, osobne pytania badawcze.
• •Potrzebujesz świeżego spojrzenia: agent-recenzent bez kontekstu autora widzi to, czego autor nie zobaczy — świeży kontekst to cecha, nie wada.
• •Skala: 40 plików do tej samej transformacji — koordynacja jest trywialna (identyczne zlecenie), a równoległość realna.

Minimalna implementacja#

Zanim sięgniesz po framework — najprostszy orkiestrator to funkcja, która woła agenta z rolą:

python
Kopiuj
import anthropic

client = anthropic.Anthropic()

def call_agent(role: str, task: str) -> str:
    response = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=16000,
        system=f"Jesteś {role}.",
        messages=[{"role": "user", "content": task}],
    )
    # pierwszym blokiem bywa thinking — bierzesz tylko bloki tekstowe
    return "".join(b.text for b in response.content if b.type == "text")

plan = call_agent("architektem — projektujesz, nie kodujesz", f"Zaplanuj: {task}")
code = call_agent("wykonawcą — trzymasz się planu", f"Plan:\n{plan}\n\nZaimplementuj.")
review = call_agent("recenzentem — szukasz błędów", f"Kod:\n{code}\n\nZrecenzuj.")

Reszta — komunikaty strukturalne, współdzielony stan, wybór modelu per rola — to inżynieria, którą znajdziesz w dokumentacji (link w zasobach). Zasada pozostaje: rolę definiuje zlecenie i kontekst, nie framework. W praktyce codziennej multi-agent to najczęściej nie kod, tylko osobne sesje Claude Code z jasnymi rolami.

Z życia: designer buduje pierwszy produkt#

Tomek, designer bez doświadczenia programistycznego. Pomysł: aplikacja do śledzenia nawyków z AI coachem. Zero kodu w życiu, pierwszy projekt z Claude Code.

Etap 1: Architektura#

Tomek NIE zaczął od "zbuduj mi aplikację". Zaczął od rozmowy:

code
Kopiuj
Tomek: "Chcę zbudować habit tracker z AI coachem.
        Użytkownicy logują nawyki, AI daje feedback i sugestie.
        Potrzebuję: web app, baza danych, prosty AI chat.
        Jestem designerem bez doświadczenia w kodzie."

Claude (jako Architect): "Proponuję najlżejszy stack:
- Next.js (jeden framework = frontend + backend)
- SQLite z Drizzle (zero konfiguracji bazy danych)
- Claude API dla coachingu
Zacznijmy od schematu danych..."

Kluczowe: Claude jako Architect — najpierw projektował, potem kodował. Tomek weryfikował logikę, nie kod.

Etap 2: Funkcja po funkcji#

Tu Tomek odkrył multi-agent pattern intuicyjnie:

code
Kopiuj
Sesja 1 (Claude Code): "Zbuduj ekran logowania nawyku"
Sesja 2 (Claude Code): "Dodaj streak tracking"  
Sesja 3 (Claude Chat): "Napisz system prompt dla AI coacha
                         który motywuje bez bycia nachalnym"
Sesja 4 (Claude Code): "Zintegruj coaching z danymi nawyków"

Każda sesja = nowy agent z czystym kontekstem i jasnym zadaniem.

Etap 3: Testy, deploy, porażki#

code
Kopiuj
Tomek: "Zdeploy to na Vercel"

Claude: [konfiguruje, deploy, pierwszy test]
"Deploy przeszedł ale mamy problem: SQLite
 nie działa na serverless. Musimy przenieść
 bazę do Turso (hosted SQLite)."

Czego AI NIE umiało:

• •Decyzje produktowe — Tomek musiał sam zdecydować: ile nawyków max? Darmowy czy freemium?
• •Design — AI generowało "bezpieczny" UI. Tomek robił design w Figma, AI implementowało
• •Testowanie UX — AI nie widzi czy flow jest intuicyjny. Tomek testował z 3 znajomymi

Co Tomek zrobiłby inaczej:

1. •Zacząłby od hosted bazy (nie SQLite) — uniknąłby migracji na etapie deployu
2. •Pisałby CLAUDE.md od pierwszego dnia — za dużo powtarzał kontekst
3. •Używałby osobnych sesji od początku zamiast jednej mega-sesji na starcie

Cenna wiedza: Tomek nie zbudował "aplikacji wygenerowanej przez AI". Zbudował swój produkt, używając AI jako wyspecjalizowanych partnerów: architekta, kodera, copywritera. Multi-agent nie musi być kodem — to mentalny model podziału zadań.

Równoległość w praktyce#

Najczęstszy zysk z wielu agentów to nie „zespół specjalistów", tylko zwykła równoległość niezależnych zadań:

• •Kilka sesji naraz. Trzy osobne sesje Claude Code (albo trzy zadania w Cowork), każda z własnym zleceniem. Przy kodzie — każda na osobnej gałęzi albo w osobnym worktree, żeby nie edytowały tych samych plików.
• •Subagenci. W Claude Code główna sesja może zlecić podzadanie subagentowi, który pracuje we własnym kontekście i oddaje tylko wynik — research nie zaśmieca głównej sesji.
• •Recenzent ze świeżym spojrzeniem. Druga sesja dostaje sam wynik, bez historii autora, i szuka błędów. Często to jedyny „drugi agent", który się opłaca.

Przykład bez kodu:

code
Kopiuj
Trzy niezależne pytania badawcze do jednego raportu:
  A: „Jak konkurencja wycenia usługę X?"
  B: „Jakie są wymogi prawne dla X w Polsce?"
  C: „Co mówią recenzje klientów o X?"
→ trzy osobne zadania naraz, każde z kryterium „każda teza ma źródło"
→ scalasz TY: jeden spójny wniosek, nie sklejka trzech tekstów

Rachunek, który robisz przed podziałem: czy części są naprawdę niezależne i czy scalanie jest tanie? Jeśli wynik ma mieć jeden głos (spójny dokument, jedna architektura) — scalanie zje zysk.

Czego NIE robić z multi-agent#

❌ Agent na wszystko#

code
Kopiuj
Jeden mega-prompt: "Jesteś plannerem, coderem,
testerem i reviewerem jednocześnie"
→ Konflikt ról, niespójne zachowanie.
   Lepiej: osobne sesje, jasne role.

❌ Za dużo agentów#

code
Kopiuj
8 agentów dla prostego CRUDa.
→ Overhead komunikacji > wartość specjalizacji.
   Zacznij od 2-3 agentów, dodawaj gdy potrzeba.

❌ Brak shared context#

code
Kopiuj
Agent 2 nie wie co zrobił Agent 1.
Duplikuje pracę, tworzy sprzeczności.
→ README, CLAUDE.md, git log — agenci muszą "widzieć" co było.