# Orkestra: tekoälyagenttien orkestrointi laajassa mittakaavassa

Canonical source: https://maguyva.ai/fi/blog/orkestra-agent-orchestration

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Date: 2026-01-06 · Author: Maguyva Team

> Yksi orkestraattori reitittää työtä erikoistuneille tekoälyagenteille, joilla kullakin on omat taitonsa ja muistinsa. Näin Orkestra koordinoi 46 agenttia ja 466 taitoa tuotannossa.

> *Tämän postauksen luvut heijastavat järjestelmää julkaisuhetkellä (tammikuu 2026). Katso [tiimisivumme](/fi/team) ajantasaiset luvut.*

Kun aloimme rakentaa Claude Coden kanssa, törmäsimme ongelmaan, jonka jokainen tekoälykoodausavustimia käyttävä tiimi lopulta kohtaa: yksi agentti ei osaa tehdä kaikkea hyvin.

Voit ohjeistaa agentin olemaan tietokanta-asiantuntija. Tai turvallisuusauditoija. Tai frontend-insinööri. Mutta hetkellä, jolloin pyydät sitä olemaan kaikki kolme samanaikaisesti, laatu kärsii. Konteksti laimenee. Ohjeet ovat ristiriidassa. Agentista tulee yleisosaaja, joka on keskinkertainen kaikessa.

Joten rakensimme Orkestran.

## Mikä on Orkestra?

Orkestra on agenttien orkestrointijärjestelmä Claude Codelle ja vastaaville tekoälykoodaustyökaluille. Se koordinoi useita erikoistuneita agentteja, joilla kullakin on omat asiantuntemusalueensa, yhden orkestraattorin alaisuudessa, joka reitittää työn oikealle erikoisosaajalle.

Ajattele sitä henkilöstövuokrausyrityksenä tekoälyagenteille. Orkestraattori vastaanottaa tehtävän, tunnistaa, minkä erikoisosaajan pitäisi käsitellä se, ja delegoi sen oikealla kontekstilla. Kun työ on valmis, tulokset virtaavat takaisin orkestraattorille synteesiä varten.

Luvut kertovat tarinan:

| Komponentti | Määrä |
|-----------|-------|
| Erikoisosaaja-agentit | 46 |
| Uudelleenkäytettävät taidot | 466 |
| Identiteettiarkkityypit | 27 |
| Ajattelutavat | 11 |
| Kommunikaatiotyylit | 10 |
| Tietämysalueet | 21 |

## Hahmojärjestelmä: D&D agenteille

Orkestran ydinoivallus on se, että agentin käyttäytyminen syntyy kolmesta yhdisteltävästä primitiivistä:

**Identiteetti** määrittelee, *mitä* agentti on. Arkkitehti suunnittelee järjestelmärakenteita. Debuggaaja jäljittää epäonnistumiset juurisyihin. Vartija valvoo vaatimustenmukaisuutta ja turvallisuusrajoja. Meillä on 27 identiteettiarkkityyppiä, joita voi sekoittaa.

**Ajattelutapa** määrittelee, *miten* agentti ajattelee. Analyyttinen ajattelutapa perustaa väitteet todisteisiin ja kvantifioi epävarmuutta. Skeptinen ajattelutapa kyseenalaistaa oletukset ja etsii kumoavaa todistusaineistoa. Tutkiva ajattelutapa omaksuu epäselvyyden ja kokeilee useita lähestymistapoja.

**Tyyli** määrittelee, *miten* agentti kommunikoi. Tekninen tyyli sisältää tarkat arvot ja viittaa tiettyihin tiedostoihin. Ytimekäs tyyli karsii täytteen ja aloittaa vastauksesta. Diplomaattinen tyyli tasapainottaa rehellisyyden tahdikkuuden kanssa.

Agentti yhdistää nämä primitiivit:

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

Tämä kokoonpano luo agentin, joka suunnittelee järjestelmiä (arkkitehti), yhdistää tietämystä toimialueiden yli (tietämysarkkitehti), asettaa strategisen suunnan (strategisti), ajattelee todisteina ja datana (analyyttinen) ja kommunikoi ilman täytettä (ytimekäs).

Voima on yhdistelmien räjähdysmäisessä määrässä. 27 identiteettiä kertaa 11 ajattelutapaa kertaa 10 tyyliä tuottaa lähes 3 000 mahdollista agenttipersoonallisuutta. Mutta määrittelet vain ne yhdistelmät, jotka merkitsevät työllesi.

## Taidot: uudelleenkäytettävät kyvykkyysmoduulit

Taidot ovat tietämystä ja työnkulkuja, joita agentit voivat kutsua. Ne noudattavat porrastettua järjestelmää laajuuden perusteella:

| Taso | Nimi | Laajuus | Esimerkki |
|------|------|-------|---------|
| K0 | Perusta | Universaali metodologia | Testivetoinen kuri, näyttöön perustuva valmistuminen |
| K1 | Identiteetit | Roolipohjaiset työnkulut | CLI-rajapintastandardit, suorituskykykäsikirja |
| K2 | Toimialueet | Toimialuekohtainen tietämys | Tietokannan migraatiomallit, todennuksen validointi |
| K3 | Pinot | Teknologiakohtainen | Cloudflare-käyttöönotto, Supabase-operaatiot |
| K4 | Projekti | Vain tämä koodikanta | Projektikohtaiset työnkulut ja käytännöt |

Taidot ladataan laiskasti. Agentti näkee taitojen nimet ja kuvaukset käynnistyksessä, mutta täysi taitosisältö latautuu vasta laukaisuhetkellä. Tämä pitää kontekstin kevyenä ja tekee samalla sadoista taidoista löydettäviä.

Jokainen taito sisältää:
- Selkeät laukaisuehdot ("Käytä tietokantaskeemoja migroitaessa")
- Askel askeleelta -ohjeistuksen
- Työnkululle sallitut työkalut
- Onnistumiskriteerit ja epäonnistumisen palautumispolut

Rekisterimme 466 taitoa kattavat kaiken git-worktree-eristyksestä web-tutkimustyönkulkuihin ja käyttöönoton terveystarkistuksiin.

## Miksi orkestrointi merkitsee

Yhden agentin arkkitehtuurit törmäävät seiniin nopeasti:

**Kontekstin laimeneminen.** 200k tokenin kontekstiikkuna kuulostaa suurelta, kunnes lataat tietokantaskeemoja, API-dokumentaatiota, testifixtureita ja toimialuetietämystä. Erikoisosaajat voivat työskennellä kohdennetulla kontekstilla.

**Ohjeiden ristiriidat.** Agentin ohjeistaminen olemaan "perusteellinen mutta nopea" ja "tarkista kaikki, mutta älä yliteknisoi" luo jännitteen. Erikoisosaajat ratkaisevat tämän selkeällä laajuudella.

**Asiantuntemuksen syvyys.** Yleisosaaja-agentti tietää vähän kaikesta. Erikoisosaaja-agentti, oikean identiteetin ja taitojen kanssa koottuna, tuntee toimialueensa syvällisesti.

Orkestra toteuttaa litteän orkestroinnin: yksi orkestraattori koordinoi useita erikoisosaajia. Erikoisosaajat eivät voi synnyttää alaerikoisosaajia. Tämä estää monimutkaisuuden räjähdyksen samalla kun se mahdollistaa rinnakkaisen työn.

Orkestraattorilla on pääsy 2,2 miljoonaan tokeniin tehokasta kapasiteettia: sen oma 200k ikkuna plus 10 samanaikaista alaagenttia, joilla kullakin on 200k. Työ, joka kuluttaisi yhden agentin loppuun, kulkee mukavasti koko laivueen yli.

## Renderöintiputki

Agenttimäärittelyt elävät YAML:ssä. Claude Code lukee Markdownia. Orkestra siltaa tämän kuilun deterministisellä renderöintiputkella:

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

Operaattorit muokkaavat YAML-lähdettä. Ajavat `orkestra sync`:n. Renderöity Markdown ilmestyy kohtaan `.claude/agents/`. Claude Code ottaa muutokset käyttöön.

Tämä erottelu palvelee eri yleisöjä:
- **YAML-lähde** sisältää elinkaarimetadataa, tageja, validointisääntöjä ja vanhentumishuomautuksia työkaluille
- **Renderöity Markdown** sisältää vain sen, mitä malli tarvitsee: kuvauksen, työkalut, taidot ja käyttäytymisohjeistuksen

Putki kokoaa identiteetit, ajattelutavat, tyylit ja taidot yhdeksi yhtenäiseksi kehotteeksi. Arkkitehti-analyyttinen-ytimekäs-agentti saa hyvin erilaisen järjestelmäkehotteen kuin debuggaaja-skeptinen-tekninen-agentti, vaikka ne jakaisivat joitakin taustalla olevia taitoja.

## Toimialuetietämys: neljän tiedoston malli

Jokainen tietämysalue noudattaa yhtenäistä rakennetta:

```
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
```

Tämä rakenne palvelee agentin kontekstin lataamista. Todennuksen parissa työskentelevä agentti lataa `authentication/patterns.md`:n ohjeistusta varten ja `authentication/anti-patterns.md`:n tunnettujen sudenkuoppien välttämiseksi. Tiedostot on mitoitettu tehokasta kontekstin lataamista varten: tarpeeksi kohdennettuja ollakseen hyödyllisiä, tarpeeksi kattavia ollakseen auktoritatiivisia.

Ylläpidämme 21 ylätason toimialuetta, mukaan lukien analytiikka, todennus, data science, infrastruktuuri, koneoppiminen, suorituskyky, turvallisuus ja muut. Jokaisella toimialueella voi olla alitoimialueita hienojakoisempaa tarkkuutta varten.

## Arvot: käyttöjärjestelmä

Kaikki agentit jakavat perusarvokerroksen, joka määrittelee, miten ne toimivat:

**Yksinkertaisuus edellä.** Käytä yksinkertaisinta ratkaisua, joka toimii. Lisää monimutkaisuutta vain perustellusti.

**Korjaa juurisyyt.** Älä koskaan tyydy peittämään virheitä. Jos putki epäonnistuu, debuggaa putki. Jos testi epäonnistuu, korjaa koodi tai testi.

**Näyttöön perustuva.** Merkitse väitteet "varmennetuksi" (vertailuarvoilla) tai "arvioiduksi" (oletuksilla). Havaittu kuvio ei tarkoita vahvistettua ongelmaa.

**Kontekstitalous.** MCP-työkalut maksavat 0,1 % kontekstista. Tiedostojen lukeminen maksaa 2 % kukin. Sovella toimialueasiantuntemusta ennen koodin tutkimista.

Nämä arvot leviävät jokaiseen erikoisosaajaan renderöintiputken kautta. Agentti ei voi ohittaa niitä kokoonpanon kautta.

## CLI: ohjaustaso

Orkestra toimitetaan CLI:llä agenttiekosysteemin hallintaan:

```bash
# 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 on totuuden lähde sille, mitä agentteja on olemassa, mitä taitoja niillä on ja onko järjestelmä terve. Se ajaa validoinnin ennen synkronointia ongelmien varhaiseksi kiinni saamiseksi.

## Avoimen lähdekoodin näkökohdat

Rakensimme Orkestran ratkaisemaan oman ongelmamme: tekoälyagenttien koordinoinnin laajassa mittakaavassa monimutkaiselle koodikannalle. Löytämämme mallit eivät ole erityisiä toimialueellemme.

Hahmojen kokoonpanojärjestelmä (identiteetti + ajattelutapa + tyyli) soveltuu mille tahansa tiimille, joka määrittelee agenttipersoonallisuuksia.

Taitojen tasojärjestelmä (K0–K4) tarjoaa mentaalisen mallin uudelleenkäytettävien kyvykkyyksien järjestämiseen laajuuden mukaan.

Renderöintiputken malli (YAML-lähde + templatet + generoidut artefaktit) erottaa työkalujen tarvitsemat tiedot mallin käyttämästä sisällöstä.

Litteä orkestrointimalli (yksi koordinaattori, monta erikoisosaajaa) välttää monimutkaisuuden mahdollistaen samalla rinnakkaisuuden.

Tuleeko Orkestrasta avoimen lähdekoodin projekti, riippuu siitä, onko näillä malleilla arvoa muille, jotka rakentavat Claude Coden kanssa. Jos törmäät kuvaamiimme seiniin, arkkitehtuuri saattaa auttaa.

## Mitä opimme

Orkestran rakentaminen opetti meille, ettei orkestrointi tarkoita agenttien tekemistä älykkäämmiksi. Se tarkoittaa niiden tekemistä keskittyneemmiksi.

Täydellisilläkin ohjeilla toimivan yksittäisen agentin konteksti loppuu silti kesken. Yksi agentti kaikilla taidoilla silti hämmentyy siitä, mitä soveltaa. Yksi agentti, joka yrittää olla kaikkea, tuottaa keskinkertaisia tuloksia kaikkialla.

Neljäkymmentä erikoisosaajaa, kukin erinomainen toimialueellaan, koordinoituna orkestraattorilla, joka tietää milloin delegoida: näin me toimitamme.

Luvut merkitsevät vähemmän kuin arkkitehtuuri. Saatat tarvita viisi agenttia tai viisikymmentä. Periaate pysyy: kokoonpano kyvykkyyden sijaan, erikoistuminen yleisosaamisen sijaan, koordinointi yksilöllisen sankaruuden sijaan.

---

*Orkestra tehostaa Maguyva-palvelun, koodiälyalustamme, takana olevaa agenttiekosysteemiä. Haluatko tietää lisää? Ota yhteyttä tiimiin.*