Claude Code subagents po polsku, parallel agents w praktyce 2026

Spis treści

• Czym są subagents
• Kiedy używać
• Kiedy NIE używać
• Konfiguracja
• Twój pierwszy subagent
• Parallel execution patterns
• Context isolation
• Komunikacja main ↔ sub
• 5 use case
• Koszty subagents
• Antywzorce
• FAQ

Aktualizacja: maj 2026. Subagents to feature, który zamienia Claude Code z jednowątkowego asystenta w prawdziwy multi-agent system. Zamiast czekać 25 minut aż agent przeanalizuje 5 konkurentów sekwencyjnie, odpalasz 5 subagents równolegle i kończysz w 6 minut. W tym tutorialu pokazuję czym subagents są, kiedy ich używać, jak je konfigurować w Agent SDK i 5 production use case z prawdziwymi liczbami performance.

Czym są subagents w Claude Code

Subagent to wyizolowana instancja Claude'a, którą main agent (parent) spawnuje w trakcie sesji żeby zdelegować część pracy. Każdy subagent dostaje własny prompt, własny zestaw tools, własny context window i działa niezależnie od parenta. Po zakończeniu zwraca jedną finalną odpowiedź, którą main agent dostaje jako wynik tool calla.

Analogicznie do worker threads w systemach operacyjnych, main agent to manager, subagents to workerzy. Manager dzieli zadanie na kawałki, rozdaje workerom, zbiera wyniki, składa w całość. Workerzy nie wiedzą o sobie nawzajem (chyba że manager ich poinformuje), nie mają wspólnej pamięci, są tani do zabicia jeśli któryś się zawiesi.

Subagent vs główny agent

Główny agent (main) to ten, z którym rozmawiasz w terminalu. Widzi pełną historię konwersacji, ma dostęp do twojego kodu, hooków, MCP serverów. Subagent jest spawnowany przez głównego agenta, zna tylko to, co główny mu przekaże w prompcie, ma węższy zakres tools (zazwyczaj subset) i nie pojawia się w UI, jest niewidzialny dla użytkownika.

Subagent vs MCP server

MCP server to zewnętrzny proces, który dostarcza tools przez Model Context Protocol (np. Linear, GitHub, custom DB query). Subagent to instancja Claude'a, która potrafi orkiestrować tools (włącznie z MCP toolsami) ale sama jest LLM-em, nie tylko źródłem danych. MCP = source of data/actions, subagent = autonomous reasoner.

Kiedy używać subagents, 5 typowych scenariuszy

1. Research wielu niezależnych topiców równolegle. Analizujesz 5 konkurentów, każdy ma własną stronę, własny pricing, własny stack. 5 subagents jednocześnie, każdy researchuje jednego konkurenta, scatter-gather pattern. Realnie: 25 minut sekwencyjnie vs 6 minut paralelnie.
2. Multi-file refactor z izolacją. Refactorujesz 12 plików, każdy izolowany (nie importują się nawzajem). 4 subagents, każdy bierze 3 pliki, główny agent łączy wyniki i robi review. Główny nie zalewa się treścią wszystkich 12 plików (60k tokens), tylko dostaje 4 podsumowania (8k tokens).
3. Parallel testing across branches. Masz 3 hipotezy implementacyjne, każda na innym branchu. 3 subagents, każdy odpala testy na swoim branchu, każdy zwraca raport. Główny agent decyduje który branch wygrał.
4. Code generation z różnymi constraintami. Generujesz 4 warianty komponentu UI (light/dark theme × desktop/mobile), 4 subagents z różnymi promptami, każdy zwraca swój wariant.
5. Batch data processing. Masz 100 logów do sklasyfikowania. 10 subagents, każdy bierze 10 logów, klasyfikacja w paraleli. Bonus: użyj Haiku dla subagents, 5x taniej niż Sonnet dla prostej klasyfikacji.

Kiedy NIE używać subagents

Subagents są mocne, ale nie zawsze. Sequential 1 agent wygrywa gdy:

• Zadania są zależne. Output zadania A jest inputem zadania B, B jest inputem C. Nic nie zrównoleglisz, każdy krok musi czekać na poprzedni.
• Zadania są krótkie. 5 zadań po 15 sekund każde to 75s sekwencyjnie. Spawnowanie 5 subagents zajmie 20-30s sam overhead + 15s longest task = 45s. Marginalna oszczędność, większy koszt orkiestracji.
• Potrzebujesz pełnego kontekstu w finale. Subagent zwraca summary, nie pełny scratchpad. Jeśli potrzebujesz wszystkich myśli pośrednich (np. dla debugu), sequential lepszy.
• Cienki budżet. 5 subagents = 5x koszt context loading. Dla solo projektu z budżetem 50 USD/miesiąc, sequential może być jedyną opcją.
• Tier 1 API rate limit. 50 RPM to za mało dla 5 równoległych subagents z aktywnym tool use (każdy robi 10+ requestów). Sequential lub upgrade Tier.

Konfiguracja w settings.json i Agent SDK

W Claude Code CLI subagents spawnowane są automatycznie przez tool Task kiedy main agent uzna, że zadanie jest niezależne. Konfiguracja przez .claude/settings.json:

{
  "subagents": {
    "enabled": true,
    "maxParallel": 5,
    "defaultModel": "claude-sonnet-4-7",
    "researchModel": "claude-haiku-4-5",
    "maxTurnsPerSubagent": 15
  }
}

maxParallel to twardy limit ile subagents naraz, ratuje przed eksplozją kosztów. defaultModel dla większości zadań, researchModel dla research/summarization (Haiku 5x taniej).

W Agent SDK (Python lub TypeScript) spawnowanie subagentów jest jawne. Każdy subagent tworzysz przez API call z osobnym system promptem:

import anthropic
import asyncio

client = anthropic.AsyncAnthropic()

async def spawn_subagent(topic: str) -> str:
    response = await client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=4000,
        system="Jesteś research agent. Analizujesz jeden topic, zwracasz summary 500 słów.",
        messages=[{"role": "user", "content": f"Research: {topic}"}],
    )
    return response.content[0].text

async def main():
    topics = ["Cursor pricing", "Codeium features", "Continue.dev models", "Aider workflow", "Cline tools"]
    results = await asyncio.gather(*[spawn_subagent(t) for t in topics])
    return results

Twój pierwszy subagent, research jednego konkurenta

Zacznijmy od prostego scenariusza: research jednego konkurenta z subagent. Zamiast main agent ładował 30k tokenów stron www do swojego kontekstu, deleguje research do subagenta, dostaje 500-słowowe summary.

Plik research_competitor.py:

import anthropic

client = anthropic.Anthropic()

def research_competitor(name: str, url: str) -> dict:
    """Subagent który analizuje jednego konkurenta i zwraca structured summary."""
    response = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=2000,
        system='''Jesteś competitive intelligence analyst.
Analizujesz jednego konkurenta. Zwracasz JSON z polami:
- pricing (string)
- target_audience (string)
- main_differentiator (string)
- weakness (string)
Bądź konkretny, podawaj liczby gdzie to możliwe.''',
        tools=[{"name": "web_fetch", "input_schema": {...}}],
        messages=[{
            "role": "user",
            "content": f"Researchuj konkurenta: {name}, URL: {url}"
        }],
    )
    return parse_json(response.content[0].text)

# Main agent wywołuje subagenta jednokrotnie
result = research_competitor("Cursor", "https://cursor.com")
print(result)

Korzyść: main agent dostaje tylko 4-polowy JSON (200 tokenów) zamiast całej strony Cursora (30k tokenów). Kontekst parenta jest oszczędzony, finalna analiza zostaje czysta.

Parallel execution patterns, fan-out i scatter-gather

Najczęstsze dwa wzorce parallel execution dla subagents to fan-out i scatter-gather. Różnią się tym, czy main agent agreguje wyniki.

Fan-out (fire and forget)

Main agent spawnuje N subagents, każdy robi swoje, wyniki nigdzie nie są agregowane (np. każdy zapisuje plik). Main idzie dalej po spawnowaniu, nie czeka. Przykład: backup 5 katalogów do różnych S3 buckets.

Scatter-gather (najczęstszy)

Main agent spawnuje N subagents, czeka aż wszyscy skończą (lub timeout), zbiera wszystkie odpowiedzi, syntetyzuje finalny output. Przykład: research 5 konkurentów, main robi comparative analysis z 5 summaries.

Realny TypeScript przykład scatter-gather z Agent SDK:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function researchSubagent(topic: string): Promise<string> {
  const res = await client.messages.create({
    model: "claude-haiku-4-5",
    max_tokens: 1500,
    system: "Jesteś research agent. Zwracasz zwięzłe summary 400 słów.",
    messages: [{ role: "user", content: `Research: ${topic}` }],
  });
  return (res.content[0] as any).text;
}

async function scatterGather(topics: string[]): Promise<string> {
  // Scatter, spawn wszystkich subagents równolegle
  const summaries = await Promise.all(
    topics.map((t) => researchSubagent(t))
  );

  // Gather, main agent synthesizes
  const synthesis = await client.messages.create({
    model: "claude-sonnet-4-7",
    max_tokens: 4000,
    system: "Jesteś senior analyst. Dostajesz 5 summaries, robisz comparative analysis.",
    messages: [{
      role: "user",
      content: `Summaries:\n\n${summaries.map((s, i) => `## Topic ${i+1}\n${s}`).join("\n\n")}`,
    }],
  });
  return (synthesis.content[0] as any).text;
}

const result = await scatterGather([
  "Cursor", "Codeium", "Continue.dev", "Aider", "Cline"
]);

Realne liczby z tego pattern (mierzone na Tier 3 API, maj 2026): sequential 5 konkurentów = 4:50 min, scatter-gather z 5 subagents = 1:08 min. Speedup 4.3x. Koszt: sequential 0.14 USD, parallel 0.16 USD (overhead synthesis call). Worth it.

Context isolation, własny context window dla każdego subagenta

Najmocniejsza cecha subagents to izolacja kontekstu. Każdy subagent ma własne 200k tokenów (lub 1M dla niektórych modeli), zaczyna od pustki, nie widzi historii main agenta i nie widzi innych subagents. Korzyści:

• Brak context pollution. Main agent po sesji ma 80k tokenów. Gdyby załadował do siebie 5 stron konkurentów po 30k każdy, byłoby 230k tokenów = przeciążone, model zgubi szczegóły. Z subagents, main zostaje przy 80k, dostaje 5×500 słów summary = +5k tokenów.
• Brak cross-contamination. Subagent A nie zostanie zmylony tym co znalazł subagent B. Każdy patrzy świeżym okiem.
• Możliwość użycia różnych modeli. Main = Sonnet/Opus, subagents = Haiku. Mix-and-match per zadanie.

Cena izolacji: każdy subagent musi dostać swój system prompt + context od zera. Jeśli wszystkim 5 subagentom przekazujesz ten sam CLAUDE.md (10k tokenów), płacisz 5×10k = 50k tokenów same setup. Rozważ prompt caching dla wspólnego context (Anthropic prompt caching zmniejsza koszt cached prefix o 90%).

Komunikacja main agent ↔ subagents, parent-child message passing

Subagents nie mają shared state z parentem. Cała komunikacja jest message-passing przez prompt (input) i response (output). Brak side-channeli, brak globalnego store, brak observer pattern.

Main agent przekazuje subagentowi:

• System prompt (rola, zasady, output format)
• User message (konkretne zadanie + dane wejściowe)
• Tools (subset narzędzi które subagent może użyć)
• Optional, dotychczasowe wyniki innych subagents (jeśli kolejny krok zależy)

Subagent zwraca jedną rzecz: response.content, czyli finalną odpowiedź. Wszystko co działo się w środku (tool calls, internal reasoning) nie wraca do parenta. Jeśli chcesz logi z subagenta, zapisz je explicite w response (np. JSON z polami summary + tools_used + warnings).

5 praktycznych use case subagents

1. Research 5 konkurentów (scatter-gather)

Klasyk. 5 subagents Haiku researchują równolegle, main Sonnet syntetyzuje. Czas: 24 min → 6 min, koszt: 0.14 USD → 0.16 USD. Use case dla każdego startupu robiącego competitive analysis.

2. Multi-file analysis 20 plików (fan-out)

Audyt bezpieczeństwa 20 plików serverowych. 5 subagents, każdy bierze 4 pliki, sprawdza pod kątem SQL injection / XSS / CSRF. Każdy zwraca listę warnings z linenum. Main agent agreguje do raportu. Czas: 18 min sequential → 4 min parallel.

3. Parallel testing 3 branchy (scatter-gather)

A/B/C test 3 implementacji feature. 3 subagents, każdy checkout swojego brancha (osobny worktree), uruchamia testy, zbiera coverage i performance metrics. Main agent porównuje wyniki, rekomenduje wygrywającą branchę. Czas: 12 min sequential → 4 min parallel.

4. Branch comparison (compare 5 PR-ów)

Reviewujesz 5 PR-ów do tego samego ticketa od różnych deweloperów. 5 subagents, każdy analizuje jednego PR (diff + tests + commit history), zwraca structured review (security/perf/style/coverage). Main robi side-by-side comparison i wybiera najlepszy. Czas: 35 min manualnie → 8 min z subagents.

5. Code generation 4 wariantów komponentu (fan-out)

Designer prosi o 4 warianty pricing card (compact/expanded × light/dark). 4 subagents, każdy generuje swój wariant z tym samym base prompt + różnym constraint. Main agent łączy w jeden plik z 4 exportami. Czas: 10 min sequential → 3 min parallel.

Koszty subagents, każdy = osobny invoice

Subagents są mocne ale nie są darmowe. Każdy subagent to:

• Osobny system prompt (cached jeśli używasz prompt caching)
• Osobny context (5x setup tokens dla 5 subagents)
• Osobne tool calls (każdy subagent ma własne web_fetch / file reads)
• Osobna finalna odpowiedź (input do main agenta)

Realny breakdown dla scatter-gather research 5 konkurentów (maj 2026, Sonnet 4.7 main + Haiku 4.5 subs):

Element	Tokens	Koszt
Main agent setup (Sonnet, prompt + initial)	8k in, 1k out	0.027 USD
5× subagent Haiku (10k in, 2k out each)	50k in, 10k out	0.052 USD
Main agent synthesis (Sonnet, 10k in, 3k out)	10k in, 3k out	0.075 USD
TOTAL parallel	~82k tokens	0.154 USD
Sequential equivalent (Sonnet all)	~120k tokens	0.260 USD

Counter-intuitive insight: parallel scatter-gather z mix Sonnet+Haiku jest tańszy niż sequential same Sonnet, bo Haiku 5x taniej dla research-y zadań. Speed bonus 4x to wisienka na torcie.

Antywzorce, czego unikać przy subagents

1. Over-parallelization. Spawnujesz 15 subagents do zadań po 10 sekund każde. Overhead orkiestracji + rate limit zjadają zysk. Sweet spot to 3-5 subagents dla zadań trwających 1-5 minut każde.
2. Brak limit per subagent. Subagent leci w pętlę (powtarza ten sam tool call), zżera 50k tokenów. Ustaw max_turns=15 dla research, max_turns=30 dla code gen. Hard cap kosztu per subagent.
3. Zagnieżdżanie 3+ levels. Main → sub → subsub → subsubsub. Każdy poziom mnoży koszt i szansę na chaos. Spłaszcz do max 2 poziomów (main + subs).
4. Ignorowanie rate limit. Tier 1 to 50 RPM. Jeśli 5 subagents robi po 15 tool calls każdy, w 30 sekund masz 75 requestów = throttling. Sprawdź swój Tier (Anthropic Console → Usage) zanim zrobisz scatter z 10 subagents.
5. Brak prompt caching dla wspólnego prefix. 5 subagents × 10k system prompt = 50k tokenów rozliczonych. Z caching ten sam scenariusz = 10k full price + 4×1k cached = 14k tokenów. Oszczędność 72%.
6. Subagent z pełnym tool set. Każdy subagent ma dostęp do Bash + Edit + Write + WebFetch + 5 MCP serverów = za dużo opcji, niska decyzyjność. Daj subagentowi tylko te tools, których realnie potrzebuje (np. research subagent tylko WebFetch + Read).

Co dalej

Subagents to jeden z 4 filarów zaawansowanego Claude Code. Pozostałe to hooks, MCP servers i Agent SDK. Razem dają pełen stack do budowania production-grade agentic systems:

• Claude Code tutorial po polsku, kompletny przewodnik
• Claude Code hooks po polsku, 10 praktycznych przykładów
• Claude Code MCP Server po polsku
• Claude Agent SDK po polsku, headless workflow
• Kurs Claude Code po polsku, 6 modułów

Najczęściej zadawane pytania

Powiązane artykuły

Claude Code•9 min

Claude Code cena 2026, ile kosztuje i czy jest darmowy

Claude Code cena w PLN i USD, plany Pro i Max, API pay-as-you-go, darmowe kredyty i alternatywy. Najtańsza legalna ścieżka. Stan maj 2026.

Czytaj

Claude Code•9 min

Claude Max plan po polsku, ceny i limity 2026

Plan Claude Max po polsku: ceny Max 5x i 20x, ile zapytań daje, Claude Pro vs Max, Max vs API. Limity sesji i tygodniowe. Stan maj 2026, dla kogo warto.

Czytaj

Claude Code•15 min

Claude Code Skills po polsku, tutorial Agent Skills 2026

Pierwszy polski tutorial Agent Skills w Claude Code. SKILL.md, frontmatter, progressive disclosure, jak tworzyć skille krok po kroku, vs subagents i MCP.

Czytaj