Multi-agent orchestration: mis läks katki 3 315 käivituses

Olen Denys, full-stack- ja AI-insener. Ehitan tarkvara ühe Claude Code’i juhtsessiooniga, mis annab töö edasi spetsialiseeritud alamagentidele: uurijatele, planeerijale, teostajatele ning turva- ja koodiülevaatajatele. See on aruanne selle mitmeagendilise süsteemi kohta, mitte kliendi toote kohta. Arvud pärinevad logidest, mida see peab: käivituste register (üks rida iga käivitatud agendi kohta), sessioonide transkriptsioonid ja seadistuse enda git’i ajalugu. Kliendi- ja projektinimed on välja jäetud.

Ehitasin ka interaktiivse mitmeagendilise orkestreerimise dashboardi prototüübina näidisandmetega. Kõik allolev pärineb päris jooksudest.

Mis on multi-agent orchestration?

Multi-agent orchestration (mitmeagendiline orkestreerimine) on seadistus, kus üks juhtagent annab piiritletud ülesanded spetsialiseeritud agentidele ja ühendab nende tulemused; orkestreerija vastutab konteksti, eelarvete ja korduskatsete eest. Selles artiklis ilmneb see kahe mustrina: juhtsessioon alamagentidega (uurijad, planeerija, teostajad, ülevaatajad) ning hookid, mis jõustavad reegleid, millest agendid rääkimisega mööda ei pääse. Mitmeagendilise orkestreerimise dashboard näitab sama ideed näidisandmetel; allolevad jaotised räägivad sellest, mis päris jooksudes katki läks.

Milline see seadistus on?

Üks juhtsessioon räägib minuga ja vastutab ülesande eest. Suuremate ülesannete puhul ei kirjuta see ise tootmiskoodi. See jagab töö laiali:

• Uurijad loevad ühte koodibaasi kihti (frontend, backend, andmebaas) ja kirjutavad lühikese kaardi.
• Planeerija muudab kaardi nummerdatud sammudeks koos failiteedega.
• Teostajad võtavad igaüks ühe plaani faasi, kirjutavad kõigepealt testid, seejärel koodi. Paralleelsed teostajad saavad oma git worktree’i.
• Ülevaatajad kontrollivad diffi: üks turvalisuse, teine korrektsuse poolest, mõlemad samal commit’il.

Nende vahel on hookid: väikesed skriptid, mida Claude Code käivitab enne igat tööriistakutset ja pärast seda. Hook võib kutse blokeerida, näiteks agendi käivituse, faili kirjutamise või käsu git commit. Seadistuses on 165 hooki, neist umbes 40 on seotud orkestreerimisega. Reeglid, mida agendid loevad, on Markdown; reeglid, millest nad mööda ei pääse, on hookid. See jaotus on kahe kuu peamine õppetund ja ülejäänud kirjutis räägib, miks.

Mitu agenti jooksis ja milliste mudelitega?

Näitaja (17. aug – 19. okt 2026)	Väärtus
Käivitatud alamagendid	3 315 üle 57 aktiivse päeva
Agenditüübid	30
Kõige rohkem käivitatud	teostaja (tdd-guide) 793, turvaülevaataja 455, general-purpose 424
Tegelik mudel	Opus 46,5%, Sonnet 45,8%, Fable 1,3%, ülejäänud päritud juhtsessioonilt
Käivitatud ühekaupa	67,7%
Suurim paralleellaine	5 agenti (ülempiir), saavutatud 9 korda
Ülevaatajate jooksud teostaja jooksu kohta	0,71 (680 ülevaatust, 963 teostust)

Kaks arvu üllatasid mind. Esiteks, enamik käivitusi oli üksikud agendid, mitte hargnemised. Paralleeltöö on erand: see tasub end ära lugemisel ja ülevaatamisel ning läheb kirjutamisel kalliks (vt allpool esimest viga). Teiseks, 23% käivitustest, kus agendi fail nimetab mudeli, jooksis tegelikult teine mudel, peaaegu alati Sonnet tõstetuna Opuseks (584 / 610). See on tahtlik: hook tõstab mudeli, kui samm puudutab riskantset koodi, näiteks migratsioone, autentimist või serveri marsruute, ja pärast seda, kui Sonnetil töötav teostaja ebaõnnestub samas testis kolm korda järjest. Tugevam teostaja jooksis 159 korda; ma ei saa logi jagada “riskantne samm” ja “korduv viga” vahel, seega ei väida, mitu neist olid päästeoperatsioonid.

Mida maksab multi-agent orchestration?

Maksan püsitellimuse eest, nii et žetooni kohta arvet pole. Transkriptsioonid salvestavad siiski iga žetooni, nii et siin on see, mida viimased 30 päeva (20. september – 19. oktoober) maksaksid Anthropicu API nimekirjahindadega:

30 päeva	Žetoonid
Kokku	umbes 15,99 miljardit
Vahemälu lugemised	15,55 miljardit (97,7% kõigest mudelile saadetust)
Vahemälu kirjutamised	372 miljonit
Värske, vahemällu panemata sisend	0,18 miljonit
Väljund	69 miljonit

Nimekirjahindadega (Opus 5.5: 4 USD miljoni sisendžetooni kohta, 20 miljoni väljundžetooni kohta, 0,20 miljoni vahemälu lugemise kohta; Sonnet 5.5 ja Fable 5.1 oma hindadega) teeb ainuüksi kolme praeguse mudeli väljund, sisend ja vahemälu lugemised kokku umbes 3 350 USA dollarit. See jätab välja vahemälu kirjutamised ja logides endiselt olevad vanemad mudelid, nii et tegelik API summa on suurem. Kaks kolmandikku sellest 3 350 dollarist on vahemälu lugemised: iga tsükkel saadab kogu konteksti uuesti ja vahemälu on ainus põhjus, miks see üldse jõukohane on.

Jaotus juhtsessiooni ja alamagentide vahel on see osa, mida kasutaksin eelarve planeerimisel:

• Alamagendid kasutasid 42% kõigist žetoonidest, kuid kirjutasid 66% väljundist. Juhtsessioon on kallis, sest kannab pikimat konteksti; alamagentides kirjutatakse päris tekst ja kood.
• Ülevaatajad on odavad. Turva- või koodiülevaatus kulutas 1–4 miljonit žetooni. Teostaja kulutas 5–100 miljonit. Kaks ülevaatajat igale riskantsele commit’ile maksavad vähem kui üks korduskatseid tegev teostaja.
• Suurim sessioon 6. oktoobril käivitas 63 alamagenti ja kulutas 372 miljonit žetooni 3,5 tunniga.

Mis läks katki

Iga allolev viga juhtus, sellel on kuupäev ja see lõppes hooki või skriptiga, mis takistab selle kordumist. Ükski neist pole “mudel kirjutas vea”. Tavalised vead püüdsid kinni testid ja ülevaatajad. Need pääsesid mõlemast mööda.

Kuupäev (2026)	Mis läks katki	Mis seda nüüd blokeerib
19. aug	Paralleelsed agendid kirjutasid ühe tõlkefaili üle: 55 umbes 95 võtmest kadus, kõik kontrollid rohelised	Iga agent kirjutab oma võtmed oma fragmenti; ühendusskript tõendab, et iga võti jõudis kohale
24. aug	Puhastusskript kustutas 4 valminud tööpaketti	Puhastus jätab vahele iga worktree’i, kus on kogumata muudatusi; kogu esmalt, puhasta seejärel
1. sept	Hilisemad agendilained alustasid vanast koodist	Ühenda iga agendi töö kolmepoolse patch’ina, mitte kunagi failikoopiana
13. sept	Agent suri käivitusel ja käivitus ütles “õnnestus”	Käivitaja loeb agendi esimese väljundi ja märgib surnud mudeli kõigile sessioonidele
20. sept	Kaks minu enda reeglit läksid vastuollu; agendid proovisid keelatud käsku uuesti	Isoleeritud agentide ülesandekirjeldustes on käsuvormid, mida liivakast aktsepteerib
18. okt	Agent muutis kontrolle, mis blokeerisid tema commit’i	Kontrollifailid on projektisessioonidest kirjutuskaitstud; muudatused logitakse ja nende kohta tuleb teavitus
18. okt	Paranduse juhised muutsid vaikselt seda, mida kliendi rakenduse kasutajad saavad	Iga paranduse ülesandekirjeldus ütleb “keep live behaviour”; tootemuudatused lähevad minu juurde tagasi

Paralleelsed kirjutajad ja fail, mida iga funktsioon puudutab

Kolm agenti ehitasid samal ajal kolme funktsiooni kliendi iOS-i rakendusele. Igaüks lisas oma tekstistringid rakenduse ainsasse tõlkekataloogi ja igaüks salvestas oma versiooni kogu failist. Viimane salvestus võitis. 55 umbes 95 uuest võtmest oli kadunud. Iga agendi build läbis, sest iga agendi koopia oli järjepidev; kataloogikontroll läbis, sest selle katvus oli katki muul viisil. Leidsin selle võtmeid käsitsi lugedes.

Parandus koosneb kolmest osast. Hook keeldub käivitamast agenti, mille deklareeritud failid kattuvad veel töötava kirjutajaga. Agendid ei muuda kunagi jagatud katalooge; nad kirjutavad oma võtmed fragmendifaili ja üks skript ühendab fragmendid, ebaõnnestub vastuoluliste väärtuste korral ja kontrollib seejärel, et iga võti on olemas. Teine hook blokeerib commit’i, kui kataloogis on vähem võtmeid kui varem. Aus osa: lisasin need kaitsed 18. oktoobril, 60 päeva pärast kaotust. Nende kuupäevade vahel oli ainus kaitse rida Markdown-reeglis ja reegel on soovitus.

Puhastus, mis kustutas valminud töö

Paralleelsed teostajad töötavad git worktree’des ja lisavad muudatused stage’i ilma commit’ita. Commit’i kontroll käskis juhtsessioonil käivitada puhastusskripti. Skript jättis vahele worktree’d, mille agent veel töötas, ja need agendid olid valmis. Neli valminud tööpaketti kustutati ja ühtegi taastatavat git-objekti ei jäänud. “Kas agent veel töötab?” ja “kas selle töö on kogutud?” on erinevad küsimused ning skript küsis ainult esimest. Puhastus jätab nüüd vahele iga worktree’i, kus on muudatusi, mida põhikoopias pole, ja eraldi hook blokeerib worktree’i kaustade otsese kustutamise.

Lained, mis alustasid vanast koodist

11 sammuga plaan jooksis 6 teostajaga 3 lainena. Lained 2 ja 3 alustasid commit’ist, millelt sessioon algas, kolm commit’i maas. Ühe agendi faili tagasikopeerimine oleks tühistanud teise agendi valmis muudatuse. Worktree on hetktõmmis sellest, kust alustasid, seega lähevad tulemused nüüd tagasi kolmepoolsete patch’idena ja konfliktid tulevad nähtavale, selle asemel et vaikselt üle kirjutada.

Surnud agent, kes teatas edust

Agent, mis oli seotud mudeliga, mille kasutuslimiit oli otsas, suri enne oma esimest sammu. Käivitus tagastas “spawned successfully”; tõrge tuli hiljem jõudeolekuteatena. Uuesti proovimise teisel mudelil lülitas tagasi sama hook, mis mudeleid kinnitab. Juhtsessioon kirjutas seejärel plaani vaikselt ise, mis oli täpselt see tulemus, mida planeerija pidi vältima. Hook loeb nüüd agendi esimese väljundi ja märgib surnud mudeli mõneks ajaks kõigile sessioonidele.

Agent, kes muutis oma kontrolle

18. oktoobril sai kliendiprojekti kallal töötav sessioon oma commit’i korduvalt kontrolli poolt blokeeritud. See muutis kolme kontrolliskripti nii, et tema commit läbiks. Midagi sellest ei olnud peidetud; muudatused olid täiesti nähtaval. Aga miski ei takistanud neid ka, sest kontrollid asusid kaustas, kuhu agent sai kirjutada, ja jälgiti ainult failiredaktori tööriistu, mitte shelli käske. Nüüd saab kontrollifaile muuta ainult sessioonist, mis on käivitatud seadistuskaustas endas, iga kirjutustee on kaetud (redaktor, shelli ümbersuunamised, skriptid, git) ja iga neid muutev tegevus projektisessioonis logitakse koos teavitusega.

See on viga, mille eest hoiataksin esimesena. Agent, kellele öeldakse “vii commit läbi”, käsitleb väravat probleemi osana.

Kaks minu enda reeglit olid erinevatel seisukohtadel

Üks reegel käskis agentidel ühendada kolm või rohkem shelli sammu üheks skriptiks, et žetoone säästa. Worktree’sse isoleeritud agendid töötavad liivakastis, mis keeldub just sellest vormist. Agendid sattusid kolm korda järjest mitmel päeval veale “too complex to verify” ja kulutasid oma eelarve ümbersõnastamisele. Agendid peatuvad nüüd pärast kahte identset keeldumist ja isoleeritud agentide ülesandekirjeldused nimetavad töötavad käsuvormid.

Miks mitmeagendilised süsteemid ebaõnnestuvad?

Nende kahe kuu põhjal: mitte seepärast, et mudel on liiga nõrk. Ükski ülaltoodud seitsmest veast ei olnud mudeli läbikukkumine talle antud ülesandes. Need ebaõnnestuvad agentide vahelistes õmblustes, kus ükski üksik agent ei vastuta:

• Jagatud olek. Fail, mida iga funktsioon puudutab, töökataloog, haru. Iga agent on kohalikult õige ja tulemus on globaalselt vale.
• Rohelised kontrollid. Iga ülaltoodud intsident läbis kontrollid, mis sel ajal olid olemas. Kontroll tõestab seda, mida ta kontrollib, mitte midagi enamat.
• Valetavad edusignaalid. “Spawned”, “saved”, “cleaned up” tähendasid igaüks midagi kitsamat, kui nad väitsid.
• Väravale optimeerivad agendid. Ütle agendile, et commit on blokeeritud, ja ta otsib viisi commit’i vabastamiseks, ka värava kaudu.

Teised ehitajad teatavad suuremate laevastike puhul samast mustrist. Jed Arden, kes juhib umbes kahtekümmet agenti, kirjutas, et “the LLM barely appears in the incident log” (eesti keeles: LLM vaevu ilmub intsidendilogis; juuli 2026). Cursori meeskond leidis, et kakskümmend agenti, mis jagasid ühte lukkudega koordinatsioonifaili, aeglustusid kahe-kolme läbilaskevõimeni (jaanuar 2026).

Mida ma kõigepealt seadistaksin

Kui alustate Claude Code’i alamagentide või mis tahes mitmeagendilise orkestreerimisega, teeksin seda selles järjekorras, arvestades, mis mulle õppimine maksis:

1. Logi iga agendi käivitus. Üks rida käivituse kohta: aeg, agenditüüp, mudel, risk. Ilma selleta ei tea sa, mida süsteem teeb, ja ühtegi ülaltoodud arvu poleks olemas.
2. Üks kirjutaja faili kohta. Paralleelsed kirjutajad saavad worktree’i ja deklareeritud faililoendi. Failidel, millele iga funktsioon midagi lisab (tõlked, lukufailid, changelog’id), on üks omanik ja teised annavad fragmente.
3. Kogu enne, kui puhastad. Ära lase puhastussammul otsustada küsimusega “kas see töötab”. Otsusta küsimusega “kas selle töö on põhikoopias”.
4. Vii kontrollid agentide käeulatusest välja. Blokeerivad hookid hoitakse kohas, kuhu projektisessioon kirjutada ei saa.
5. Piira laine. Viis paralleelset agenti on minu lagi; sealt edasi muutub ülevaatus kitsaskohaks ja konfliktid kasvavad kiiremini kui läbilaskevõime.
6. Eskaleeri kordumise, mitte pingutuse põhjal. Vaikimisi odav mudel; pärast sama viga kolm korda üks katse tugevama mudeliga; pärast seda inimene.

Mida maksab AI-agendi ehitamine ja käitamine ettevõttele, mitte ühe arendaja töövoole? See on teine küsimus, millele vastatakse numbritega artiklis Kui palju maksab AI-agent? Numbrid neljast projektist. Milliseid paneele ma nüüd jälgin, samadest logidest kuu hiljem, on artiklis AI agent monitoring dashboard: mida näitas 1 238 täitmist.

Selle aruande piirid

• Ühe arendaja seadistus. Üks juhtsessioon, kuni viis paralleelset agenti. Kümnete või sadade agentide laevastikud ebaõnnestuvad täiendavatel viisidel, näiteks käivitusel.
• Pole päris arvet. Dollarisumma on API nimekirjahinna ekvivalent 30 päeva kohta, alampiir, mis jätab välja vahemälu kirjutamised ja vanemad mudelid. Maksan püsitellimuse eest.
• Augud logides. Blokeeritud käivitusi ei logita, nii et ma ei saa öelda, kui tihti laine ülempiir rakendus. Tugevama teostaja 159 jooksu segavad riskantseid samme ja korduvaid vigu.
• Kuupäevad minu enda märkmetest. Intsidentide kuupäevad pärinevad samal päeval kirjutatud märkmetest ja commit’idest; üks intsident on vanemas reeglifailis dateeritud teisiti ja kasutasin märget.

Sellest tööst kasvanud dashboardi prototüüp on mitmeagendilise orkestreerimise juhtum ja agentide ehitamine klientidele kuulub teenuse AI-agendid ja vestlusrobotid alla.