Orkestra: att orkestrera AI-agenter i stor skala

När vi började bygga med Claude Code stötte vi på ett problem som alla team som använder AI-kodningsassistenter förr eller senare möter: en enda agent kan inte göra allt bra.

Man kan prompta en agent att vara en databasspecialist. Eller en säkerhetsgranskare. Eller en frontend-ingenjör. Men i samma stund man ber den vara alla tre samtidigt sjunker kvaliteten. Kontexten späds ut. Instruktioner krockar. Agenten blir en generalist som är medioker på allt.

Så vi byggde Orkestra.

Vad är Orkestra?

Orkestra är ett agentorkestreringssystem för Claude Code och liknande AI-kodningsverktyg. Det koordinerar flera specialiserade agenter, var och en med egen expertis, under en enda orkestrerare som dirigerar arbete till rätt specialist.

Tänk på det som en bemanningsbyrå för AI-agenter. Orkestreraren tar emot en uppgift, identifierar vilken specialist som bör hantera den, och delegerar med rätt kontext. När arbetet är klart flödar resultaten tillbaka till orkestreraren för sammanställning.

Siffrorna berättar historien:

Komponent	Antal
Specialistagenter	46
Återanvändbara skills	466
Identitetsarketyper	27
Mindset	11
Kommunikationsstilar	10
Kunskapsdomäner	21

Karaktärssystemet: D&D för agenter

Den centrala insikten bakom Orkestra är att agentbeteende uppstår ur tre komponerbara primitiver:

Identitet definierar vad agenten är. En arkitekt designar systemstrukturer. En debugger spårar fel till grundorsaken. En guardian upprätthåller efterlevnad och säkerhetsgränser. Vi har 27 identitetsarketyper som kan kombineras.

Mindset definierar hur agenten tänker. Ett analytiskt mindset förankrar påståenden i bevis och kvantifierar osäkerhet. Ett skeptiskt mindset ifrågasätter antaganden och söker motbevisande fakta. Ett utforskande mindset omfamnar tvetydighet och prövar flera angreppssätt.

Stil definierar hur agenten kommunicerar. En teknisk stil inkluderar exakta värden och refererar till specifika filer. En koncis stil skär bort fluff och leder med svaret. En diplomatisk stil balanserar ärlighet med takt.

En agent kombinerar de här primitiverna:

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

Den här kompositionen skapar en agent som designar system (arkitekt), knyter ihop kunskap över domäner (kunskapsarkitekt), sätter strategisk riktning (strateg), tänker i bevis och data (analytisk), och kommunicerar utan fluff (koncis).

Kraften ligger i den kombinatoriska explosionen. 27 identiteter gånger 11 mindset gånger 10 stilar ger nästan 3 000 möjliga agentpersonligheter. Men man definierar bara de kombinationer som spelar roll för ens arbete.

Skills: återanvändbara förmågemoduler

Skills är den kunskap och de arbetsflöden agenter kan åberopa. De följer ett nivåsystem baserat på scope:

Nivå	Namn	Scope	Exempel
K0	Grunder	Universell metodik	Testdriven disciplin, evidensbaserad slutförande
K1	Identiteter	Rollbaserade arbetsflöden	CLI-gränssnittsstandarder, prestandaplaybook
K2	Domäner	Domänspecifik kunskap	Databasmigreringsmönster, autentiseringsvalidering
K3	Stackar	Teknikspecifikt	Cloudflare-driftsättning, Supabase-drift
K4	Projekt	Endast den här kodbasen	Projektspecifika arbetsflöden och konventioner

Skills laddas lazy. En agent ser skill-namn och beskrivningar vid start, men fullt skill-innehåll laddas bara när det utlöses. Det håller kontexten mager samtidigt som hundratals skills görs upptäckbara.

Varje skill innehåller:

• Tydliga utlösarvillkor (“Använd när du migrerar databasscheman”)
• Steg-för-steg-vägledning
• Tillåtna verktyg för arbetsflödet
• Framgångskriterier och återhämtningsvägar vid fel

De 466 skills i vårt register täcker allt från git worktree-isolering till webbresearcharbetsflöden till driftsättningshälsovalidering.

Varför orkestrering spelar roll

Arkitekturer med en enda agent stöter snabbt på väggar:

Kontextutspädning. Ett kontextfönster på 200 000 tokens låter stort ända tills man laddar in databasscheman, API-dokumentation, testfixturer och domänkunskap. Specialister kan arbeta med riktad kontext.

Instruktionskonflikter. Att be en agent “vara grundlig men snabb” och “verifiera allt men inte överkonstruera” skapar spänning. Specialister löser det genom att ha tydligt scope.

Expertisdjup. En generalistagent kan lite om allt. En specialistagent, komponerad med rätt identitet och skills, kan sin domän djupt.

Orkestra implementerar platt orkestrering: en orkestrerare koordinerar flera specialister. Specialister kan inte skapa underspecialister. Det förhindrar en komplexitetsexplosion samtidigt som det möjliggör parallellt arbete.

Orkestreraren har tillgång till 2,2 miljoner tokens effektiv kapacitet: sitt eget fönster på 200 000 plus 10 samtidiga subagenter med 200 000 var. Arbete som skulle tömma en enda agent löper bekvämt genom flottan.

Renderingspipelinen

Agentdefinitioner lever i YAML. Claude Code läser Markdown. Orkestra överbryggar det gapet med en deterministisk renderingspipeline:

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

Operatörer redigerar YAML-källan. Kör orkestra sync. Renderad Markdown dyker upp i .claude/agents/. Claude Code tar upp ändringarna.

Den här separationen tjänar olika målgrupper:

• YAML-källan innehåller livscykelmetadata, taggar, valideringsregler och utfasningsnoteringar för tooling
• Renderad Markdown innehåller bara det modellen behöver: beskrivning, verktyg, skills och beteendevägledning

Pipelinen komponerar identiteter, mindset, stilar och skills till en enda sammanhängande prompt. En arkitekt-analytisk-koncis-agent får en helt annan systemprompt än en debugger-skeptisk-teknisk-agent, även om de delar en del underliggande skills.

Domänkunskap: fyrafilsmönstret

Varje kunskapsdomän följer en konsekvent struktur:

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

Den här strukturen betjänar agentens kontextladdning. En agent som arbetar med autentisering laddar authentication/patterns.md för vägledning och authentication/anti-patterns.md för att undvika kända fallgropar. Filerna är dimensionerade för effektiv kontextladdning: tillräckligt fokuserade för att vara användbara, tillräckligt heltäckande för att vara auktoritativa.

Vi underhåller 21 toppnivådomäner, bland annat analys, autentisering, datavetenskap, infrastruktur, maskininlärning, prestanda, säkerhet och mer. Varje domän kan ha underdomäner för finare granularitet.

Värderingar: operativsystemet

Alla agenter delar ett bottenlager av värderingar som definierar hur de opererar:

Enkelhet först. Använd den enklaste lösningen som fungerar. Lägg bara till komplexitet när det är motiverat.

Åtgärda grundorsaker. Lappa aldrig runt fel. Om en pipeline misslyckas, felsök pipelinen. Om ett test misslyckas, åtgärda koden eller testet.

Evidensbaserat. Märk påståenden som “verifierat” (med benchmarks) eller “uppskattat” (med antaganden). Ett upptäckt mönster är inte detsamma som ett bekräftat problem.

Kontextekonomi. MCP-verktyg kostar 0,1 % av kontexten. Filläsningar kostar 2 % var. Tillämpa domänexpertis innan koden utforskas.

De här värderingarna sprids till varje specialist genom renderingspipelinen. En agent kan inte kringgå dem genom komposition.

CLI:t: kontrollplanet

Orkestra levereras med ett CLI för att hantera agentekosystemet:

# 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"

CLI:t är sanningskällan för vilka agenter som finns, vilka skills de har, och om systemet är friskt. Det kör validering före synk för att fånga problem tidigt.

Överväganden kring öppen källkod

Vi byggde Orkestra för att lösa vårt eget problem: att koordinera AI-agenter i stor skala för en komplex kodbas. Mönstren vi upptäckte är inte specifika för vår domän.

Karaktärskompositionssystemet (identitet + mindset + stil) gäller för alla team som definierar agentpersonligheter.

Skill-nivåsystemet (K0–K4) ger en mental modell för att organisera återanvändbara förmågor efter scope.

Renderingspipelinemönstret (YAML-källa + mallar + genererade artefakter) separerar tooling-hänsyn från modellkonsumtion.

Den platta orkestreringsmodellen (en koordinator, många specialister) undviker komplexitet samtidigt som den möjliggör parallellism.

Om Orkestra blir öppen källkod beror på om de här mönstren har värde för andra som bygger med Claude Code. Om du stöter på väggarna vi beskrev kan arkitekturen kanske hjälpa.

Vad vi lärde oss

Att bygga Orkestra lärde oss att orkestrering inte handlar om att göra agenter smartare. Det handlar om att göra dem mer fokuserade.

En enda agent med perfekta instruktioner tar ändå slut på kontext. En enda agent med alla skills blir ändå förvirrad över vilken som ska tillämpas. En enda agent som försöker vara allt ger medioker resultat överallt.

Fyrtio specialister, var och en excellent inom sin domän, koordinerade av en orkestrerare som vet när den ska delegera: så levererar vi.

Siffrorna spelar mindre roll än arkitekturen. Man kanske behöver fem agenter eller femtio. Principen kvarstår: komposition före kapacitet, specialisering före generalisering, koordination före enskilda hjältedåd.

---

Orkestra driver agentekosystemet bakom Maguyva, vår kodintelligensplattform. Vill du veta mer? Hör av dig till teamet.