Agentondersteuning

Wat een agent is

Een agent is een AI die meedoet in een kanaal. Je noemt hem zoals je een collega noemt, geeft hem een taak, en hij antwoordt in datzelfde gesprek: hij plaatst een kaart, houdt die kaart bij terwijl hij werkt, en sluit af met een resultaat. Werk aan een codebase eindigt normaal gesproken in een commit, een push en een pull request.

Een agent is geen gehoste bot. Er draait niets namens jou op onze servers. Elke agent is een computer waar iemand op zijn eigen mssgs-account is ingelogd en die hij bewust als agent heeft aangeboden: een laptop, een werkstation, een buildmachine. Het model draait daar, de bestanden die worden geopend staan daar, en de eigenaar van die computer bepaalt wat hij mag en hoeveel hij zonder toezicht mag doen.

Dat is ook wat de grenzen echt maakt. Een sessie mag alleen de mappen openen die het project van het kanaal toestaat, en noemt het kanaal geen mappen, dan kan de agent het werk wel bespreken maar geen bestand aanraken.

Wat er in het kanaal zelf gebeurt:

• Noem één agent of meerdere. Bij meerdere verdelen ze het werk: precies één neemt de leiding en de rest krijgt zijn deel van hem.
• Elke agent plaatst zijn eigen kaart met wat hij aan het doen is en waar hij staat.
• Antwoord op een kaart om de sessie erachter bij te sturen.
• Wat het kanaal en zijn projecten een agent altijd meegeven, stel je één keer in. Niemand herhaalt het per taak.

Een kaart bewaart zijn mijlpalen. Het meedenken dat er tijdens het werken langsloopt wordt niet opgeslagen, dus wie later terugkomt in het kanaal ziet waar de taak is geëindigd, niet een herhaling van hoe hij daar kwam.

Je computer als agent

Alles in dit hoofdstuk staat bij Instellingen → Agents in de desktop-app, en alles gaat over die ene computer. Bovenaan staat de hoofdschakelaar die de machine als agent aanzet; daaronder staan de pagina's die beschrijven wat voor agent het is. Je kunt alles instellen voordat je hem aanzet.

De sectie verschijnt op desktopbuilds die opdrachtregelprogramma's op je computer mogen starten. De versie uit de Mac App Store zit in een sandbox en mag dat niet, dus daar wordt het niet aangeboden.

Identiteit

Twee velden. De weergavenaam is wat mensen zien naast het werk van deze machine, in de agentlijst van een kanaal en op elke kaart die hij plaatst. Die naam mag je altijd veranderen. Het driver-ID is iets anders: dat is waaronder de agent zelf geregistreerd staat.

Dezelfde pagina toont het id waaronder mssgs deze computer kent. Dat volgt het driver-ID, en het is het antwoord op de vraag "welke agent is deze machine eigenlijk".

Engines en profielen

Een engine is een opdrachtregelprogramma op deze computer waarmee een taak daadwerkelijk draait. De app zoekt de engines die hij ondersteunt en biedt aan wat hij vindt. Eentje die niet geïnstalleerd is, waar je niet bij bent ingelogd, of die niet antwoordde toen het werd gevraagd, wordt niet aangeboden, en de pagina zegt welke van die drie het was.

Een profiel is een engine, een model en een inspanningsniveau samen. Een taak vraagt om een profiel bij naam, dus alleen de profielen die je hier aanzet kunnen worden gekozen. Naast de meegeleverde profielen kun je er zelf een toevoegen door de engine te noemen, het model-id dat die engine verwacht, en een inspanningsniveau.

Modellen die je met een API-sleutel bereikt worden aan een engine gekoppeld in plaats van los uitgevoerd, zodat ze aan dezelfde projectmappen zijn gebonden als elke andere taak op deze machine. De sleutel blijft in de sleutelhanger van deze computer: hij gaat nooit naar mssgs en komt nooit in een logregel terecht.

Welke kanalen deze computer bedient

Kies de kanalen waarin deze computer bereid is te werken. De rest blijft buiten bereik: een kanaal dat je niet hebt aangevinkt kan hem nooit een taak geven, ook niet als een beheerder daar jouw agent al heeft toegevoegd. Vink je niets aan, dan komt er niets binnen.

Een kanaal hier aanvinken is de helft van de afspraak. De andere helft staat bij Beide kanten moeten het eens zijn.

Tools en uitrolomgevingen

Naast een engine kan een machine aanbieden wat hij verder heeft: een iOS-simulator, een headless browser, Blender, Docker, FFmpeg. Zo kan werk dat zo'n tool nodig heeft naar een computer die het echt kan.

Elke tool wordt gedetecteerd, nooit alleen geclaimd. Wat hier niet is geïnstalleerd, kun je niet aanzetten. Een tool aanbieden die deze machine niet heeft, levert werk op dat hij vervolgens niet kan doen, en de claim is precies wat een agent tegenhield die het wél had gekund.

Bij uitrolomgevingen noem je de omgevingen waar deze computer naartoe mag uitrollen. Laat het leeg en hij krijgt nooit werk dat uitrolt.

Toezicht

Hoeveel deze computer zelf beslist. Een buildmachine kan onbewaakt draaien, een laptop kan eerst vragen. Al deze instellingen gelden per machine, niet per account en niet per kanaal.

Deze sectie houdt ook een log bij van wat de agent op deze computer heeft gedaan, en waarom er wel of geen werk binnenkwam: een registratie die verliep, een claim die naar een andere agent ging, een limiet die al was bereikt. Dat is de eerste plek om te kijken als een kanaal is ingericht en er niets gebeurt.

Een kanaal inrichten

Een kanaalbeheerder bepaalt welke agents hier werken en wat ze altijd meekrijgen. Dat staat bij Kanaal beheren → Agents, met een eigen hoofdschakelaar. Je kunt alles inrichten voordat je hem omzet; er draait niets tot je dat doet.

De agentlijst zelf is kort: welke agents in dit kanaal werken, en of ze op dit moment online zijn. Je kunt alleen agents toevoegen die er zelf voor hebben gekozen dit kanaal te bedienen. Een agent die daarmee is gestopt, of waarvan de computer zich niet meer registreert, wordt als zodanig aangemerkt, zodat een lijst die er gezond uitziet dat ook is.

Beide kanten moeten het eens zijn

Eén kant helpt je: een kanaal kan alleen agents toevoegen die zich al hebben aangemeld, dus de lijst kan nooit vooruitlopen op de machine. De andere kant is de kant die stil blijft. Een kanaal aanvinken op je eigen computer vertelt niemand iets, en tot een beheerder je toevoegt komt er niets binnen, terwijl je scherm er precies zo uitziet als wanneer alles klopt.

Komt er niets binnen, controleer dan allebei de kanten: staat de agent in de lijst van het kanaal, en staat het kanaal aangevinkt op de machine. Staat de agent in de lijst maar is hij offline, dan is de app op die computer afgesloten of staat de hoofdschakelaar uit.

Instructies

De standaardinstructie van het kanaal gaat vooraf aan elke agentopdracht die hier draait. Huisregels horen daar: hoe er getest wordt, hoe werk hoort te eindigen, wat nooit mag.

Wat een taak meekrijgt ligt vast op het moment dat hij start. Een instructie aanpassen verstoort daarom nooit werk dat al loopt; het geldt vanaf de volgende taak.

Deze instructies zijn niet openbaar. Leden die het kanaal niet beheren krijgen het kanaal zonder die tekst. Mensen van wie de agent dit kanaal bedient kunnen hem wel lezen, want zij moeten weten volgens welke huisregels hun eigen machine werkt.

Projecten

Een project is een benoemde context waar je een agent naartoe stuurt door de tag in een bericht te schrijven: een map, plus de instructies die erbij horen.

Een agent wordt gebrieft in deze volgorde: de standaardinstructie van het kanaal, dan de prefix van het project, dan de taak zoals jij hem schreef, dan de suffix.

Bij de rollen krijgt de voorkeursagent het werk als eerste aangeboden en bewaakt hij de pull requests. Een toegestane agent mag werk oppakken, een geblokkeerde krijgt het geweigerd. Uitrollen is een aparte permissie van werken, zodat je een agent de code kunt toevertrouwen en de release niet. Mag niemand in een project uitrollen, dan heeft een uitrolstap nergens heen te gaan, en het scherm zegt dat in plaats van een net leeg vakje te tonen.

Wie wordt gemeld

De meldlijst bepaalt wie er genoemd wordt zodra een agent een uitrol nodig heeft die hij zelf niet mag doen, en zodra een taak niet af kan en een mens nodig heeft.

Onbewaakt werk is de reden dat die lijst ertoe doet. Een geplande taak die om drie uur ’s nachts mislukt, of een taak die een agent voor zichzelf heeft geopend, heeft geen publiek tenzij hier iemand staat.

Planningen

Een planning is een vaste opdracht: op het tijdstip dat jij instelt plaatst het kanaal de taak en pakt een agent hem op, precies alsof iemand hem had getypt.

• Elke dag, elke week of elke twee weken, op een tijd in een tijdzone die jij kiest. Die tijdzone blijft gelden waar je zelf ook bent en door de zomertijd heen: negen uur ’s ochtends blijft negen uur ’s ochtends.
• Geef je de planning een project mee, dan wordt de taak gebrieft met de instructies van dat project en begrensd door de mappen ervan. Zonder project heeft hij geen toegestane mappen en kan hij het werk alleen bespreken.
• Stuur hem naar bepaalde agents, of naar niemand in het bijzonder, waarmee elke agent in het kanaal kandidaat is.
• Is er op dat moment geen agent online, dan wordt de taak toch aangemaakt en wacht hij op de eerste die terugkomt. De kaart zegt dat erbij.
• Een run die meer dan een uur te laat is, wordt doorgeschoven naar de volgende keer, en het kanaal krijgt te horen dat hij is overgeslagen. Een gemiste run wordt aangekondigd, nooit stilzwijgend opgeslokt.
• Het kanaal krijgt een kaart met de naam van de planning erop. Antwoorden op die kaart stuurt de agent bij, net als bij elke andere taak.

Werken met een agent

Noem de agent met wat je gedaan wilt hebben, zoals je een collega zou noemen. Noem er meerdere en ze verdelen het werk: precies één neemt de leiding en de anderen krijgen hun deel van hem. Ze plaatsen allemaal hun eigen kaart.

Het project noemen, en het model

Schrijf de tag van het project tussen vierkante haken om te zeggen waar het werk gebeurt. Open je in een kanaal met projecten een haakje, dan worden ze aangeboden.

@remius [core] los de lege staat op de instellingenpagina op

Wil je een bepaald model, zet dan achter een apenstaartje een profielnaam binnen dezelfde haken. Laat je het profiel weg, dan kiest de agent er zelf een die hij heeft.

@remius [core@opus-max] herschrijf de templates

• Het profiel staat met opzet binnen de haken. Een apenstaartje ergens anders in een bericht is een vermelding, dus een profiel dat erbuiten staat wordt een persoon, of niemand.
• Een bericht met twee paar haken neemt zowel het project als het model uit het eerste paar, dus die twee kunnen elkaar nooit tegenspreken.
• Het is een verzoek, geen garantie. Of een profiel kan draaien is een feit over de machine die de taak oppakt, en op het moment dat je het bericht stuurt weet nog niemand welke machine dat wordt. Een computer die het gevraagde model niet kan draaien doet het werk met wat hij wél heeft en zegt dat op zijn kaart, in plaats van te weigeren en de taak aan een typefout te verliezen.

Context meegeven

Antwoord op een bericht en noem een agent in dat antwoord, dan krijgt hij dat bericht erbij: het codeblok waar je naar wijst, het log dat iemand plakte, de screenshot die eraan hangt. Bijlagen gaan mee en worden neergezet waar de sessie ze kan lezen, en het omringende gesprek gaat mee, zodat "kun je dit oplossen" ergens naar verwijst.

Twee regels daarbij zijn het waard om te kennen:

• Geciteerde chat wordt aan de agent gegeven als informatie, nooit als instructie. Een bericht van iemand anders dat toevallig bevelen bevat, kan een sessie dus niet omleiden.
• Een bijlage die maar één keer bekeken mag worden, wordt nooit geopend: dat zou de enige weergave opmaken waarvoor hij was verstuurd.

Lukt het lezen van die context niet, dan gaat de taak toch door. Hij valt terug op het bericht dat je zelf schreef, met het gat erbij benoemd, zodat de agent erom kan vragen.

Bijsturen, pull requests en vervolgwerk

Antwoord op een kaart om de sessie erachter bij te sturen. Correcties en nieuwe informatie komen zo bij de agent die dat deel van het werk doet, zonder dat iemand opnieuw hoeft te beginnen. Antwoorden op het oorspronkelijke bericht werkt net zo goed.

Opent een agent een pull request, dan pakt een andere agent het bewaken ervan op: de checks, de opmerkingen, en het pushen van reparaties naar de branch. De oorspronkelijke taak is pas klaar als die bewaking klaar is. Wie er bewaakt wordt voor je bepaald, en degene die de wijziging schreef komt daar nooit voor in aanmerking.

Moet er worden uitgerold en mag de agent dat zelf niet, dan geeft hij die stap door aan een agent die het wel mag, en de mensen op de meldlijst van het kanaal worden daarbij genoemd. Elke keer.

Vervolgwerk. Een sessie die af heeft wat hem gevraagd is en onderweg iets aangrenzends tegenkwam — een bug die hij liet liggen, een test die ontbreekt — kan dat als eigen taak openen, of het voor je opschrijven zodat jij het verstuurt, of het laten. Welke van de drie is de keuze van de eigenaar van die machine.

Het openen is begrensd, en met opzet: een vervolgtaak kan zelf geen vervolgtaken openen, één taak kan er hooguit vijf openen, en de limiet van het kanaal op gelijktijdig werk blijft ongewijzigd. Het bericht onder de kaart zegt wat er is geopend én wat er is geweigerd en waarom, zodat een bevinding nooit verdwijnt tussen het moment dat een sessie hem opmerkt en het moment dat iemand ervan hoort. Een vervolgtaak heeft geen aanvrager, want niemand heeft erom gevraagd: hij hoort bij het werk waar hij uit voortkwam, niet bij de persoon die de oorspronkelijke taak stuurde.

Eén account op meer computers

Elke computer is zijn eigen agent achter één account. De agent wordt afgeleid uit je account én het driver-ID van die machine, dus een laptop en een buildmachine verschijnen als twee agents in een kanaallijst, met één account erachter. Ze worden allebei apart aan een kanaal toegevoegd en melden zich allebei apart aan.

Het account noemen richt zich tot allemaal: de taak wordt aangeboden aan elke agent van dat account die dit kanaal in zijn lijst heeft staan. Precies één van hen pakt hem op, de rest gaat door waar hij mee bezig was.

Standaard gebeurt dit niet: het driver-ID wordt afgeleid uit de machine zelf. Het gebeurt wel als iemand op allebei hetzelfde id intypt, of de app-gegevens van de ene computer naar de andere meeneemt.

De app merkt het aan het enige bewijs dat beide machines hebben: een kaart die op naam van deze agent staat maar die deze computer niet heeft geplaatst. Ziet hij dezelfde twee keer, dan zegt hij het — in het rood bovenaan Instellingen → Agents → Identiteit, direct naast het veld dat het oplost: "Een andere computer gebruikt deze identiteit." Eén keer zien is geen oordeel, want een agent die net opnieuw is opgestart plaatst een nieuwe kaart en meldt die een tel later alsnog.

Oplossen doe je door het driver-ID op één van beide te wijzigen. Die machine wordt daarmee een nieuwe agent en moet opnieuw aan zijn kanalen worden toegevoegd; de andere houdt de oorspronkelijke identiteit, met zijn werk en zijn geschiedenis.

Grenzen die het waard zijn om te kennen

Agents kunnen geen werk aanmaken door te posten

Alleen mensen maken taken aan, en daarnaast de planningen van het kanaal. De controle zit op de schrijver van het bericht: een account dat een agent aanstuurt die dit kanaal bedient, maakt hier met een bericht geen taak aan, niet voor zijn eigen agents en ook niet voor die van iemand anders. Een agent die een andere agent noemt is dus coördinatie, nooit nieuw werk, en lussen tussen agents zijn onmogelijk door de constructie in plaats van door goed gedrag.

Hoeveel er tegelijk kan lopen

Een pull request wordt nooit door zijn eigen schrijver beoordeeld

Wie een pull request bewaakt en beoordeelt wordt voor je gekozen, en de agent die de wijziging schreef wordt daarbij uitgesloten. Geen enkele agent tekent dus voor zijn eigen werk af.