Computers via de API¶

Het concept achter tools staat in Tools.

Geef een beurt een eigen computer: een afgeschermde machine waarop het model opdrachten uitvoert en bestanden leest en schrijft. Het model kan zo een script schrijven, het draaien, de uitvoer lezen en het opnieuw proberen — om een bijgevoegd CSV-bestand door te rekenen, een grafiek te maken of code te testen. Wat het maakt, krijg je terug als artefact.

Een computer hoort bij één antwoord. Hij wordt gemaakt bij de eerste computer-tool-aanroep van dat antwoord, blijft voor elke volgende aanroep in hetzelfde antwoord dezelfde machine, en verdwijnt als het antwoord klaar is. Een beurt die geen computer-tool aanroept, kost niets.

Dezelfde computer draait ook de eigen programma's van je organisatie, elk aangeboden als één tool: zie Scripts via de API. Een script heeft de capability computer nodig, maar niet de drie tools hieronder.

Wat je sleutel nodig heeft¶

1. De capability computer. Die hangt af van tooling, dus zet die ook aan.
2. De systeemtool computer in de configuratie tooling van de sleutel. Die ene schakelaar zet alle drie de computer-tools aan; in de console heet hij Computer gebruiken (Sleutels).
3. files als het model je bijlagen moet kunnen lezen, en artifacts als je bestanden van de computer terug wilt krijgen.

{
  "name": "Rapportage",
  "capabilities": {
    "tooling": { "system_tools": ["computer"] },
    "computer": {},
    "files": {},
    "artifacts": {}
  }
}

Je organisatie moet computer ook toestaan. Een organisatie die bestond voordat computers er waren, staat het niet vanzelf toe: code laten uitvoeren is een bewuste keuze van wie de organisatie erboven beheert, of van je operator.

Je installatie moet ook computers draaien voor je organisatie. Doet hij dat niet, dan weigert Core een verzoek dat een computer-tool noemt met 400 en "This tool is not configured on this deployment.", nog voordat het model draait. De 400 draagt "computer_not_configured" als error.code. Zo'n tool rechtstreeks aanroepen met POST /tools/{name}/call geeft in plaats daarvan 422 op name, met "reason_code": "computer_not_configured" in de body.

De drie tools¶

Een relatief pad valt onder /workspace. Aanroepen in één ronde lopen na elkaar, in de volgorde waarin het model ze schreef, dus een script dat wordt geschreven en daarna uitgevoerd, werkt zoals bedoeld.

Een verzoek¶

Bied de drie tools aan zoals elke andere tool, en voeg de bestanden toe waarmee het model moet werken:

{
  "model": "<een model-id>",
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Tel de omzet per maand op en maak er een staafdiagram van." },
        { "type": "input_file", "file_id": "src_3Wq8..." }
      ]
    }
  ],
  "tools": [
    { "type": "tool", "name": "builtin__computer_exec" },
    { "type": "tool", "name": "builtin__computer_write_file" },
    { "type": "tool", "name": "builtin__computer_read_file" }
  ]
}

Of bied ze aan via een toolset met het patroon builtin__computer_*.

Bestanden erin en eruit¶

Erin. Bij de eerste computer-aanroep kopieert Core de bestanden die het verzoek bijvoegt — de input_file- en input_image-items — naar /workspace/inputs/<file id>/<bestandsnaam>. Dat gebeurt alleen voor een sleutel met files, en alleen voor bestanden die de sleutel ook via GET /files/{id}/content mag lezen: een bestand dat het beleid van de sleutel niet noemt, van een andere persoon is of intussen is verwijderd, wordt overgeslagen. Een artefact wordt niet naar binnen gekopieerd.

Eruit. Een bestand verlaat de computer alleen als het model het exporteert, met builtin__computer_read_file en export: true. Het wordt een artefact van je sleutel, met hetzelfde maximum als elk ander artefact (25 MiB). Zonder artifacts wordt het niet bewaard en hoort het model dat. Vind de artefacten van een antwoord met:

GET /api/v1/artifacts?response_id=resp_...

GET /artifacts/{id}/content geeft daarna de bytes (Bestanden).

De schijf van de computer is kladpapier. Wat niet is geëxporteerd, is weg als de computer stopt.

Wat een computer niet kan¶

• Geen netwerk. De computer bereikt internet niet, en ook je eigen systemen niet. Wat hij nodig heeft, stuur je mee als bijlage. De uitzondering is een omgeving waarvan de beheerder computers aanbiedt die internet bereiken, voor een organisatie die computer_internet heeft aangezet, net als elke organisatie erboven: daar kan code op de computer verbinding maken met de buitenwereld en zijn argumenten en bestanden overal heen sturen. Zonder die schakelaar krijg je een computer zonder netwerk, of geen als de omgeving alleen open computers heeft. Ook mét de schakelaar krijg je zo'n computer niet als je beleid toegestane regio's of leveranciers noemt, de hosts beperkt die het mag bereiken, of eist dat persoonsgegevens verborgen worden, of als je sleutel persoonsgegevens verbergt. Een organisatie die toegestane hosts heeft ingesteld, wordt ook geweigerd. Een regio-uitzondering verandert dat niet; elke computeraanroep antwoordt Denied by policy..
• Via de proxy van Core, waar de omgeving er een draait. Een computer die internet bereikt, krijgt dan de opdracht de egress-proxy van Core te gebruiken: HTTPS_PROXY, HTTP_PROXY en varianten staan voor elk commando ingesteld, met toegangsgegevens die alleen van die computer zijn. Verkeer dat via de proxy gaat, wordt vastgelegd -- host, bytes, tijd -- en de proxy weigert wat de regels van je organisatie weigeren; waar de omgeving een limiet instelt, wordt het per organisatie begrensd, en een begrenzer die niet antwoordt laat verbindingen door. Je leest het logboek met GET /computers/{computer_id}/egress of GET /computer-egress, te versmallen met host, opened_after en opened_before. Verkeer dat om de proxy van Core heen gaat -- een programma dat de proxyvariabelen negeert, een socket die zelf verbinding maakt -- bereikt het internet nog steeds, en wordt niet vastgelegd, niet begrensd en niet getoetst aan de blokkeerlijst of de regel voor privéadressen.
• De toegangsgegevens van de proxy zijn zichtbaar voor code op de computer. Ze staan in de omgeving van de computer en in /workspace/.artific/proxy.env, dus een opdracht die ze afdrukt, zet ze in de uitvoer van de beurt, en daarmee in de items en de trace van die beurt. Ze horen bij die ene computer, en waar de operator dat inricht is de proxy alleen bereikbaar vanaf het adres waarvandaan computers naar buiten verbinden. Ze openen de proxy niet meer zodra de computer wordt verwijderd of zijn levensduur voorbij is, en ook niet als de sleutel is verwijderd, verlopen of uitgezet, als de organisatie niet actief is, of als de schakelaar niet meer telt; de proxy controleert dat ongeveer elke 30 seconden.
• Geen gesprek overspannen. Elk antwoord krijgt een nieuwe computer. Het volgende antwoord in dezelfde conversatie begint met een lege schijf; wat het model daar nodig heeft, moet in een artefact of in de conversatie staan. De enige uitzondering is een computer die een shelltaak laat staan: de beurten van de thread vinden hem zolang hij blijft staan.
• Niet buiten een eigen beurt. Een computer-tool die je rechtstreeks aanroept of in een geneste beurt noemt, wordt geweigerd met A computer tool runs only in a turn of its own. Een stap van een evaluatie is een gewone beurt en kan wel een computer gebruiken.

Hoe lang een computer leeft¶

• Een synchrone beurt houdt haar computer tot de beurt eindigt, hoe die ook eindigt: met een antwoord, een fout, een afbreking of een stop.
• Een achtergrondrun houdt haar computer tot de run klaar, mislukt of geannuleerd is. Wacht de run op de uitkomst van een function-tool die jij uitvoert (requires_action), dan verdwijnt de computer; de hervatte run krijgt een nieuwe.
• Een shelltaak houdt de computer van het gesprek vast zolang ze loopt en nog een paar minuten daarna, zodat de beurt die haar resultaat beantwoordt hem vindt.
• Nooit langer dan de limiet van de deployment, standaard een uur. De sleutel kan die korter maken, zie hieronder.

Je kunt een computer ook zelf stoppen, met een sleutel die computer heeft. GET /computers geeft de computers van je organisatie die nog leven; ?status=all geeft ze allemaal, ook gestopte, en ?response_id= die van één antwoord. DELETE /computers/{computer_id} stopt er een en geeft 204. Was hij al weg, dan krijg je 409; kan Core de machine niet bereiken, dan 503 — Core ruimt hem dan later zelf op. De beurt die hem gebruikte, verliest hem meteen.

Limieten per sleutel¶

De configuratie van de capability computer maakt de limieten van de installatie kleiner, nooit groter. Een waarde boven de limiet wordt teruggebracht tot de limiet.

{
  "capabilities": {
    "tooling": { "system_tools": ["computer"] },
    "computer": { "exec_timeout_seconds": 30, "lifetime_seconds": 600 },
    "files": {},
    "artifacts": {}
  }
}

Je operator kan andere standaarden hebben ingesteld. Processor en geheugen liggen vast per installatie en zijn niet per sleutel in te stellen.

Wat het model te horen krijgt¶

Uitvoer van een opdracht en tekst uit een bestand zijn onvertrouwd, zoals elk toolresultaat (Vertrouwen in toolresultaten), en worden afgekapt op 32 KiB. Een opdracht die zijn tijd overschrijdt, geeft wat hij tot dan toe schreef, met als eerste regel timed out after <n> seconds. Gaat er iets mis, dan krijgt het model een vaste zin van Core:

Geen van deze fouten beëindigt de beurt; het model kan verder.

Regio's¶

Beperkt het beleid van je sleutel of je organisatie de regio's (policy.settings.regions_allow), dan moet de regio waar je organisatie haar computers draait in die lijst liggen. Die regio stelt je operator in; vraag hem waar je computers draaien. Ligt hij erbuiten, dan geeft elke computer-aanroep Denied by policy., wordt er niets gemaakt en staat de weigering in je auditspoor. Noem builtin:computer als regio-uitzondering om computers toch toe te staan zonder de hele regio open te zetten.

Verbruik en audit¶

Per computer schrijft Core één verbruiksrij van soort sandbox_seconds als hij stopt: de hele seconden van het moment dat hij klaarstond tot het moment dat hij verdween, naar boven afgerond, op naam van de sleutel wiens beurt hem maakte. Stopt iemand hem via DELETE, dan blijft de rekening bij die sleutel. Met een prijs per seconde telt het mee voor de maandlimiet. In de console heet deze soort Sandboxtijd.

Het auditspoor legt vast: computer.created en computer.destroyed (met de seconden die hij draaide), computer.destroy_requested als iemand hem via de API of de console stopte, en per aanroep computer.executed met de soort (exec, write_file, read_file), de duur en bij een opdracht de exitcode, en computer.egress_rate_limited als de egress-proxy van Core een verbinding weigerde omdat je organisatie haar deel had gebruikt. De opdracht zelf, de uitvoer en bestandsnamen staan nooit in het auditspoor; die staan in de beurt zelf en in haar trace, onder de bewaartermijn van je organisatie.