Orkestra: AI-agents orkestreren op schaal

Cijfers in deze post weerspiegelen het systeem op het moment van publicatie (januari 2026). Zie onze teampagina voor actuele cijfers.

Toen we begonnen te bouwen met Claude Code, liepen we tegen een probleem aan dat elk team dat AI-codeerassistenten gebruikt vroeg of laat tegenkomt: één agent kan niet alles goed doen.

Je kunt een agent prompten om een databasespecialist te zijn. Of een securityauditor. Of een frontend-engineer. Maar zodra je hem vraagt alle drie tegelijk te zijn, lijdt de kwaliteit. Context verwatert. Instructies conflicteren. De agent wordt een generalist die overal middelmatig in is.

Dus bouwden we Orkestra.

Wat is Orkestra?

Orkestra is een agent-orchestratiesysteem voor Claude Code en vergelijkbare AI-codeertools. Het coördineert meerdere gespecialiseerde agents, elk met eigen expertise, onder één orchestrator die werk routeert naar de juiste specialist.

Zie het als een uitzendbureau voor AI-agents. De orchestrator ontvangt een taak, identificeert welke specialist die moet afhandelen, en delegeert met de juiste context. Zodra het werk klaar is, vloeien resultaten terug naar de orchestrator voor synthese.

De cijfers vertellen het verhaal:

Component	Aantal
Gespecialiseerde agents	46
Herbruikbare skills	466
Identiteitsarchetypes	27
Mindsets	11
Communicatiestijlen	10
Kennisdomeinen	21

Het karaktersysteem: D&D voor agents

Het kerninzicht achter Orkestra is dat agentgedrag ontstaat uit drie combineerbare primitieven:

Identity definieert wat de agent is. Een architect ontwerpt systeemstructuren. Een debugger traceert fouten naar hun grondoorzaak. Een guardian handhaaft compliance- en beveiligingsgrenzen. We hebben 27 identiteitsarchetypes die gemengd kunnen worden.

Mindset definieert hoe de agent denkt. Een analytische mindset onderbouwt beweringen met bewijs en kwantificeert onzekerheid. Een sceptische mindset stelt aannames ter discussie en zoekt weerleggend bewijs. Een verkennende mindset omarmt ambiguïteit en probeert meerdere aanpakken.

Style definieert hoe de agent communiceert. Een technische stijl bevat exacte waarden en verwijst naar specifieke bestanden. Een beknopte stijl snijdt franje weg en begint met het antwoord. Een diplomatieke stijl balanceert eerlijkheid met tact.

Een agent combineert deze primitieven:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Deze compositie creëert een agent die systemen ontwerpt (architect), kennis verbindt over domeinen heen (knowledge-architect), strategische richting bepaalt (strategist), denkt in bewijs en data (analytical), en communiceert zonder franje (concise).

De kracht zit in combinatorische explosie. 27 identities keer 11 mindsets keer 10 styles levert bijna 3.000 mogelijke agentpersoonlijkheden op. Maar je definieert alleen de combinaties die ertoe doen voor jouw werk.

Skills: herbruikbare capaciteitsmodules

Skills zijn de kennis en workflows die agents kunnen aanroepen. Ze volgen een gelaagd systeem gebaseerd op scope:

Tier	Naam	Scope	Voorbeeld
K0	Foundations	Universele methodologie	Test-first-discipline, bewijsgebaseerde afronding
K1	Identities	Rolgebaseerde workflows	CLI-interfacestandaarden, prestatie-playbook
K2	Domains	Domeinspecifieke kennis	Database-migratiepatronen, authenticatievalidatie
K3	Stacks	Technologiespecifiek	Cloudflare-deployment, Supabase-operaties
K4	Project	Alleen deze codebase	Projectspecifieke workflows en conventies

Skills worden lazy-loaded. Een agent ziet skillnamen en -beschrijvingen bij het opstarten, maar de volledige skillinhoud wordt pas geladen wanneer die wordt getriggerd. Dat houdt de context slank terwijl honderden skills toch vindbaar blijven.

Elke skill bevat:

• Duidelijke triggervoorwaarden (“Use when migrating database schemas”)
• Stap-voor-stap-begeleiding
• Toegestane tools voor de workflow
• Succescriteria en herstelpaden bij falen

De 466 skills in ons register bestrijken alles van git worktree-isolatie tot webresearchworkflows tot deployment health validation.

Waarom orchestratie ertoe doet

Single-agent-architecturen lopen snel tegen muren aan:

Contextverwatering. Een contextvenster van 200k tokens klinkt groot totdat je databaseschema’s, API-documentatie, testfixtures en domeinkennis laadt. Specialisten kunnen werken met gerichte context.

Instructieconflicten. Een agent vertellen om “grondig maar snel” te zijn en “alles te verifiëren maar niet te over-engineeren” creëert spanning. Specialisten lossen dit op door een duidelijke scope te hebben.

Expertisediepgang. Een generalistische agent weet een beetje over alles. Een gespecialiseerde agent, samengesteld met de juiste identity en skills, kent zijn domein diepgaand.

Orkestra implementeert flat orchestration: één orchestrator coördineert meerdere specialisten. Specialisten kunnen geen subspecialisten spawnen. Dat voorkomt complexiteitsexplosie terwijl parallel werk mogelijk blijft.

De orchestrator heeft toegang tot 2,2 miljoen tokens aan effectieve capaciteit: zijn eigen venster van 200k plus 10 gelijktijdige subagents met elk 200k. Werk dat een enkele agent zou uitputten, verloopt moeiteloos over de vloot.

De renderpipeline

Agentdefinities leven in YAML. Claude Code leest Markdown. Orkestra overbrugt dat gat met een deterministische renderpipeline:

YAML Registries → Jinja Templates → .claude/agents/*.md

Operators bewerken de YAML-bron. Voer orkestra sync uit. Gerenderde Markdown verschijnt in .claude/agents/. Claude Code pikt de wijzigingen op.

Deze scheiding bedient verschillende doelgroepen:

• YAML-bron bevat levenscyclusmetadata, tags, validatieregels en deprecation-notities voor tooling
• Gerenderde Markdown bevat alleen wat het model nodig heeft: beschrijving, tools, skills en gedragsrichtlijnen

De pipeline stelt identities, mindsets, styles en skills samen tot één coherente prompt. Een architect-analytical-concise-agent krijgt een heel andere systeemprompt dan een debugger-skeptical-technical-agent, zelfs als ze enkele onderliggende skills delen.

Domeinkennis: het vierbestandenpatroon

Elk kennisdomein volgt een consistente structuur:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Deze structuur dient het laden van agentcontext. Een agent die aan authenticatie werkt, laadt authentication/patterns.md voor begeleiding en authentication/anti-patterns.md om bekende valkuilen te vermijden. De bestanden zijn afgestemd op efficiënt contextladen: gefocust genoeg om nuttig te zijn, uitgebreid genoeg om gezaghebbend te zijn.

We onderhouden 21 topleveldomeinen, waaronder analytics, authenticatie, data science, infrastructuur, machine learning, performance, security en meer. Elk domein kan subdomeinen hebben voor fijnere granulariteit.

Values: het besturingssysteem

Alle agents delen een basislaag aan values die bepalen hoe ze opereren:

Eenvoud eerst. Gebruik de eenvoudigste oplossing die werkt. Voeg alleen complexiteit toe wanneer dat gerechtvaardigd is.

Los grondoorzaken op. Pleister nooit rond falen. Als een pipeline faalt, debug de pipeline. Als een test faalt, repareer de code of de test.

Op bewijs gebaseerd. Label beweringen als “verified” (met benchmarks) of “estimated” (met aannames). Een gedetecteerd patroon staat niet gelijk aan een bevestigd probleem.

Context-economie. MCP-tools kosten 0,1% van de context. Bestanden lezen kost elk 2%. Pas domeinexpertise toe voordat je code gaat verkennen.

Deze values propageren naar elke specialist via de renderpipeline. Een agent kan ze niet omzeilen door compositie.

CLI: het controlevlak

Orkestra wordt geleverd met een CLI voor het beheren van het agent-ecosysteem:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

De CLI is de single source of truth voor welke agents bestaan, welke skills ze hebben, en of het systeem gezond is. Hij draait validatie vóór sync om problemen vroegtijdig op te vangen.

Overwegingen rond open source

We bouwden Orkestra om ons eigen probleem op te lossen: AI-agents op schaal coördineren voor een complexe codebase. De patronen die we ontdekten zijn niet specifiek voor ons domein.

Het karaktercompositiesysteem (identity + mindset + style) is toepasbaar op elk team dat agentpersoonlijkheden definieert.

Het skill-tiersysteem (K0-K4) biedt een mentaal model voor het organiseren van herbruikbare capaciteiten per scope.

Het renderpipelinepatroon (YAML-bron + templates + gegenereerde artefacten) scheidt de belangen tussen tooling en modelconsumptie.

Het flat-orchestration-model (één coördinator, veel specialisten) vermijdt complexiteit terwijl het parallellisme mogelijk maakt.

Of Orkestra open source wordt, hangt af van of deze patronen waarde hebben voor anderen die bouwen met Claude Code. Als jij tegen de muren aanloopt die we hebben beschreven, kan deze architectuur helpen.

Wat we hebben geleerd

Het bouwen van Orkestra leerde ons dat orchestratie niet gaat over agents slimmer maken. Het gaat over ze gefocuster maken.

Eén agent met perfecte instructies raakt nog altijd door zijn context heen. Eén agent met alle skills raakt nog altijd in de war over welke toe te passen. Eén agent die probeert alles te zijn, levert overal middelmatige resultaten.

Veertig specialisten, elk uitstekend in hun domein, gecoördineerd door een orchestrator die weet wanneer te delegeren: zo leveren wij op.

De cijfers doen er minder toe dan de architectuur. Je hebt misschien vijf agents nodig, of vijftig. Het principe blijft: compositie boven capaciteit, specialisatie boven generalisatie, coördinatie boven individueel heldendom.

---

Orkestra vormt de motor achter het agent-ecosysteem van Maguyva, ons code intelligence-platform. Wil je meer weten? Neem contact op met het team.