Orkestra: orkiestracja agentów AI na dużą skalę

Liczby w tym wpisie odzwierciedlają system w momencie publikacji (styczeń 2026). Aktualne dane znajdziesz na naszej stronie zespołu.

Gdy zaczęliśmy budować z Claude Code, natrafiliśmy na problem, z którym prędzej czy później mierzy się każdy zespół korzystający z asystentów kodujących AI: jeden agent nie potrafi robić wszystkiego dobrze.

Możesz podpowiedzieć agentowi, żeby był specjalistą od baz danych. Albo audytorem bezpieczeństwa. Albo inżynierem frontendu. Ale w chwili, gdy poprosisz go, żeby był tymi trzema naraz, jakość spada. Kontekst się rozmywa. Instrukcje wchodzą w konflikt. Agent staje się generalistą, który jest przeciętny we wszystkim.

Więc zbudowaliśmy Orkestrę.

Czym jest Orkestra?

Orkestra to system orkiestracji agentów dla Claude Code i podobnych narzędzi AI do kodowania. Koordynuje wielu wyspecjalizowanych agentów, każdego z odrębną ekspertyzą, pod jednym orkiestratorem, który kieruje pracę do właściwego specjalisty.

Pomyśl o tym jak o agencji zatrudnienia dla agentów AI. Orkiestrator otrzymuje zadanie, identyfikuje, który specjalista powinien się nim zająć, i deleguje z właściwym kontekstem. Gdy praca jest gotowa, wyniki wracają do orkiestratora do syntezy.

Liczby mówią same za siebie:

Komponent	Liczba
Agenci specjalistyczni	46
Skille wielokrotnego użytku	466
Archetypy tożsamości	27
Sposoby myślenia (mindsety)	11
Style komunikacji	10
Domeny wiedzy	21

System charakteru: D&D dla agentów

Kluczową obserwacją stojącą za Orkestrą jest to, że zachowanie agenta wyłania się z trzech komponowalnych prymitywów:

Tożsamość definiuje, czym jest agent. Architekt projektuje struktury systemowe. Debugger śledzi awarie do ich pierwotnych przyczyn. Guardian egzekwuje zgodność i granice bezpieczeństwa. Mamy 27 archetypów tożsamości, które można mieszać.

Mindset definiuje, jak agent myśli. Analityczny mindset zakotwicza twierdzenia w dowodach i kwantyfikuje niepewność. Sceptyczny mindset kwestionuje założenia i szuka dowodów obalających. Eksploracyjny mindset akceptuje niejednoznaczność i próbuje wielu podejść.

Styl definiuje, jak agent się komunikuje. Techniczny styl zawiera dokładne wartości i odwołuje się do konkretnych plików. Zwięzły styl obcina ozdobniki i zaczyna od odpowiedzi. Dyplomatyczny styl równoważy szczerość z taktem.

Agent łączy te prymitywy:

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

Ta kompozycja tworzy agenta, który projektuje systemy (architekt), łączy wiedzę między domenami (knowledge-architect), wyznacza kierunek strategiczny (strategist), myśli w kategoriach dowodów i danych (analityczny) i komunikuje się bez ozdobników (zwięzły).

Moc tkwi w eksplozji kombinatorycznej. 27 tożsamości razy 11 mindsetów razy 10 stylów daje prawie 3000 możliwych osobowości agentów. Ale definiujesz tylko te kombinacje, które mają znaczenie dla Twojej pracy.

Skille: wielokrotnego użytku moduły zdolności

Skille to wiedza i przepływy pracy, które agenci mogą wywoływać. Podlegają wielopoziomowemu systemowi opartemu na zakresie:

Poziom	Nazwa	Zakres	Przykład
K0	Fundamenty	Uniwersalna metodologia	Dyscyplina test-first, ukończenie oparte na dowodach
K1	Tożsamości	Przepływy pracy oparte na roli	Standardy interfejsu CLI, playbook wydajności
K2	Domeny	Wiedza specyficzna dla domeny	Wzorce migracji baz danych, walidacja uwierzytelniania
K3	Stosy	Specyficzne dla technologii	Wdrożenie Cloudflare, operacje Supabase
K4	Projekt	Tylko ta baza kodu	Przepływy pracy i konwencje specyficzne dla projektu

Skille są ładowane leniwie (lazy-loaded). Agent widzi nazwy i opisy skilli przy starcie, ale pełna treść skilla wczytuje się dopiero po wywołaniu. To utrzymuje kontekst szczupły, jednocześnie czyniąc setki skilli odkrywalnymi.

Każdy skill zawiera:

• Jasne warunki wyzwalające („Użyj podczas migracji schematów bazy danych”)
• Wskazówki krok po kroku
• Dozwolone narzędzia dla przepływu pracy
• Kryteria sukcesu i ścieżki odzyskiwania po niepowodzeniu

466 skilli w naszym rejestrze obejmuje wszystko, od izolacji git worktree po przepływy pracy badań webowych po walidację kondycji wdrożenia.

Dlaczego orkiestracja ma znaczenie

Architektury jednoagentowe szybko trafiają na ściany:

Rozmycie kontekstu. Okno kontekstu 200 tys. tokenów brzmi ogromnie, dopóki nie wczytasz schematów baz danych, dokumentacji API, fixture’ów testowych i wiedzy domenowej. Specjaliści mogą pracować z celowanym kontekstem.

Konflikty instrukcji. Powiedzenie agentowi „bądź dokładny, ale szybki” i „zweryfikuj wszystko, ale nie przeinżynieruj” tworzy napięcie. Specjaliści rozwiązują to, mając jasny zakres.

Głębia ekspertyzy. Agent generalista wie trochę o wszystkim. Agent specjalista, złożony z właściwej tożsamości i skilli, zna swoją domenę głęboko.

Orkestra implementuje płaską orkiestrację: jeden orkiestrator koordynuje wielu specjalistów. Specjaliści nie mogą tworzyć sub-specjalistów. To zapobiega eksplozji złożoności, jednocześnie umożliwiając pracę równoległą.

Orkiestrator ma dostęp do 2,2 miliona tokenów efektywnej pojemności: własne okno 200 tys. plus 10 równoczesnych subagentów po 200 tys. każdy. Praca, która wyczerpałaby jednego agenta, przebiega swobodnie w całej flocie.

Pipeline renderowania

Definicje agentów żyją w YAML. Claude Code czyta Markdown. Orkestra pomostuje tę różnicę deterministycznym pipeline’em renderowania:

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

Operatorzy edytują źródło YAML. Uruchamiają orkestra sync. Wyrenderowany Markdown pojawia się w .claude/agents/. Claude Code odbiera zmiany.

To rozdzielenie służy różnym odbiorcom:

• Źródło YAML zawiera metadane cyklu życia, tagi, reguły walidacji i notatki o wycofaniu na potrzeby narzędzi
• Wyrenderowany Markdown zawiera tylko to, czego potrzebuje model: opis, narzędzia, skille i wskazówki behawioralne

Pipeline składa tożsamości, mindsety, style i skille w jeden spójny prompt. Agent architekt-analityczny-zwięzły otrzymuje bardzo inny prompt systemowy niż agent debugger-sceptyczny-techniczny, nawet jeśli dzielą część leżących u podstaw skilli.

Wiedza domenowa: wzorzec czterech plików

Każda domena wiedzy podąża za spójną 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

Ta struktura służy wczytywaniu kontekstu agenta. Agent pracujący nad uwierzytelnianiem wczytuje authentication/patterns.md dla wskazówek i authentication/anti-patterns.md, by unikać znanych pułapek. Pliki są rozmiarowane pod efektywne wczytywanie kontekstu: wystarczająco skupione, by być użyteczne, wystarczająco wyczerpujące, by być autorytatywne.

Utrzymujemy 21 domen najwyższego poziomu, w tym analitykę, uwierzytelnianie, data science, infrastrukturę, uczenie maszynowe, wydajność, bezpieczeństwo i inne. Każda domena może mieć poddomeny dla drobniejszej granularności.

Wartości: system operacyjny

Wszyscy agenci dzielą bazową warstwę wartości, która definiuje, jak działają:

Prostota przede wszystkim. Używaj najprostszego rozwiązania, które działa. Dodawaj złożoność tylko wtedy, gdy jest uzasadniona.

Napraw pierwotne przyczyny. Nigdy nie łataj obejściami awarii. Jeśli pipeline zawodzi, debuguj pipeline. Jeśli test zawodzi, napraw kod albo test.

Oparte na dowodach. Oznaczaj twierdzenia jako „zweryfikowane” (z benchmarkami) lub „szacowane” (z założeniami). Wykryty wzorzec nie równa się potwierdzonemu problemowi.

Ekonomia kontekstu. Narzędzia MCP kosztują 0,1% kontekstu. Odczyty plików kosztują po 2% każdy. Zastosuj ekspertyzę domenową, zanim zaczniesz eksplorować kod.

Te wartości propagują się do każdego specjalisty przez pipeline renderowania. Agent nie może ich obejść przez kompozycję.

CLI: płaszczyzna kontroli

Orkestra dostarczana jest z CLI do zarządzania ekosystemem agentów:

# 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 jest źródłem prawdy o tym, jakie agenty istnieją, jakie mają skille i czy system jest zdrowy. Uruchamia walidację przed synchronizacją, żeby wcześnie wychwycić problemy.

Rozważania dotyczące open source

Zbudowaliśmy Orkestrę, żeby rozwiązać nasz własny problem: koordynację agentów AI na dużą skalę dla złożonej bazy kodu. Wzorce, które odkryliśmy, nie są specyficzne dla naszej domeny.

System kompozycji charakteru (tożsamość + mindset + styl) ma zastosowanie do każdego zespołu definiującego osobowości agentów.

System poziomów skilli (K0-K4) dostarcza modelu mentalnego do organizowania wielokrotnego użytku zdolności według zakresu.

Wzorzec pipeline’u renderowania (źródło YAML + szablony + wygenerowane artefakty) rozdziela odpowiedzialności między narzędzia a konsumpcję przez model.

Płaski model orkiestracji (jeden koordynator, wielu specjalistów) unika eksplozji złożoności, jednocześnie umożliwiając równoległość.

Czy Orkestra stanie się open source, zależy od tego, czy te wzorce mają wartość dla innych budujących z Claude Code. Jeśli trafiasz na te same ściany, które opisaliśmy, ta architektura może pomóc.

Czego się nauczyliśmy

Budowanie Orkestry nauczyło nas, że orkiestracja nie polega na czynieniu agentów mądrzejszymi. Polega na czynieniu ich bardziej skupionymi.

Pojedynczy agent z idealnymi instrukcjami wciąż wyczerpuje kontekst. Pojedynczy agent ze wszystkimi skillami wciąż gubi się w tym, który zastosować. Pojedynczy agent próbujący być wszystkim produkuje przeciętne wyniki wszędzie.

Czterdziestu specjalistów, każdy doskonały w swojej domenie, koordynowanych przez orkiestratora, który wie, kiedy delegować: tak dostarczamy.

Liczby mają mniejsze znaczenie niż architektura. Możesz potrzebować pięciu agentów albo pięćdziesięciu. Zasada pozostaje: kompozycja ponad zdolność, specjalizacja ponad generalizację, koordynacja ponad indywidualne bohaterstwo.

---

Orkestra napędza ekosystem agentów stojący za Maguyva, naszą platformą inteligencji kodu. Chcesz dowiedzieć się więcej? Skontaktuj się z zespołem.