Subagents i multi-agent workflow | Kurs Claude AI

Czym są subagenty

Subagent to izolowany agent uruchamiany przez głównego agenta do wykonania konkretnego podzadania. Klasyczny subagent ma własny, czysty kontekst - nie widzi historii rozmowy głównego agenta. Wyjątkiem jest fork, czyli subagent, który dziedziczy całą dotychczasową rozmowę. W sesjach interaktywnych Claude może go uruchomić. Gdy nie poprosi o fork, dostaje zwykłego subagenta z czystym kontekstem - szczegóły w sekcji o fork mode niżej.

Analogia: Szef (główny agent) deleguje zadania pracownikom (subagentom). Każdy pracownik dostaje wytyczne i pracuje samodzielnie, a na końcu raportuje wynik.

Kiedy delegować

Dobre scenariusze:

Równoległe zadania (frontend + backend jednocześnie)
Eksploracja codebase (przeszukiwanie wielu plików)
Izolacja ryzyka (ryzykowne zmiany w osobnym kontekście)
Specjalizacja (security review, test review, style review)

Złe scenariusze:

Proste, jednoetapowe zadania (overhead > korzyść)
Gdy subagent potrzebuje pełnego kontekstu rozmowy (chyba że użyjesz forka - patrz sekcja o fork mode niżej)
Gdy koszt tokenów jest priorytetem (subagenty mnożą koszty)

Custom subagenty

Tworzysz je jako pojedyncze pliki Markdown w .claude/agents/ (projekt) lub ~/.claude/agents/ (wszystkie Twoje projekty). Plik napiszesz sam albo poprosisz Claude, żeby go utworzył. Kreatora /agents ze starszych poradników już nie ma: od wersji 2.1.198 komenda tylko przypomina o tych dwóch drogach. Jeden subagent = jeden plik .md:

---
name: security-reviewer
description: Sprawdza kod pod kątem bezpieczeństwa. Używaj po zmianach w kodzie.
tools: Read, Grep, Glob
model: sonnet
---

## Instrukcje Security Review

Przeanalizuj wskazane pliki pod kątem:
1. Injection attacks (SQL, XSS, command injection)
2. Hardcoded secrets (klucze API, hasła)
3. Brakująca walidacja inputu
4. Niebezpieczne operacje na plikach
5. Problemy z autentykacją/autoryzacją

Format raportu:
- [KRYTYCZNY] - wymaga natychmiastowej naprawy
- [WAŻNY] - naprawić przed merge
- [SUGESTIA] - warto rozważyć

YAML frontmatter:

name - unikalny identyfikator (małe litery i myślniki); wymagane
description - kiedy delegować (Claude używa tego pola do decyzji); wymagane
tools - lista dozwolonych narzędzi; bez tego pola subagent dziedziczy narzędzia głównej rozmowy (subagent w tle dostaje węższy zestaw narzędzi wbudowanych). Jest też odwrotność: disallowedTools (czarna lista)
model - model subagenta: sonnet, opus, haiku, fable, pełne ID (np. claude-opus-5-5) albo inherit (model głównej rozmowy). Kolejność wyboru: najpierw model, który Claude poda przy wywołaniu, potem to pole, potem zmienna CLAUDE_CODE_SUBAGENT_MODEL, a na końcu model głównej rozmowy. Na Anthropic API aliasy wskazują dziś (stan na 1 października 2026): opus na Opus 5.5 (wymaga 2.1.280 lub nowszej), sonnet na Sonnet 5.5 (wymaga 2.1.284 lub nowszej), fable na Fable 5.1 (wymaga 2.1.257 lub nowszej)
effort - poziom effort tylko dla tego subagenta (low, medium, high, xhigh, max); bez tego pola dziedziczy poziom sesji
omitClaudeMd - wartość true uruchamia subagenta bez Twoich plików CLAUDE.md (wymaga 2.1.271 lub nowszej). Przydaje się, gdy wszystko, czego subagent potrzebuje, dostaje w poleceniu

Treść pod frontmatterem staje się system promptem subagenta.

Orchestration patterns

Sekwencyjny

Główny → Subagent A → wynik → Subagent B → wynik → Odpowiedź

Każdy subagent działa po kolei.

Równoległy

Główny → Subagent A --|
       → Subagent B --|→ Agregacja → Odpowiedź
       → Subagent C --|

Wiele subagentów jednocześnie. Główny czeka i łączy wyniki.

Hierarchiczny

Główny → Subagent-lider → Sub-subagent X
                        → Sub-subagent Y

Subagent sam deleguje dalej. Domyślnie może uruchamiać własnych subagentów do trzech warstw pod główną rozmową (od wersji 2.1.219). Limit zmienisz zmienną CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, a wartość 1 wyłącza zagnieżdżanie. Starsze poradniki podają 5 poziomów - tak było tylko w wersjach od 2.1.172 do 2.1.216. Do delegowania subagent potrzebuje narzędzia Agent. Jeśli ma nie delegować dalej (np. recenzent, który tylko czyta), usuń Agent z jego listy tools albo dopisz je do disallowedTools. W sesji interaktywnej wyniki pośrednie zostają u lidera - do głównej rozmowy wraca tylko jego podsumowanie.

Przykład: Multi-agent PR review

"Zrób pełny review tego PR-a"
    |
    +→ security-reviewer - bezpieczeństwo
    +→ test-reviewer - pokrycie testami
    +→ style-reviewer - zgodność z konwencjami
    |
    v
Główny agent: łączy raporty w jeden review

Subagenci w tle, fork mode i wznowienia (stan na 1 października 2026)

Cztery zachowania, które zmieniły codzienną pracę z subagentami:

Tło jako domyślne. Od wersji 2.1.198 subagenci działają domyślnie w tle - Ty pracujesz dalej, a wynik wraca po zakończeniu. W sesji interaktywnej, przy domyślnie włączonym fork mode (punkt niżej), w tle biegną wszyscy subagenci i Claude nie może poprosić o pierwszy plan. Gdy fork mode jest wyłączony (domyślnie w claude -p i w Agent SDK), Claude uruchamia subagenta na pierwszym planie, jeśli potrzebuje wyniku przed dalszą pracą. Skrót Ctrl+B przenosi działające zadanie do tła, a /tasks pokazuje, co aktualnie biegnie.
Fork mode (tryb forków) włączony domyślnie. W sesjach interaktywnych (od wersji 2.1.232) Claude może uruchomić fork, czyli subagenta z kopią bieżącej rozmowy. Fork dostaje cały dotychczasowy kontekst zamiast pustej kartki i krótkiego briefu. Nie każdy subagent jest jednak forkiem. Fork powstaje, gdy Claude poprosi o typ fork. Bez wskazania typu Claude dostaje zwykłego subagenta general-purpose z czystym kontekstem. Subagent, który potrzebuje pełnego kontekstu, przestał więc być złym scenariuszem - wystarczy fork. Fork wnosi do swojego okna całą historię, ale dzieli cache promptu z główną sesją. Według dokumentacji Claude Code przy zadaniu, które i tak wymaga tego samego kontekstu, wychodzi taniej niż świeży subagent. W claude -p i Agent SDK fork mode jest domyślnie wyłączony, a zmienna CLAUDE_CODE_FORK_SUBAGENT=0 wyłącza go wszędzie.
Uprawnienia z tła. Prośba o pozwolenie z subagenta w tle pojawia się w Twojej głównej sesji z nazwą agenta, który pyta. Zatwierdzasz albo odrzucasz (Esc) pojedyncze wywołanie bez zatrzymywania agenta. Zgoda udzielona na dłużej niż jedno wywołanie, np. do końca sesji, obowiązuje w całej sesji, także w głównej rozmowie.
Kontynuacja rozmowy z agentem. Zakończonego subagenta można wznowić: Claude wysyła mu wiadomość (narzędzie SendMessage, po ID lub nazwie), a agent wraca z pełną historią swojej rozmowy i kontynuuje od miejsca, w którym skończył. Wbudowane Explore i Plan są jednorazowe - wznowienia wymagają general-purpose albo własnego subagenta.

Naraz może biec do 20 subagentów (od wersji 2.1.217). Kolejne wywołanie kończy się błędem Concurrent subagent limit reached, a komunikat każe Claude go nie ponawiać. Nowego subagenta da się uruchomić dopiero wtedy, gdy któryś z działających skończy. Limit zmienisz zmienną CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. W sesjach z włączonym ultracode (opis niżej) ten limit nie obowiązuje.

Dwie komendy: /subtask i /fork

/subtask uruchamia forkowanego subagenta, który dziedziczy całą rozmowę, także gdy fork mode jest wyłączony. Użyj, gdy chcesz wydzielić poboczne zadanie („sprawdź, czy ten endpoint ma testy”) bez zaśmiecania głównego wątku jego wynikami pośrednimi. Wynik wraca do Twojej rozmowy. Wymaga wersji 2.1.212 lub nowszej (w wersjach 2.1.161-2.1.211 tę rolę pełniło /fork).
/fork robi kopię rozmowy do osobnej sesji w tle (w widoku agentów, czyli agent view). Główna sesja idzie dalej, kopia pracuje niezależnie - dobre do sprawdzenia dwóch wariantów rozwiązania na tym samym punkcie startowym. Gdy agent view jest wyłączony, /subtask nie działa, a /fork uruchamia forkowanego subagenta.

Fork nie uruchomi kolejnego forka. Limit zagnieżdżenia zwykłych subagentów opisuje wzorzec hierarchiczny wyżej: domyślnie trzy warstwy.

Cztery warstwy, których nie mylić

Stan na 1 października 2026 Claude Code ma cztery mechanizmy, które w rozmowach potocznie zlewają się w „agentów”:

Warstwa	Co to jest	Gdzie w kursie
Subagenci	Pojedynczy agent z własnym kontekstem, wywołany przez główną sesję	ta lekcja
Skills	Instrukcje i pliki pomocnicze ładowane na żądanie; domyślnie działają w głównej rozmowie. Z polem `context: fork` skill rusza w osobnym subagencie, ale mimo nazwy bez historii rozmowy	Hooks, Skills i Permissions
Dynamic workflows	Skrypt JavaScript pisany przez Claude, który orkiestruje dziesiątki lub setki subagentów w tle	Tryb auto, dynamic workflows i agent teams
Agent teams	Eksperymentalny zespół: lider i członkowie z własnymi oknami kontekstu, wspólna lista zadań; włączane zmienną `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`	jw.

Workflows i agent teams opisuje osobna lekcja - tu wystarczy, że wiesz, czym różnią się od zwykłego subagenta.

Monitorowanie i koszty

/usage (aliasy /cost, /stats) - zsumowane zużycie sesji (włącznie z subagentami) i stan limitów
Każdy subagent zużywa własne tokeny (niezależnie od głównej sesji)
Koszty rosną wielokrotnie wraz z liczbą subagentów. Fork niesie w oknie całą rozmowę, ale dzieli cache promptu z główną sesją. Nie zakładaj więc z góry, że jest droższy - sprawdź to w /usage

Pro tip: Orkiestrator (główna sesja) na mocnym modelu, bo to on planuje, dzieli pracę i scala wyniki. Domyślny w Claude Code Opus 5.5 ($4/$20 za milion tokenów wejścia i wyjścia) według Anthropic dorównuje Fable 5.1 w większości zadań. Fable 5.1 ($10/$50) zostaw na najtrudniejsze.

Subagentów puść na tańszym Sonnecie 5.5 ($2/$10), przy prostym przeszukiwaniu na Haiku 4.5 ($1/$5) albo obniż im poziom polem effort. Ta asymetria tnie koszty. Czy nie tnie jakości, sprawdź sam: puść ten sam review raz z subagentem na Sonnecie 5.5 (model: sonnet), raz na Opusie 5.5 (model: opus) i porównaj wyniki. Ceny w tej wskazówce to stawki API (stan na 1 października 2026).

Gotową orkiestrację floty dostajesz też bez ręcznego projektowania: tryb ultracode. To ustawienie Claude Code, nie poziom effort modelu. Przy większych zadaniach każe Claude orkiestrować dynamic workflows. To automatyczne prowadzenie dziesiątek, a przy dużych zadaniach setek subagentów w jednym biegu (limit 1000 agentów na bieg). Od wersji 2.1.284 ultracode to osobny przełącznik: działa przy każdym poziomie effort i nie wymusza już xhigh. Włączasz go komendą /effort ultracode (wyłączasz /effort ultracode off), klawiszem Tab w suwaku /effort albo wpisem "ultracode": true w settings. Flaga claude --effort ultracode (wymaga 2.1.203 lub nowszej) włącza ultracode i ustawia effort xhigh.

Dynamic workflows działają na wszystkich planach płatnych; na Pro włączasz je w wierszu Dynamic workflows w /config. Domyślnie biegnie do 16 agentów równolegle (mniej, gdy komputer ma mniej rdzeni procesora). Zmienna CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS (zakres 1-256, wymaga 2.1.269 lub nowszej) pozwala to zmienić. Od wersji 2.1.271 domyślny rozmiar workflow to medium (poniżej 10 agentów), a na Pro small (poniżej 5). Powyżej 25 agentów albo 1,5 mln tokenów Claude Code pokazuje ostrzeżenie „Large workflow”. Reszta mechaniki workflows: lekcja Tryb auto, dynamic workflows i agent teams.

Ćwiczenie praktyczne: Uruchom workflow z subagentami:

Stwórz custom subagenta w pliku .claude/agents/code-reviewer.md (jeden plik Markdown z frontmatterem name, description, tools) z instrukcjami code review

Poproś głównego agenta: „Zrób review ostatnich zmian, delegując security review do subagenta”

Sprawdź koszty: /usage (albo alias /cost)

Porównaj jakość review z subagentami vs bez

Powtórz punkt 2 przez /subtask i porównaj w /usage, ile kosztował fork z pełnym kontekstem, a ile zwykły subagent

Praktyczne przykłady multi-agentowych workflow znajdziesz w artykułach Autonomiczny zespół deweloperski AI i Zespoły agentów AI w marketingu.

Co dalej

W następnej lekcji poznasz background tasks i headless mode - automatyzację z CI/CD.