Dlaczego jeden agent nie wystarczy

Pojedynczy agent ma fundamentalne ograniczenia — i warto je rozumieć, bo wprost wynikają z architektury modeli językowych.

Pierwsze jest okno kontekstowe. 200k lub 1M tokenów w czasie jednego wywołania brzmi jak dużo, ale eksploracja nietrywialnego codebase'u — grep po kilkudziesięciu plikach, czytanie wyników, śledzenie zależności — może pochłonąć połowę dostępnej przestrzeni. Gdy kontekst zostaje skompaktowany, agent traci szczegóły. Jeśli jednocześnie musi implementować, zostaje mu mało miejsca na faktyczną pracę.

Drugie to kwestia skupienia. Agent, który równocześnie eksploruje, planuje i pisze kod, gubi się — nie dlatego, że jest nieudolny, ale dlatego, że każda zmiana trybu pracy (od czytania pliku do edycji, od analizy do generowania testów) kosztuje. Model traci wątek. Wyspecjalizowany subagent robi jedno i robi to dobrze.

Trzeci problem to czas. Sekwencyjne wykonywanie niezależnych zadań trwa. Jeśli agent ma zbadać trzy niezależne moduły, robi to jeden po drugim. Trzy subagenci wykonają to samo zadanie równolegle.

Jest wreszcie bezpieczeństwo. Subagent działający w worktree pracuje na izolowanej kopii repozytorium. Jeśli coś pójdzie nie tak — eksperyment, zepsuta refaktoryzacja, błędna migracja — main branch pozostaje nienaruszony. Rollback sprowadza się do usunięcia worktree.

Agent tool — mechanizm delegacji

W Claude Code mechanizm multi-agent to narzędzie Agent. Agent główny (parent) uruchamia subagenta (child) przez wywołanie:

Agent(
  description: "Zbadaj moduł autoryzacji",
  prompt: "Przeanalizuj app/auth/ — jak działa flow logowania,
           jakie middleware'y są używane, gdzie jest walidacja JWT.
           Raport w 200 słowach.",
  subagent_type: "Explore"
)

Wywołanie przyjmuje kilka parametrów:

Niezależnie od parametrów, subagent zawsze działa w izolacji: pracuje we własnym kontekście i nie modyfikuje kontekstu rodzica. Zwraca wynik jako tekst — parent dostaje podsumowanie, nie surowe dane narzędzi.

Typy subagentów

Claude Code oferuje trzy wyspecjalizowane typy subagentów. Różnią się dostępem do narzędzi i przeznaczeniem:

Przykłady wywołań

Explore — szybka eksploracja lub głęboka analiza. W prompcie warto podać poziom dokładności: quick (1–2 zapytania), medium (kilka plików) lub very thorough (pełna analiza, wiele lokalizacji).

Agent(
  subagent_type: "Explore",
  description: "Znajdź użycia deprecated API",
  prompt: "Przeszukaj codebase pod kątem wywołań
           api.legacy_endpoint(). Podaj ścieżki plików
           i numery linii. Bądź very thorough."
)

Plan — analiza kodu i projekt strategii implementacji krok po kroku.

Agent(
  subagent_type: "Plan",
  description: "Zaplanuj migrację z REST na GraphQL",
  prompt: "Przeanalizuj app/api/ i zaplanuj migrację
           z REST na GraphQL. Uwzględnij: które endpointy
           mają być GraphQL, które zostaną REST,
           strategię migracji (big bang vs incremental),
           wpływ na frontend."
)

General-purpose — zadania wymagające faktycznej edycji plików.

Agent(
  subagent_type: "general-purpose",
  description: "Napisz testy dla modułu auth",
  prompt: "Napisz testy jednostkowe dla app/auth/middleware.py.
           Użyj pytest. Pokryj: valid JWT, expired JWT,
           missing token, invalid signature.
           Zapisz w tests/auth/test_middleware.py."
)

Worktree isolation

Subagenci mogą pracować w worktree — izolowanej kopii repozytorium git:

Agent(
  description: "Zrefaktoruj moduł payments",
  prompt: "...",
  isolation: "worktree"
)

Worktree to osobny katalog roboczy z własnym branchem, współdzielący historię gita z głównym repo. Subagent w worktree:

• Ma własną kopię plików — edycje nie wpływają na główny katalog roboczy
• Pracuje na osobnym branchu
• Po zakończeniu: jeśli dokonał zmian, zwraca ścieżkę i nazwę brancha
• Jeśli nie dokonał zmian — worktree jest automatycznie czyszczone

graph TD
    M[Main worktree<br/>branch: main] --> W1[Worktree 1<br/>branch: refactor-auth]
    M --> W2[Worktree 2<br/>branch: refactor-payments]

    W1 --> R1[Subagent 1<br/>edytuje auth/]
    W2 --> R2[Subagent 2<br/>edytuje payments/]

    R1 -->|git diff| P[Parent agent]
    R2 -->|git diff| P

    P -->|review + merge| M

Wzorce orkiestracji

Cztery wzorce pokrywają większość realnych przypadków. Różnią się tym, czy subagenci działają równolegle czy sekwencyjnie, czy piszą kod czy tylko czytają, i kto odpowiada za jakość wyniku.

Przykłady

Fan-out / Fan-in — trzy niezależne eksploracje jednocześnie, wyniki zbiegają się w jeden plan:

// Wywołaj równolegle (trzy Agent() w jednej odpowiedzi)
Agent(subagent_type: "Explore", description: "Zbadaj email notifications",
  prompt: "Jak działa moduł email/? Flow, zależności, known issues. Max 200 słów.")

Agent(subagent_type: "Explore", description: "Zbadaj push notifications",
  prompt: "Jak działa moduł push/? Flow, zależności, known issues. Max 200 słów.")

Agent(subagent_type: "Explore", description: "Zbadaj in-app notifications",
  prompt: "Jak działa moduł in_app/? Flow, zależności, known issues. Max 200 słów.")

// Parent otrzymuje trzy raporty → tworzy plan refaktoryzacji

Pipeline — wynik każdego etapu trafia do następnego jako kontekst:

// Etap 1
raport = Agent(subagent_type: "Explore",
  description: "Zbadaj architekturę modułu auth",
  prompt: "Przeanalizuj app/auth/. Jak działa flow logowania,
           jakie middleware'y, gdzie walidacja JWT. Raport 300 słów.")

// Etap 2 — raport z etapu 1 wchodzi do promptu
plan = Agent(subagent_type: "Plan",
  description: "Zaplanuj migrację na OAuth 2.0",
  prompt: "Analiza modułu auth: [raport z etapu 1]
           Na tej podstawie zaplanuj migrację z JWT na OAuth 2.0.
           Podaj kroki, zależności, ryzyko.")

// Etap 3 — implementacja pierwszego kroku z planu
Agent(subagent_type: "general-purpose",
  description: "Zaimplementuj krok 1: OAuth provider",
  prompt: "Plan migracji: [plan z etapu 2]
           Zaimplementuj krok 1: dodaj OAuth provider w app/auth/oauth.py.")

Specialist team — każdy agent na osobnym branchu, parent robi review i merge:

// Wywołaj równolegle z isolation: worktree
Agent(description: "CSS zmienne dark theme", isolation: "worktree",
  prompt: "Dodaj zmienne CSS dla dark mode w src/styles/variables.css.
           Użyj prefiksu --color-*. Nie modyfikuj innych plików.")

Agent(description: "Toggle switch dark mode", isolation: "worktree",
  prompt: "Dodaj komponent ToggleDarkMode.tsx w src/components/.
           Przełącza klasę 'dark' na <html>. Dodaj test w __tests__/.")

Agent(description: "Testy wizualne dark mode", isolation: "worktree",
  prompt: "Zaktualizuj snapshoty w tests/visual/ dla dark mode.
           Uruchom: npm run test:visual -- --update-snapshots.")

// Parent: przegląda trzy branche, merguje do main

Supervisor — parent iteruje z subagentem do momentu, gdy wynik spełnia wymagania:

// Runda 1
Agent(subagent_type: "general-purpose",
  description: "Napisz komponent Registration.tsx",
  prompt: "Napisz formularz rejestracji w src/components/Registration.tsx.
           Pola: email, password, confirm password. Użyj React Hook Form.")

// Parent robi review → brakuje walidacji email i siły hasła

// Runda 2 — korekta z konkretnym feedbackiem
Agent(subagent_type: "general-purpose",
  description: "Dodaj walidację formularza",
  prompt: "W src/components/Registration.tsx dodaj walidację:
           - email: format RFC 5322
           - password: min. 8 znaków, jedna cyfra, jeden znak specjalny
           - confirm password: zgodność z password
           Użyj istniejących reguł z utils/validators.ts.")

// Parent: review OK → commit

Foreground vs background

Subagenci mogą działać na pierwszym planie (foreground) lub w tle (background):

Foreground (domyślny) — parent czeka na wynik subagenta. Użyj, gdy wynik jest potrzebny do następnego kroku.

Background — parent kontynuuje pracę, zostanie powiadomiony gdy subagent skończy. Użyj, gdy masz niezależne zadania.

// Foreground — parent potrzebuje wyniku
Agent(description: "Zbadaj schemat bazy", prompt: "...")
// Parent czeka → dostaje wynik → kontynuuje

// Background — niezależne zadania
Agent(description: "Uruchom testy", prompt: "...", run_in_background: true)
Agent(description: "Sprawdź linting", prompt: "...", run_in_background: true)
// Parent kontynuuje pracę → zostanie powiadomiony gdy oba skończą

Koszty multi-agenta

Multi-agent nie jest darmowy:

Pisanie dobrych promptów dla subagentów

Subagent nie widzi historii rozmowy. Prompt to jego jedyne źródło kontekstu. Zły prompt → zły wynik.

Antywzorzec: za skąpy

Agent(prompt: "Zbadaj auth")

Subagent nie wie: czy "auth" to katalog, moduł, koncept? Co ma zbadać — architekturę, bugi, performance? Jaki format raportu?

Antywzorzec: za obszerny

Agent(prompt: "[500 słów kontekstu, historia decyzji,
  pełna architektura projektu, 20 wymagań]")

Za dużo szumu. Subagent tonie w kontekście i gubi główne pytanie.

Wzorzec: briefing jak dla kolegi

Agent(
  description: "Zbadaj flow autoryzacji",
  prompt: "Przeanalizuj katalog app/auth/:
    1. Jak działa flow logowania (od request do response)?
    2. Jakie middleware'y są zaangażowane?
    3. Gdzie jest walidacja JWT?
    4. Jakie są znane problemy / TODO w kodzie?

    Kontekst: planujemy migrację z JWT na session-based auth.
    Twoje wnioski posłużą do zaplanowania zakresu zmian.

    Raport: max 300 słów, z konkretnymi ścieżkami plików
    i numerami linii."
)

Co robi dobrze:

• Jasny zakres (katalog + 4 konkretne pytania)
• Kontekst biznesowy (dlaczego to robimy)
• Format wyniku (max 300 słów, ścieżki + linie)

Nie musisz pisać Agent() ręcznie

W tym poście pokazywaliśmy wywołania Agent() z konkretnymi parametrami — ale to perspektywa wewnętrzna, to co agent robi „pod maską". W praktyce wystarczy napisać po polsku, czego potrzebujesz:

Zbadaj równolegle moduły email/, push/ i in_app/.
Dla każdego opisz flow, zależności i known issues.
Na podstawie wyników zaproponuj plan unifikacji.

Claude Code sam zdecyduje, że potrzebuje trzech subagentów Explore (fan-out), uruchomi je równolegle, zbierze raporty i zaproponuje plan. Nie trzeba pisać Agent(subagent_type: "Explore", ...) — agent rozpoznaje wzorzec z promptu.

Analogicznie dla pipeline'u:

Przeanalizuj moduł auth/, zaplanuj migrację z JWT
na session-based auth, a potem zaimplementuj pierwszy krok.

Agent sam podzieli to na etapy: Explore → Plan → Implement, przekazując kontekst między krokami.

Reguła jest prosta: opisujesz cel, nie mechanizm. Jeśli zadanie wymaga równoległości — agent ją zastosuje. Jeśli wymaga izolacji — użyje worktree. Wywołania Agent() z tego posta to dokumentacja tego, co dzieje się wewnętrznie — nie interfejs, którego musisz używać.

Możesz jednak jawnie użyć składni Agent() w promptach i instrukcjach, gdy chcesz mieć pełną kontrolę — np. wymusić konkretny typ subagenta, worktree isolation albo background execution. Jest to szczególnie przydatne w skillach — skill pisze się raz, a wywołuje wielokrotnie. Warto wtedy precyzyjnie zdefiniować, jakie subagenty mają być uruchamiane, zamiast polegać na tym, że agent za każdym razem sam wybierze właściwą strategię.

Multi-agent poza Claude Code

Claude Code nie jest jedynym narzędziem do multi-agent. Oto jak inne rozwiązania podchodzą do tematu: