Skip to content

Agent37

Agent37 Cloud for Sanoma: the boxes coding agents work in, one persistent Linux instance each, driven through Sanoma's runner.

Package @sanoma-ai/connector-agent37, version 0.11.24. Its README, with how to install and connect it, is on GitHub.

Resource types, which a data file under resources/ declares: agent37.instance.

instance

import

agent37.instance.importreadsafe to retry

Find a instance by its binding id and read it; gone when there is none

Input

  • idstringrequired

    at least 1 character

Output

  • idstringrequired

    at least 1 character

  • gonebooleanrequired
  • stateobject
    Fields
    • size2 | 4

      Each box's vCPUs, 2 (the default) or 4; a box that exists keeps its shape

    • memoryinteger

      Each box's memory in GB: 4 with 2 vCPUs, 8 (the default), 16 or 32 with 4

    • diskinteger

      Each box's disk in GB, billed in every state; default 10

      at least 2

    • imagestring

      The template a box runs: by default Sanoma's box image of this release, registered in the workspace; or agent37-base, or another template of the workspace

      at least 1 character

    • region"us" | "eu" | "ap-south"

      Where boxes run, us (the default); eu and ap-south run vm and performance boxes only

    • type"default" | "vm" | "performance"

      default (shared CPU, the default), vm (a kernel of its own) or performance (cores held for it)

    • idstring

      What the declaration is bound by: boxes are made as people open them

    • healthyboolean

      Whether the key lists the workspace's instances

  • handlestring

    The driver's data for the object, opaque: pass it back unchanged

read

agent37.instance.readreadsafe to retry

Read a instance as it is now; gone when it no longer exists

Input

  • idstringrequired

    at least 1 character

  • staterecord of any
  • handlestring

    The driver's data for the object, opaque: pass it back unchanged

Output

  • idstringrequired

    at least 1 character

  • gonebooleanrequired
  • stateobject
    Fields
    • size2 | 4

      Each box's vCPUs, 2 (the default) or 4; a box that exists keeps its shape

    • memoryinteger

      Each box's memory in GB: 4 with 2 vCPUs, 8 (the default), 16 or 32 with 4

    • diskinteger

      Each box's disk in GB, billed in every state; default 10

      at least 2

    • imagestring

      The template a box runs: by default Sanoma's box image of this release, registered in the workspace; or agent37-base, or another template of the workspace

      at least 1 character

    • region"us" | "eu" | "ap-south"

      Where boxes run, us (the default); eu and ap-south run vm and performance boxes only

    • type"default" | "vm" | "performance"

      default (shared CPU, the default), vm (a kernel of its own) or performance (cores held for it)

    • idstring

      What the declaration is bound by: boxes are made as people open them

    • healthyboolean

      Whether the key lists the workspace's instances

  • handlestring

    The driver's data for the object, opaque: pass it back unchanged

plan

agent37.instance.planreadsafe to retry

Plan how apply would make a instance match its declaration (or delete it, given none); nothing changes

Input

  • idstring

    at least 1 character

  • staterecord of any
  • handlestring

    The driver's data for the object, opaque: pass it back unchanged

  • desiredrecord of any

    The declared fields; a write-only one may hold a secret marker

Output

  • action"none" | "create" | "update" | "replace" | "delete"required
  • plannedrecord of any
  • unknownstring[]required
  • replacestring[]required

    The fields whose change replaces the object: not empty exactly when replace

create

agent37.instance.createwrite

Create a instance as declared

Input

  • desiredrecord of anyrequired

    The declared fields; a write-only one may hold a secret marker

Output

  • idstringrequired

    at least 1 character

  • stateobjectrequired
    Fields
    • size2 | 4

      Each box's vCPUs, 2 (the default) or 4; a box that exists keeps its shape

    • memoryinteger

      Each box's memory in GB: 4 with 2 vCPUs, 8 (the default), 16 or 32 with 4

    • diskinteger

      Each box's disk in GB, billed in every state; default 10

      at least 2

    • imagestring

      The template a box runs: by default Sanoma's box image of this release, registered in the workspace; or agent37-base, or another template of the workspace

      at least 1 character

    • region"us" | "eu" | "ap-south"

      Where boxes run, us (the default); eu and ap-south run vm and performance boxes only

    • type"default" | "vm" | "performance"

      default (shared CPU, the default), vm (a kernel of its own) or performance (cores held for it)

    • idstring

      What the declaration is bound by: boxes are made as people open them

    • healthyboolean

      Whether the key lists the workspace's instances

  • handlestring

    The driver's data for the object, opaque: pass it back unchanged

update

agent37.instance.updatewrite

Change a instance to match its declaration, replacing it where a field cannot change in place

Input

  • idstringrequired

    at least 1 character

  • staterecord of any
  • handlestring

    The driver's data for the object, opaque: pass it back unchanged

  • desiredrecord of anyrequired

    The declared fields; a write-only one may hold a secret marker

  • expectobject
    Fields
    • action"none" | "create" | "update" | "replace" | "delete"required
    • replacestring[]required

Output

  • idstringrequired

    at least 1 character

  • stateobjectrequired
    Fields
    • size2 | 4

      Each box's vCPUs, 2 (the default) or 4; a box that exists keeps its shape

    • memoryinteger

      Each box's memory in GB: 4 with 2 vCPUs, 8 (the default), 16 or 32 with 4

    • diskinteger

      Each box's disk in GB, billed in every state; default 10

      at least 2

    • imagestring

      The template a box runs: by default Sanoma's box image of this release, registered in the workspace; or agent37-base, or another template of the workspace

      at least 1 character

    • region"us" | "eu" | "ap-south"

      Where boxes run, us (the default); eu and ap-south run vm and performance boxes only

    • type"default" | "vm" | "performance"

      default (shared CPU, the default), vm (a kernel of its own) or performance (cores held for it)

    • idstring

      What the declaration is bound by: boxes are made as people open them

    • healthyboolean

      Whether the key lists the workspace's instances

  • handlestring

    The driver's data for the object, opaque: pass it back unchanged

delete

agent37.instance.deletewritesafe to retry

Delete a instance; done already when it is gone

Input

  • idstringrequired

    at least 1 character

  • staterecord of any
  • handlestring

    The driver's data for the object, opaque: pass it back unchanged

Output

  • idstringrequired

    at least 1 character

  • gonetruerequired

box

open

agent37.box.openaccesssafe to retry

Open the box name (find it or make it, labelled with group, wake it, start Sanoma's runner and put pnpm in it) and mint a signed link to its runner's port. A box of that name in another group, or in none, is refused. Opens of one name at once in two processes can make two boxes

Input

  • namestringrequired

    The box's name, which it is found by

    at least 1 character

  • groupstringrequired

    The group the box is labelled with, such as the company it is for

    at least 1 character

  • networkstring[]

    The domains and addresses a new box may reach, up to 100; anywhere when left out. A box that exists keeps its own

    at least 1 item, at most 100 items, each item: at least 1 character

  • ttlintegerrequired

    How long the link works, in seconds: 60 to 604800 (7 days). It cannot be revoked sooner

    at least 60, at most 604800

Output

  • idstringrequired

    The box's instance

  • urlstringrequired

    The link: the port's URL with its token in a37_token

  • expiresAtstringrequired

    When the link stops working, ISO 8601

    format date-time, matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

  • protocolintegerrequired

    The runner protocol of this release, which the box's runner now speaks

expose

agent37.box.exposeaccesssafe to retry

Mint a signed link to another port of the box name, such as an agent's bridge

Input

  • namestringrequired

    The box's name, which it is found by

    at least 1 character

  • portintegerrequired

    The port

    at least 1, at most 65535

  • ttlintegerrequired

    How long the link works, in seconds: 60 to 604800 (7 days). It cannot be revoked sooner

    at least 60, at most 604800

Output

  • urlstringrequired

    The link: the port's URL with its token in a37_token

  • expiresAtstringrequired

    When the link stops working, ISO 8601

    format date-time, matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

sleep

agent37.box.sleepwritesafe to retry

Put the box name to sleep, its memory kept; nothing when there is none

Input

  • namestringrequired

    The box's name, which it is found by

    at least 1 character

Output

  • idsstring[]required

    The instances it acted on

discard

agent37.box.discardwritesafe to retry

Delete the box name, or every box labelled with group

Input

  • namestring

    The box's name, which it is found by

    at least 1 character

  • groupstring

    The group the box is labelled with, such as the company it is for

    at least 1 character

Output

  • idsstring[]required

    The instances it acted on

list

agent37.box.listreadsafe to retry

The boxes labelled with group

Input

  • groupstringrequired

    The group the box is labelled with, such as the company it is for

    at least 1 character

Output

  • boxesobject[]required
    Each item
    • idstringrequired
    • namestringrequired
    • awakebooleanrequired

      It is neither asleep, stopped nor failed: it counts toward the workspace's limit

These pages describe sanoma 0.11.24.