Scripts in de console¶

Het concept achter tools staat in Tools.

Een script is een eigen programma dat het model als één tool aanroept. Core draait het in een sandbox zonder internet en geeft de uitvoer en de gemaakte bestanden terug. In de sectie Scripts, onder Tools in de navigatie, upload je een script, schrijf je er nieuwe versies van, probeer je het uit en bepaal je welke bibliotheken de scripts van je organisatie mogen gebruiken. Elk script wordt de tool script__<naam>, die in het Overzicht verschijnt en in een toolset past. Hoe een applicatie hetzelfde doet, staat op Scripts via de API.

Je hebt een beheerdersaccount van de organisatie nodig, en de organisatie moet zowel tooling als computer toestaan onder Toegestane capabilities. Een script maken of bewerken en een pakket goedkeuren doe je op een groter scherm; op een telefoon kun je de lijsten alleen lezen.

Scripts aanzetten voor een sleutel¶

Een sleutel krijgt je scripts aangeboden als hij zowel tooling als computer aan heeft op Sleutels. Computer gebruiken onder Systeemtools is daarvoor niet nodig: die schakelaar geeft het model een shell, en een sleutel die alleen je geteste programma's moet draaien, laat hem uit. Zet ook files aan als het model met de bijlagen van een beurt moet werken, en artifacts als je de bestanden wilt die een script maakt.

De policy van de sleutel beslist nog steeds op naam: de regels over Tools moeten script__<naam> toestaan.

De lijst¶

Zoek op naam of beschrijving, of filter op label. Kies een rij om het script te openen.

Een script maken¶

Kies Nieuw script. Het formulier heeft zes stappen.

1. Naam en beschrijving.
   • Naam: kleine letters, cijfers, - en _. Het model ziet script__<naam>. Na opslaan verandert de naam nooit meer, omdat policyregels, verbruik en de audittrail hem vastleggen.
   • Beschrijving voor het model: wanneer het model deze tool moet gebruiken, hoogstens 1024 tekens. Het model ziet alleen de naam, deze tekst en de parameters.
   • Labels, als je wilt.
2. Starten.
   • Entrypoint: het programma dat draait, in 1 tot 16 delen, elk een los argument, zoals python3 en main.py. Een deel voeg je toe met Deel. Het is geen shell-regel: pipes, && en omleidingen werken niet.
   • Time-out, als je wilt, in seconden. Een aanroep stopt bij de kortste van deze time-out en de limiet van de sleutel die aanroept. Leeg laat de limiet van de sleutel gelden.
3. Parameters. De argumenten die het model meegeeft, als JSON Schema. Bouw het veld voor veld in de weergave Visueel, plak het in de weergave JSON, of laat Beschrijf wat je nodig hebt er een voorzet voor maken. De omschrijving van een veld is wat het model leest. Laat het leeg voor een script zonder argumenten.
4. Bestanden. Alle bestanden van het pakket. Tekstbestand voegt een bestand toe dat je hier typt, zoals main.py. Uit uploads kiest een bestand uit de uploads van je organisatie, of uploadt een nieuw bestand met Bestand uploaden; gebruik dit voor binaire bestanden zoals een sjabloon of een lettertype. Opslaan kopieert de upload in de versie, dus de upload later weghalen laat de versie heel. Een pad is relatief en mag geen .., \ of / vooraan bevatten. De meters tonen de grenzen: hoogstens 200 bestanden en 20 MiB samen.
5. Pakketten. De bibliotheken die het script nodig heeft naast wat de sandbox-image meebrengt, zie Pakketten. Zoek een goedgekeurd pakket en voeg het toe; alleen goedgekeurde pakketten zijn te kiezen.
6. Asynchrone tool, als je wilt. Of het model het script mag starten als taak die doorloopt na de beurt: Op de achtergrond starten, Langste looptijd (seconden) en Veilig om opnieuw te sturen, zoals beschreven bij Asynchrone tool. De standaard is Nooit. Zie Een tool op de achtergrond draaien voor wat er dan gebeurt.

Het paneel naast het formulier toont Zo ziet het model hem en de grenzen van een aanroep: uitvoer terug tot 32 KiB, hoogstens 10 artefacten per aanroep, en geen internet. Opslaan maakt versie 1; proberen kan daarna.

Je programma leest de argumenten van het model als JSON van standaardinvoer of uit het bestand dat ARTIFIC_ARGUMENTS noemt, en schrijft de bestanden die terug moeten naar de map die ARTIFIC_OUTPUTS noemt. Wat het script meekrijgt heeft een voorbeeld.

De pagina van een script¶

De pagina van een script heeft drie tabbladen.

• Overzicht toont de Beschrijving voor het model, de Parameters met de verplichte gemarkeerd, de gegevens van de laatste versie (Tool, Entrypoint, Time-out, Laatste versie, Bestanden), de pakketten die hij noemt, en onder Gebruikt in de agents die het noemen en de toolsets die het bereiken.
• Versies toont elke versie met wie hem schreef en wanneer. Vink twee versies aan en het paneel Vergelijken naast de lijst toont welke velden en welke bestanden veranderden.
• Bestanden toont de bestanden van één versie met hun grootte en digest. Een tekstbestand krijgt een voorbeeld; een binair of heel groot bestand download je met Downloaden.

Een nieuwe versie schrijven¶

Een opgeslagen versie verandert nooit meer. Kies Nieuwe versie om de volgende te schrijven. Het formulier opent met het pakket van de laatste versie ingevuld: tekstbestanden om te bewerken, binaire bestanden die meegaan, de pakketten en de instelling Asynchrone tool. Pas aan wat nodig is en kies Opslaan als v…. De vorige versie blijft ongewijzigd bestaan, en aanroepen die haar vastzetten, houden haar.

Is alles precies gelijk aan de laatste versie, dan slaat Core niets op en zegt het formulier Gelijk aan de laatste versie, niets opgeslagen.

Een verzoek of een agent gebruikt de laatste versie, tenzij het er een vastzet; zie Aanbieden aan het model.

Concepten¶

Opslaan als concept v…, naast de opslaanknop, schrijft de versie als concept: geen sleutel ziet of draait het tot je het publiceert, en aanroepen blijven de gepubliceerde versie draaien. Een nieuw script dat je als concept opslaat, heet concept in de lijst en is voor geen enkele sleutel een tool. Versies markeert elk concept als concept en toont het onder de lijst met Publiceren en Concept weggooien, elk na een bevestiging. Een concept dat een concept van een agent vastzet, kun je pas weggooien als dat concept van de agent verandert; de bevestiging noemt het.

Aanroepvariabelen¶

Een script kan waarden lezen die je applicatie bij elk verzoek meestuurt, zoals het account-id van een klant. In het formulier staan ze in de kaart Bij de aanroep; kies Variabele toevoegen, typ een naam en vul dezelfde velden in als bij een API-koppeling: soort, Verplicht, omschrijving, toegestane waarden en standaardwaarde. Een script declareert ze met de hand, want zijn code heeft geen markering om ze uit af te leiden, en geen ervan kan Geheim zijn: de shelltools kunnen de bestanden van een script lezen. Het script leest ze uit het bestand dat ARTIFIC_VARIABLES noemt (Een waarde van je klant aan een tool meegeven). Een naam die ook een argument of invulwaarde is, wordt geweigerd. Ze horen bij de versie, dus opslaan schrijft een nieuwe, en een nieuwe versie begint met de aanroepvariabelen en invulwaarden van de laatste.

Een script proberen¶

Kies Proberen op de pagina van het script. Kies onder Uitvoeren als de sleutel waarmee het draait, de Versie, en vul de argumenten in, die gemaakt zijn uit de parameters van die versie. Declareert de versie aanroepvariabelen, dan staat er een veld voor elk tussen de sleutel en de versie. Kies dan Draaien. Een sleutel zonder tooling of computer staat erbij met wat hij mist, en kan het script niet draaien.

Een proefdraai is een echte aanroep: hij draait in de sandbox, telt als aanroep van die sleutel en kost sandboxtijd. Het resultaat toont:

• Gelukt, Fout in het script (een andere exitcode dan 0) of Na … seconden gestopt (de time-out verliep), met de exitcode en de duur;
• de standaarduitvoer en standaardfout, afgekapt op 32 KiB;
• Artefacten: de bestanden die het script maakte, bewaard als artefact;
• Weggelaten: bestanden die op de computer bleven, omdat het er meer dan 10 waren, een bestand te groot of geen gewoon bestand was, of de sleutel geen artifacts heeft.

Bereikte de aanroep de sandbox niet, dan toont Niet gedraaid de reden van Core, zoals een regio die de sleutel niet mag bereiken, argumenten die niet aan de parameters voldoen, of een pakket dat niet meer goedgekeurd is.

Een script verwijderen¶

Kies Verwijderen op de pagina van het script en bevestig. De versies en hun bestanden gaan mee. Toolsets en aliassen verwijzen naar de naam en blokkeren niet. Zolang een agent het script gebruikt, noemt de dialoog die agents; haal het script daar eerst weg.

Pakketten¶

Een script kan alleen goedgekeurde bibliotheken importeren. Het tabblad Pakketten, naast Scripts, toont alles wat de scripts van je organisatie mogen gebruiken. De kolom Herkomst zegt waar een goedkeuring vandaan komt:

Op de pagina van een geïnstalleerd script kan een pakket ook als uitgever gemarkeerd staan: een pakket dat alleen de uitgever van de bundel goedkeurde, dat je bij het installeren accepteerde en dat alleen voor dat script geldt. Het staat niet op dit tabblad.

Filter op ecosysteem (PyPI of npm) of op herkomst. Gebruikt door noemt de scripts waarvan de laatste versie het pakket noemt. Staat een bibliotheek die je nodig hebt er niet op, keur hem dan goed voor je organisatie, of vraag je operator hem goed te keuren voor alle organisaties.

Een versie moet elk pakket noemen dat ze nodig heeft naast de image, inclusief de pakketten waar die pakketten van afhangen: Core installeert offline en lost geen afhankelijkheden op. Een ontbrekende afhankelijkheid zie je als importfout de eerste keer dat je het script probeert.

Een pakket goedkeuren¶

1. Kies Pakket goedkeuren.
2. Kies de Soort pakket: PyPI · wheel of npm · tarball.
3. Kies het bestand. Voor PyPI is dat de wheel (.whl) van PyPI, nooit een bronpakket: de sandbox bouwt geen pakketten. Voor npm is het de tarball (.tgz) zoals npm pack hem schrijft.
4. Naam en Versie worden ingevuld uit de bestandsnaam. Een pakket wordt goedgekeurd voor precies één versie; een andere versie keur je los goed.
5. Bekijk de Controles: de soort bestand, de grootte (hoogstens 32 MiB) en of het nieuw is op de lijst. Voor een wheel toont de console de Python- en platformtags; Core toetst bij goedkeuren of de wheel op de sandbox past en weigert er een die niet past.
6. Kies Goedkeuren.

Je organisatie heeft hoogstens 500 goedkeuringen; de teller staat bovenaan het tabblad. Een goedkeuring bereikt geen andere organisatie. Houdt de organisatie boven de jouwe het sleutelbeheer aan zichzelf, dan keuren haar beheerders goed en trekken ze in, en mislukt jouw poging met de reden van Core.

Een pakket intrekken¶

Open het rijmenu van een van de eigen pakketten van je organisatie en kies Intrekken. De dialoog noemt de scripts die het gebruiken. Intrekken verwijdert het bestand, en versies die het pakket noemen, kunnen daarna niet meer draaien: hun aanroepen geven de fout dat het pakket is ingetrokken, tot je een versie zonder dit pakket maakt. Keur je later precies hetzelfde bestand opnieuw goed, dan draaien die versies weer; een ander bestand niet.

Pakketten die voor het platform goedgekeurd zijn of in de image zitten, trekt alleen je operator in.

Een script delen¶

Kies het script onder Scripts als je een versie van een bundel publiceert; de bestanden en de pakketten die alleen jouw organisatie goedkeurde, gaan mee. Wat de abonnee ziet en accepteert, staat op Publiceren en installeren in de console. Een script dat uit een bundel komt, toont zijn herkomst in de kolom Herkomst; zolang het gekoppeld is, biedt het geen Nieuwe versie en kan het niet worden verwijderd.

Wat wordt vastgelegd¶

Elke aanroep van een script is verbruik van zijn sleutel: één toolaanroep met de naam script__<naam>, plus de Sandboxtijd van de computer waarop hij draaide (Computers in de console). De audittrail legt vast wanneer een script gemaakt, van een versie voorzien of verwijderd wordt, wanneer een pakket goedgekeurd of ingetrokken wordt, en elke aanroep met het script, de versie, de duur en de exitcode. Argumenten, uitvoer en bestandsnamen komen nooit in de audittrail.