Subagenten zijn een van de meest nuttige toevoegingen aan het Claude Code/Claude Agent-ecosysteem: ze stellen je in staat om complexe workflows op te splitsen in kleinere, gespecialiseerde AI-'teamgenoten', de context van de hoofdthread te behouden en de toegang tot tools veilig te beperken. Dit artikel legt uit welke subagenten zijn, hoe je ze kunt creëren en aanroepen (CLI, bestandssysteem en SDK), de ontwerpprincipes je moet de volgende instructies volgen bij het bouwen ervan, en concrete voorbeeldcode Je kunt het kopiëren en aanpassen.
Wat zijn subagenten?
A subagent is een vooraf geconfigureerde AI-assistent met een beperkte reikwijdte waaraan Claude Code (of de Claude Agent SDK) werk kan delegeren. Elke subagent:
- Heeft een unieke naam en een duidelijke omschrijving van het doel.
- Loopt in zijn eigen contextvenster los van het hoofdgesprek (zodat lange ketens van details de context van de orkestrator niet vervuilen).
- Kan worden geconfigureerd met een beperkte set van tools (bestand lezen/schrijven, bash, grep, MCP-hulpmiddelen, enz.) en met een specifieke modelkeuze.
- Bevat een systeemprompt (de persoonlijkheid en instructies van de subagent) die het gedrag en de beperkingen stuurt.
Deze eigenschappen maken subagenten ideaal voor taken die veel tokens vereisen (onderzoek, zoeken in grote logs), beveiligingsgevoelig zijn (scannen of potentieel destructieve tools) of repetitief en duidelijk gespecificeerd zijn (stijlcontrole, testen).
Anthropic heeft snel iteraties uitgevoerd: de Claude Code CLI en Agent SDK zijn opnieuw ontworpen en uitgebreid naar de Claude Agent SDK, er is plug-inondersteuning geïntroduceerd voor het bundelen van agenten en gerelateerde aanpassingen (slash-opdrachten, MCP-servers, hooks), en Skills bieden een manier om domeinworkflows te verpakken voor hergebruik in Claude.ai, Claude Code en de Agent SDK. Deze updates maken het eenvoudiger om delen, installeren en versie subagenten voor teams en projecten. Als u van plan bent productieworkflows te bouwen, moet u de plugin-/skillpackaging en de SDK-gebaseerde implementatiepatronen evalueren.
Waarom subagenten belangrijk zijn
Drie redenen waarom ze meteen nuttig zijn:
- Contextbehoud — lange of rumoerige zoekopdrachten, testruns of scans live in een subagent in plaats van de primaire context te overbelasten. Dat vermindert tokenverspilling en maakt de resultaten gemakkelijker te doorgronden.
- Gespecialiseerde expertise — u kunt domeinkennis en -gedrag coderen in een systeemprompt die is afgestemd op de taak (bijvoorbeeld een
security-auditordat zich richt op geheimen, afhankelijkheidsproblemen en onveilig shell-gebruik). - Veiligere toestemmingen — het beperken van hulpmiddelen per subagent vermindert de straal van de explosie (een doc-reviewer heeft mogelijk alleen-lezen hulpmiddelen; een test-runner heeft
Bashmaar neeEdit). - parallellisatie: U kunt meerdere subagenten tegelijk laten draaien (bijvoorbeeld:
style-checker,security-scanner,test-runner) en verzamelen vervolgens hun korte resultaten — een enorme winst ten opzichte van dure, onafhankelijke controles.
Vereisten voor het gebruik van subagenten in Claude Code
Voordat u met het bouwen van subagenten begint, moet u ervoor zorgen dat u het volgende hebt geregeld:
1) Claude Code geïnstalleerd en geauthenticeerd
Installeer de Claude Code CLI of gebruik de web-/IDE-integraties. Snelstartgids en installatiedocumentatie van CometAPI lijst met ondersteunde installatiemethoden (npm global package of native installers) en laat zien hoe u uw installatie kunt verifiëren met claude --version / claude doctor. Je hebt ook een KomeetAPI account (Het is goedkoper en handiger om de sleutel van CometAPI te gebruiken om toegang te krijgen tot de Claude-code dan het officiële model.) zoals vermeld in de Quickstart.
2) Knooppunt/omgeving (voor sommige installatiepaden) en basis shell-tooling
Als je via het npm-pakket installeert, heb je Node.js nodig (Node.js is gebruikelijk in voorbeelden). Als je de Agent SDK (JavaScript/TypeScript of Python) wilt gebruiken, heb je een project nodig met de SDK-afhankelijkheid geïnstalleerd. Veel tutorials gaan uit van standaard ontwikkelaarstools (git, bash, optioneel). gh CLI voor GitHub-workflows).
3) Project lay-out & CLAUDE.md
De beste werkwijze is om helper-documentatie op repo-niveau te bewaren (CLAUDE.md) en om projectgerichte agenten in te zetten .claude/agents/ zodat teamgenoten ze overnemen. CLAUDE.md-bestanden worden automatisch in Claude's context geladen en helpen bij het consistent sturen van gedrag over sessies heen. Elke subagent is een Markdown-bestand met YAML-inleiding. Minimaal voorbeeld:
---
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.
nameis een kleine letter-identificatie.descriptionbegeleidt automatische aanroep en matching.toolsbeperkt de toegang tot gereedschappen (alles overnemen).modelkan zijnsonnet,opus,haikuofinherit.
4) Machtigingen en MCP-servers (optioneel maar gebruikelijk)
Als uw workflows Model Context Protocol (MCP)-servers of externe tools (Puppeteer, Sentry, aangepaste REST-tools) gebruiken, zorg er dan voor dat uw MCP-servers geconfigureerd en bereikbaar zijn. Voor gevoelige bewerkingen (schrijven, bash, git commit) moet u de allowlist en de per-agent-instellingen zorgvuldig bepalen. tools reikwijdte.
Hoe subagenten in Claude Code te creëren
U kunt subagenten op drie manieren maken: via de interactieve CLI (/agents), als markdown-bestanden voor het bestandssysteem, of programmatisch via de Agent SDK. Hieronder vindt u de stapsgewijze opties:
Claude Code ondersteunt drie praktische manieren om subagenten te maken:
- Interactieve CLI
/agentsUI — snelste voor iteratieve creatie binnen een sessie. - Bestandssysteemgebaseerd — Markdown-bestanden maken met YAML-voorpagina's in
.claude/agents/(projectniveau) of~/.claude/agents/(gebruikersniveau). Projectagenten hebben een hogere prioriteit. - Programmatisch (Agent SDK) — definieer subagenten in de code via de
agentsparameter wanneer u aanroeptquery(); aanbevolen voor SDK-gestuurde apps. Deze aanpak is ideaal wanneer subagenten dynamisch moeten worden aangemaakt of in een applicatie moeten worden ingesloten.
Snelle interactieve flow (aanbevolen eerste stap)
- Start Claude Code in uw terminal of open het opdrachtenpalet in VS Code.
- Voer de subagentinterface uit met de slash-opdracht:
/agents
- Kies Nieuwe agent maken, kies de scope op project- of gebruikersniveau, vul naam/beschrijving/tools/systeemprompt in en sla op. U kunt een concept genereren met Claude en dit vervolgens verfijnen. Na het opslaan is de agent beschikbaar in
/agentsen kan expliciet of automatisch worden aangeroepen.
Op bestandssysteem gebaseerde subagenten (Markdown + YAML-inleiding)
Subagenten worden opgeslagen als Markdown-bestanden met YAML-frontmatter. Plaats ze in:
- Project scope:
.claude/agents/*.md(hoogste prioriteit) - Gebruikersbereik:
~/.claude/agents/*.md
Basisbestandsstructuur:
---
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
Enkele opmerkingen over de implementatie:
namemoet in kleine letters en met koppeltekens worden geschreven.- weglaten
toolszorgt ervoor dat de subagent alle hulpmiddelen van de hoofdthread erft. Door hulpmiddelen expliciet te vermelden, wordt een model met minimale bevoegdheden afgedwongen. - Gebruik
model: 'inherit'voor consistent gedrag met de hoofdthread, of geef een modelalias op (bijv.sonnet,opus,haiku).
CLI JSON-definitie (ad hoc/sessiegebruik)
U kunt tijdelijke subagenten inline definiëren bij het starten van een sessie:
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer.",
"prompt": "You are a senior code reviewer. Focus on security and best practices.",
"tools": ,
"model": "sonnet"
}
}'
CLI-gedefinieerde agents zijn handig voor scriptuitvoeringen of experimenten; ze hebben een lagere prioriteit dan projectagenten, maar een hogere dan gebruikersagenten.
Programmatische definitie (Agent SDK — aanbevolen voor apps)
Als u een applicatie of automatisering bouwt, definieert u subagenten programmatisch via de Agent SDK's agents parameter (dit is de meest geïntegreerde optie). Voorbeeld (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);
}
De SDK accepteert ook op bestandssystemen gebaseerde agents (het laadt .claude/agents/ bestanden) als u dat patroon verkiest. Programmatische agents zijn krachtig voor dynamische workflows en CI-integratie.
Voor Python is de claude-agent-sdk pakket ondersteunt vergelijkbare patronen: u kunt gebruiken query() or ClaudeSDKClient en configureer opties, tools en MCP-servers programmatisch. Zie de Python SDK-repository voor voorbeelden van snelle start.
Hoe subagenten aan te roepen
Automatische delegatie
Claude Code kan webmaster. Kies een subagent wanneer een gebruikersprompt overeenkomt met het doel van een subagent. Dit is handig voor achtergrondorkestratie, waarbij de hoofdagent taken automatisch naar de juiste specialist routeert. Vertrouw op duidelijke subagentbeschrijvingen en gerichte systeemprompts om de nauwkeurigheid van automatische selectie te verbeteren.
Expliciete aanroeping (aanbevolen voor de duidelijkheid)
U kunt een agent expliciet aanroepen tijdens een gesprek:
> Use the code-reviewer subagent to check my recent changes
Expliciete aanroep is deterministisch en wordt aanbevolen voor productiestromen waarbij u onverwachte delegatie wilt voorkomen.
SDK-orchestratorpatronen
Veelvoorkomende patronen in SDK-apps:
- Vork + verzamelen: Start meerdere subagenten parallel, verzamel het beknopte antwoord van elke agent en vat de resultaten samen/voeg ze samen in de hoofdagent.
- Supervisor-lus:De orchestrator wijst taken toe aan subagenten, inspecteert de resultaten en accepteert deze of vraagt om een herberekening/verduidelijking.
- Sandbox-uitvoering: Geef potentieel gevaarlijke mogelijkheden (implementeren, scripts uitvoeren) aan een agent met strikte beperkingen en vereis expliciete menselijke goedkeuring voordat de uitvoering plaatsvindt.
Deze patronen worden gekoppeld aan praktische implementaties met behulp van de sessiebeheer-, hooks- en MCP-tools van de Agent SDK.
Hoe je subagenten maakt die nuttig, veilig en samenstelbaar zijn
1) Eén verantwoordelijkheid en duidelijke aanwijzingen
Elke subagent moet één duidelijk doel hebben en een systeemprompt die grenzen, succescriteria en uitvoerformaat specificeert. Als de gewenste uitvoer gestructureerd is (JSON, bullet list, codepatch), geef de subagent dan specifieke instructies om parseerfouten te verminderen.
2) De minste privileges voor gereedschappen
Ken alleen de tools toe die een subagent nodig heeft. Een doc-reviewer heeft bijvoorbeeld geen tools nodig. Write or BashStel waar mogelijk standaard alleen-lezen in en verhoog toolrechten expliciet indien nodig. Dit vermindert risico's en vereenvoudigt de controle.
3) Geef compacte, gestructureerde uitkomsten
Subagenten moeten terugkeren beknopte, definitieve antwoorden in plaats van langlopende gedachtesporen. Een veelvoorkomend patroon is: doe zwaar werk binnen de context van de subagent en retourneer vervolgens een korte samenvatting met bijlagen (patches, bestandsverwijzingen, JSON). Dit maximaliseert de contextefficiëntie voor de orchestrator.
4) Testbaarheid en versiebeheer
Sla subagentbestanden op in versiebeheer, maak CI-tests die echte runs uitvoeren op kleine invoerwaarden en koppel modellen/toolsets. Als u afhankelijk bent van Skills en plugins, gebruik dan de pluginmarktplaats/versiebeheerpatronen om upgrades en rollbacks te beheren.
5) Audit-hooks en menselijke controlepunten
Gebruik SDK-hooks om toolaanroepen te onderscheppen (PreToolUse-hooks) en vereis menselijke goedkeuring voor destructieve acties. Registreer alle toolaanroepen voor herhaalbare audits. De SDK biedt hook- en permissiemechanismen om dit patroon te ondersteunen.
Toepassingsvoorbeeld: een kleine, productie-achtige pijplijn
Hieronder ziet u een compact voorbeeld met de typische onderdelen: een bestandssysteemagent, een SDK-aanroep die twee agenten gebruikt (één voor beoordeling en één voor tests) en een eenvoudige orkestratie.
1) Bestandssysteemagent: .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) Programmatische orkestratie (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);
Opmerkingen: the code-reviewer wordt opgeslagen in de repository voor hergebruik door het team; de SDK-aanroep laat zien dat programmatische agenten voorrang krijgen en de tools Scoping voorkomt onbedoelde schrijfbewerkingen.
Geavanceerde onderwerpen en patronen
Dynamische agentconfiguratie
Creëer geparametriseerde agentfabrieken die modellen en toolsets kiezen op basis van de omgeving (dev vs. prod) of ernstniveaus (bijv. strict vs balanced beveiligingsmodi). De SDK-voorbeelden laten zien hoe u agentdefinities genereert tijdens runtime.
Parallellisatie
Draai meerdere read-only analyse-agents parallel (stijl, beveiliging, testdekking) en aggregeer hun JSON-uitvoer in de hoofdthread. Dit verkort de kloksnelheid voor grote repositories aanzienlijk.
Door plug-ins geleverde agents
Plugins kunnen subagenten leveren die zijn verpakt met het plugin-manifest; ze verschijnen in /agents naast aangepaste agents en kunnen expliciet worden aangeroepen. Gebruik dit om gestandaardiseerde agents over teams te verdelen.
Waar Claude code cli het meest wordt aanbevolen
We zijn verheugd te kunnen melden dat CometAPI nu de krachtige Claude Code CLI volledig ondersteunt. U hoeft alleen Claude Code te installeren en u te verifiëren met de verkregen Comet API-sleutel en het basisadres om het Comet API-model op Claude Code te gebruiken.
Waarom moet ik claude-code gebruiken via CometAPI?
Belangrijkste functies van Kunstmatige Intelligentie: genereer, debug en optimaliseer eenvoudig code met behulp van modellen die speciaal voor ontwikkelaars zijn ontwikkeld.
- Flexibele modelselectie: dankzij ons uitgebreide aanbod aan modellen kunt u soepeler ontwikkelen.
- Naadloze integratie: API's zijn altijd beschikbaar. Integreer Claude Code binnen enkele minuten direct in uw bestaande workflow.
- Door Claude Code via CometAPI te gebruiken, bespaart u meer kostenDe Claude API van CometAPI is 20% goedkoper dan de officiële prijs en wordt door de officiële leverancier bijgewerkt met het nieuwste model.
Klaar om Claude Code cli te gebruiken? raadpleeg de API-gids voor gedetailleerde instructies.
Als u meer tips, handleidingen en nieuws over AI wilt weten, volg ons dan op VK, X en Discord!
Zie ook Hoe installeer en voer ik Claude Code uit via CometAPI?
Laatste gedachten
Behandel subagenten als herbruikbare, geversioniseerde micro-persona'sBegin klein: maak een doc-reviewer en test-runner voor een repo, check ze in .claude/agents/en automatiseer ze in CI met behulp van headless claude -pHerhaal uw prompts, voeg gestructureerde uitvoer toe en verscherp de gereedschapsmachtigingen.
Het mentale model dat het meest helpt: stel je Claude voor als projectmanager en subagenten als specialisten in het team. De manager delegeert duidelijk geformuleerde taken, verzamelt de resultaten van de specialisten en schrijft het eindrapport. Na verloop van tijd zul je verbeteringen zien in betrouwbaarheid, testbaarheid en de mogelijkheid om grote delen van de workflows van ontwikkelaars te automatiseren.