Subagenci to jeden z najprzydatniejszych dodatków do ekosystemu Claude Code/Claude Agent: pozwalają podzielić złożone przepływy pracy na mniejszych, wyspecjalizowanych „członków zespołu” opartych na sztucznej inteligencji, zachować kontekst wątku głównego i bezpiecznie ograniczyć dostęp do narzędzi. W tym artykule wyjaśniono czym są podagenci, jak je tworzyć i wywoływać (CLI, system plików i SDK) zasady projektowania powinieneś przestrzegać podczas ich tworzenia, a konkretny przykładowy kod możesz kopiować i adaptować.
Czym są podagenci?
A podagent to wstępnie skonfigurowany, wąskozakresowy asystent AI, któremu Claude Code (lub Claude Agent SDK) może delegować zadania. Każdy podagent:
- Ma unikalną nazwę i jasny opis celu.
- Działa w swoim własne okno kontekstowe oddzielone od głównej rozmowy (tak aby długie łańcuchy szczegółów nie zanieczyszczały kontekstu organizatora).
- Można skonfigurować z ograniczonym zestawem narzędzia (odczyt/zapis plików, bash, grep, narzędzia MCP itp.) oraz przy wyborze konkretnego modelu.
- Zawiera podpowiedź systemową (osobowość i instrukcje podagenta), która określa zachowanie i ograniczenia.
Właściwości te sprawiają, że podagenci idealnie nadają się do zadań wymagających dużej ilości tokenów (badania, przeszukiwanie dużych dzienników), zadań wrażliwych ze względu na bezpieczeństwo (skanowanie lub stosowanie narzędzi potencjalnie destrukcyjnych) lub powtarzalnych i ściśle określonych (sprawdzanie stylu, uruchamianie testów).
Anthropic szybko się rozwija: interfejs wiersza poleceń Claude Code CLI i zestaw SDK agenta zostały przebudowane i rozszerzone Claude Agent SDKwprowadzono obsługę wtyczek do pakietowania agentów i powiązanych dostosowań (polecenia ukośnika, serwery MCP, haki) oraz umiejętności Umożliwiają pakowanie przepływów pracy domen do ponownego wykorzystania w Claude.ai, Claude Code i Agent SDK. Te aktualizacje ułatwiają udostępniaj, instaluj i wersjonuj podagentów w zespołach i projektach. Jeśli planujesz tworzyć przepływy pracy produkcyjne, powinieneś rozważyć pakiety wtyczek/umiejętności oraz wzorce wdrażania oparte na SDK.
Dlaczego podagenci są ważni
Trzy powody, dla których są one od razu przydatne:
- Zachowanie kontekstu — długie lub zaszumione wyszukiwania, testy lub skanowanie odbywają się na żywo w podagencie, zamiast przytłaczać kontekst główny. To zmniejsza marnotrawstwo tokenów i ułatwia wnioskowanie na podstawie wyników.
- Specjalistyczna wiedza — możesz zakodować wiedzę i zachowania dotyczące danej dziedziny w monicie systemowym dostosowanym do zadania (np.
security-auditorktóry skupia się na sekretach, problemach zależności i niebezpiecznym korzystaniu z powłoki). - Bezpieczniejsze uprawnienia — ograniczenie narzędzi na podagenta zmniejsza promień rażenia (recenzent dokumentów może mieć narzędzia tylko do odczytu; osoba przeprowadzająca testy może mieć
Bashale nieEdit). - Równoległość: Można uruchomić wiele podagentów, aby działały równolegle (na przykład:
style-checker,security-scanner,test-runner) a następnie zbierz ich krótkie wyniki — to ogromna zaleta w przypadku kosztownych, niezależnych kontroli.
Wymagania wstępne dotyczące korzystania z podagentów w kodzie Claude
Zanim zaczniesz tworzyć podagentów, upewnij się, że masz następujące elementy:
1) Kod Claude'a został zainstalowany i uwierzytelniony
Zainstaluj Claude Code CLI lub skorzystaj z integracji web/IDE. Szybki start i dokumentacja konfiguracji CometAPI wypisz obsługiwane metody instalacji (pakiet globalny npm lub instalatory natywne) i pokaż, jak zweryfikować instalację za pomocą claude --version / claude doctor. Będziesz także potrzebować Interfejs API Comet konto (Używanie klucza CometAPI do dostępu do kodu Claude jest tańsze i wygodniejsze niż oficjalny model) jak zauważono w Szybkim starcie.
2) Węzeł/środowisko (dla niektórych ścieżek instalacji) i podstawowe narzędzia powłoki
Jeśli instalujesz za pomocą pakietu npm, powinieneś mieć Node.js (Node 18+ jest często używany w przykładach). Jeśli zamierzasz używać Agent SDK (JavaScript/TypeScript lub Python), będziesz potrzebować projektu z zainstalowaną zależnością SDK. Wiele samouczków zakłada standardowe narzędzia programistyczne (git, bash, opcjonalnie). gh CLI dla przepływów pracy GitHub).
3) Układ projektu i CLAUDE.md
Najlepszą praktyką jest przechowywanie dokumentacji pomocniczej na poziomie repozytorium (CLAUDE.md) i umieścić agentów o zakresie projektu .claude/agents/ Więc członkowie zespołu je dziedziczą. Pliki CLAUDE.md są automatycznie wciągane do kontekstu Claude'a i pomagają w spójnym kierowaniu zachowaniem w różnych sesjach. Każdy podagent to plik Markdown z frontmatterem YAML. Minimalny przykład:
---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. When invoked:
1. Run `git diff` to identify modified files.
2. Focus review on changed code paths.
3. List security issues, probable false positives, and suggested fixes.
4. Provide a short, prioritized action list.
Return results in JSON with fields: summary, issues.
namejest identyfikatorem zapisanym małymi literami.descriptionprowadzi automatyczne wywoływanie i dopasowywanie.toolsogranicza dostęp do narzędzi (pomija dziedziczenie wszystkiego).modelmoże byćsonnet,opus,haikulubinherit.
4) Uprawnienia i serwery MCP (opcjonalne, ale powszechne)
Jeśli Twoje przepływy pracy korzystają z serwerów Model Context Protocol (MCP) lub narzędzi zewnętrznych (Puppeteer, Sentry, niestandardowe narzędzia REST), upewnij się, że serwery MCP są skonfigurowane i dostępne. W przypadku operacji wrażliwych (zapis, bash, zatwierdzanie w Git) rozważnie dostosuj listę dozwolonych i uprawnienia dla poszczególnych agentów. tools zakres.
Jak tworzyć podagentów w kodzie Claude
Podagentów można tworzyć na trzy główne sposoby: za pomocą interaktywnego interfejsu CLI (/agents), jako pliki Markdown systemu plików lub programowo za pomocą pakietu Agent SDK. Poniżej znajdują się opcje krok po kroku:
Claude Code obsługuje trzy praktyczne sposoby tworzenia podagentów:
- Interaktywny CLI
/agentsUI — najszybszy sposób iteracyjnego tworzenia w ramach sesji. - Oparty na systemie plików — twórz pliki Markdown z frontmatterem YAML
.claude/agents/(na poziomie projektu) lub~/.claude/agents/(na poziomie użytkownika). Agenci projektu mają wyższy priorytet. - Programowy (Agent SDK) — zdefiniuj podagentów w kodzie za pomocą
agentsparametr podczas wywoływaniaquery(); zalecane dla aplikacji opartych na SDK. To podejście jest idealne, gdy podagenci muszą być tworzeni dynamicznie lub osadzeni w aplikacji.
Szybki interaktywny przepływ (zalecany pierwszy krok)
- Uruchom Claude Code w terminalu lub otwórz paletę poleceń w VS Code.
- Uruchom interfejs podagentów za pomocą polecenia slash:
/agents
- Dodaj Utwórz nowego agentaWybierz zakres na poziomie projektu lub użytkownika, wpisz nazwę/opis/narzędzia/monit systemowy i zapisz. Możesz wygenerować szkic z Claude'em, a następnie go dopracować. Po zapisaniu agent będzie dostępny w
/agentsi może być wywoływany jawnie lub automatycznie.
Podagenty oparte na systemie plików (tekst Markdown + YAML)
Podagenci są przechowywani jako pliki Markdown z frontmatterem YAML. Umieść je w:
- Zakres projektu:
.claude/agents/*.md(najwyższy priorytet) - Zakres użytkownika:
~/.claude/agents/*.md
Podstawowa struktura pliku:
---
name: code-reviewer
description: "Review recent code changes for security and style."
tools: Read, Grep, Glob, Bash # optional; omit to inherit
model: sonnet # optional; or 'inherit'
---
You are a senior code reviewer with expertise in security, performance, and best practices.
When reviewing:
- Identify security vulnerabilities
- Prioritize clarity and maintainability
- Always provide concise examples and suggested fixes
- If unsure, ask for the minimal reproducible snippet
Kilka uwag dotyczących implementacji:
namemusi być napisane małymi literami i rozdzielone myślnikami.- Pomijanie
toolspozwoli podagentowi odziedziczyć wszystkie narzędzia wątku głównego; jawne wyszczególnienie narzędzi wymusza model najmniejszych uprawnień. - Zastosowanie
model: 'inherit'aby zapewnić spójne zachowanie z wątkiem głównym lub określić alias modelu (np.sonnet,opus,haiku).
Definicja CLI JSON (użycie ad hoc/sesji)
Można zdefiniować tymczasowych podagentów w trakcie uruchamiania sesji:
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer.",
"prompt": "You are a senior code reviewer. Focus on security and best practices.",
"tools": ,
"model": "sonnet"
}
}'
Agenci zdefiniowani przez CLI przydają się w przypadku skryptów lub eksperymentów. Mają niższy priorytet niż agenci projektu, ale wyższy niż agenci użytkownika.
Definicja programowa (Agent SDK — zalecana dla aplikacji)
Jeśli tworzysz aplikację lub automatyzację, zdefiniuj podagentów programowo za pomocą pakietu Agent SDK agents Parametr (to najbardziej zintegrowana opcja). Przykład (TypeScript):
import { query } from '@anthropic-ai/claude-agent-sdk';
async function runReview() {
const result = await query({
prompt: "Assess the authentication module for security issues",
options: {
agents: {
"code-reviewer": {
description: "Expert code review specialist",
prompt: `You are a code review specialist...`,
tools: ,
model: "sonnet"
},
"test-runner": {
description: "Runs the test suite and analyzes failures",
prompt: `You run tests and summarize failures...`,
tools: ,
model: "sonnet"
}
}
}
});
console.log(result);
}
Zestaw SDK akceptuje również agentów opartych na systemie plików (będzie ładował .claude/agents/ pliki), jeśli wolisz ten wzorzec. Agenci programowi są wydajni w przypadku dynamicznych przepływów pracy i integracji CI.
W przypadku języka Python claude-agent-sdk Pakiet obsługuje podobne wzorce: możesz użyć query() or ClaudeSDKClient i konfiguruj opcje, narzędzia i serwery MCP programowo. Przykłady szybkiego startu znajdziesz w repozytorium Python SDK.
Jak wywołać podagentów
Automatyczne delegowanie
Claude Code może automatycznie Wybierz podagenta, gdy monit użytkownika odpowiada jego celowi. Jest to przydatne do koordynacji w tle, gdzie główny agent automatycznie kieruje zadania do odpowiedniego specjalisty. Polegaj na jasnych opisach podagentów i ukierunkowanych monitach systemowych, aby zwiększyć dokładność automatycznego wyboru.
Wyraźne wywołanie (zalecane dla przejrzystości)
Możesz jawnie wywołać agenta w rozmowie:
> Use the code-reviewer subagent to check my recent changes
Jawne wywołanie jest deterministyczne i zalecane w przypadku przepływów produkcyjnych, w których chcesz uniknąć nieoczekiwanego delegowania.
Wzorce orkiestratora SDK
Typowe wzorce w aplikacjach SDK:
- Widelec + zbieranie:Uruchom wiele podagentów równolegle, zbierz zwięzłą odpowiedź każdego agenta, a następnie podsumuj/scal wyniki w głównym agencie.
- Pętla nadzorcy:Organizator przydziela zadania podagentom, sprawdza wyniki i albo je akceptuje, albo żąda ponownego obliczenia/wyjaśnienia.
- Wykonanie w trybie piaskownicy:Przydziel potencjalnie niebezpieczne możliwości (wdrażanie, uruchamianie skryptów) ściśle ograniczonemu agentowi i wymagaj jawnego zatwierdzenia przez człowieka przed wykonaniem.
Wzorce te odwzorowują praktyczne implementacje wykorzystujące zarządzanie sesjami, haki i narzędzia MCP pakietu Agent SDK.
Jak tworzyć podagentów, którzy są użyteczni, bezpieczni i możliwi do komponowania
1) Pojedyncza odpowiedzialność i jasne wskazówki
Każdy podagent powinien mieć jeden jasny cel i monit systemowy określający granice, kryteria sukcesu i format wyjściowy. Jeśli pożądany wynik jest ustrukturyzowany (JSON, lista wypunktowana, poprawka kodu), należy precyzyjnie poinstruować podagent, aby zredukować błędy parsowania.
2) Najmniejsze przywileje dla narzędzi
Przyznaj tylko te narzędzia, których potrzebuje podagent. Na przykład recenzent dokumentów nie potrzebuje Write or Bash. W miarę możliwości ustaw domyślnie tylko do odczytu i jawnie eskaluj uprawnienia narzędzi w razie potrzeby. Zmniejsza to ryzyko i upraszcza audyt.
3) Zwracaj zwarte, ustrukturyzowane wyniki
Podagenci powinni wrócić zwięzłe, ostateczne odpowiedzi zamiast długotrwałych śladów myślowych. Typowym schematem jest: wykonanie dużej ilości pracy w kontekście podagenta, a następnie zwrócenie krótkiego podsumowania z załącznikami (poprawkami, odwołaniami do plików, JSON). To maksymalizuje wydajność kontekstu dla koordynatora.
4) Testowalność i wersjonowanie
Przechowuj pliki podagentów w systemie kontroli wersji, twórz testy CI, które ćwiczą rzeczywiste przebiegi na małych danych wejściowych, i przypinaj modele/zestawy narzędzi. Jeśli korzystasz z umiejętności i wtyczek, zastosuj wzorce z rynku wtyczek/wersjonowania, aby zarządzać aktualizacjami i wycofywaniem.
5) Punkty kontrolne i punkty kontrolne z udziałem człowieka
Użyj haków SDK do przechwytywania wywołań narzędzi (haki PreToolUse) i żądania zgody człowieka na działania destrukcyjne. Rejestruj wszystkie wywołania narzędzi w celu umożliwienia powtarzania audytów. SDK udostępnia mechanizmy haków i uprawnień, które obsługują ten wzorzec.
Przykład aplikacji — mały, produkcyjny proces
Poniżej znajduje się kompaktowy przykład pokazujący typowe elementy: agenta systemu plików, wywołanie zestawu SDK korzystające z dwóch agentów (jednego do przeglądu, drugiego do testów) i prostą orkiestrację.
1) Agent systemu plików: .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Use PROACTIVELY after code changes. Perform security, style, and maintainability review on modified files.
tools: Read, Grep, Glob
model: inherit
---
You are a meticulous senior code reviewer. When invoked:
1. Run `git diff --name-only` to find modified files.
2. For each modified file, read and look for security issues, suspicious patterns, or maintainability problems.
3. Return JSON:
{
"summary": "one-line summary",
"issues": ,
"recommended_changes":
}
2) Orkiestracja programowa (Node.js)
import { query } from '@anthropic-ai/claude-agent-sdk';
import fs from 'fs';
async function runPipeline() {
const result = query({
prompt: 'Run PR checks: security review then unit tests.',
options: {
agents: {
'code-reviewer': {
description: 'Use PROACTIVELY after code changes; output JSON with issues.',
prompt: fs.readFileSync('./.claude/agents/code-reviewer.md', 'utf8'),
tools: ,
model: 'sonnet'
},
'test-runner': {
description: 'Run test suite and summarize failing tests.',
prompt: `You are a test-runner. Execute tests and return JSON { summary, failing_tests[] }`,
tools:
}
}
}
});
for await (const message of result) {
// Implement streaming logic: messages may include subagent outputs
console.log(message);
}
}
runPipeline().catch(console.error);
Uwagi: dotychczasowy code-reviewer jest przechowywany w repozytorium w celu ponownego wykorzystania przez zespół; wywołanie SDK pokazuje, że agenci programowi mają pierwszeństwo i tools zakres zapobiega przypadkowym zapisom.
Zaawansowane tematy i wzorce
Dynamiczna konfiguracja agenta
Utwórz sparametryzowane fabryki agentów, które wybierają model i zestawy narzędzi w zależności od środowiska (dev vs. prod) lub poziomów ważności (np. strict vs balanced (tryby bezpieczeństwa). Przykłady SDK pokazują, jak generować definicje agentów w czasie wykonywania.
Równoległość
Wydzielaj równolegle wiele agentów analitycznych tylko do odczytu (styl, bezpieczeństwo, pokrycie testami) i agreguj ich dane wyjściowe JSON w wątku głównym. To znacznie skraca czas zegarowy dla dużych repozytoriów.
Agenci dostarczani przez wtyczkę
Wtyczki mogą dostarczać podagentów spakowanych z manifestem wtyczki; pojawiają się one w /agents obok niestandardowych agentów i można je wywołać jawnie. Użyj tego, aby rozmieścić standardowych agentów w zespołach.
Gdzie używać kodu Claude? CLI jest najbardziej zalecane
Z radością ogłaszamy, że CometAPI teraz w pełni obsługuje potężny interfejs wiersza poleceń Claude Code. Aby korzystać z modelu API Comet w Claude Code, wystarczy zainstalować Claude Code i uwierzytelnić się przy użyciu uzyskanego klucza Comet API i adresu bazowego.
Dlaczego warto używać kodu Claude poprzez CometAPI?
Najważniejsze funkcje sztucznej inteligencji: Łatwe generowanie, debugowanie i optymalizowanie kodu przy użyciu modeli stworzonych specjalnie dla programistów.
- Elastyczny wybór modeli: Nasza szeroka gama modeli pozwala na płynniejszy rozwój.
- Bezproblemowa integracja: API są zawsze dostępne. Zintegruj Claude Code bezpośrednio z istniejącym procesem pracy w kilka minut.
- Korzystanie z Claude Code za pośrednictwem CometAPI pozwoli zaoszczędzić więcej kosztówInterfejs API Claude udostępniany przez CometAPI jest przeceniony o 20% w stosunku do oficjalnej ceny i jest aktualizowany do najnowszej wersji przez oficjalną firmę.
Gotowy do użycia kodu Claude? Sprawdź Przewodnik po API dla szczegółowych instrukcji.
Jeśli chcesz poznać więcej wskazówek, poradników i nowości na temat sztucznej inteligencji, obserwuj nas na VK, X oraz Discord!
Zobacz także Jak zainstalować i uruchomić Claude Code za pomocą CometAPI?
Końcowe przemyślenia
Traktuj podagentów jako wielokrotnego użytku, wersjonowane mikro-personyZacznij od małych rzeczy: stwórz doc-reviewer oraz test-runner w celu odzyskania, sprawdź je .claude/agents/i zautomatyzować je w CI, używając headless claude -pUdoskonalaj swoje monity, dodawaj ustrukturyzowane wyniki i zawężaj uprawnienia narzędzi.
Model mentalny, który pomaga najbardziej: wyobraź sobie Claude'a jako kierownika projektu, a podagentów jako specjalistów w zespole. Kierownik deleguje jasno sformułowane zadania, agreguje rezultaty specjalistów i sporządza raport końcowy. Z czasem zauważysz poprawę niezawodności, testowalności i możliwości automatyzacji dużych fragmentów przepływów pracy programistów.