Scripts in the console¶

The concept behind tools is explained in Tools.

A script is a program of your own that the model calls as one tool. Core runs it in a sandbox without internet and returns the output and the files it made. In the Scripts section, under Tools in the navigation, you upload a script, write new versions of it, try it, and decide which libraries your organisation's scripts may use. Each script becomes the tool script__<name>, which appears in the Overview and fits in a toolset. How an application does the same is on Scripts through the API.

You need an administrator account of the organisation, and the organisation has to permit both tooling and computer under Permitted capabilities. Creating and editing a script, and approving a package, are done on a larger screen; on a phone the lists are read only.

Switch scripts on for a key¶

A key is offered your scripts when it has both tooling and computer enabled on Keys. It does not need Use a computer under System tools: that switch hands the model a shell, and a key that should only run your tested programs can leave it off. Also enable files if the model should work on a turn's attachments, and artifacts if you want the files a script makes.

The key's policy still decides by name: the rules about Tools must permit script__<name>.

The list¶

Search by name or description, or filter by label. Select a row to open the script.

Create a script¶

Select New script. The form has six steps.

1. Name and description.
   • Name: lower-case letters, digits, - and _. The model sees script__<name>. The name never changes after saving, because policy rules, usage and the audit trail record it.
   • Description for the model: when the model should use this tool, at most 1024 characters. The model sees only the name, this text and the parameters.
   • Labels, optionally.
2. Starting.
   • Entrypoint: the program to run, in 1 to 16 parts, each its own argument, such as python3 and main.py. Add a part with Part. It is not a shell line: pipes, && and redirections do not work.
   • Timeout, optionally, in seconds. A call stops at the shorter of this timeout and the calling key's limit. Empty lets the key's limit apply.
3. Parameters. The arguments the model gives, as a JSON Schema. Build it field by field in the Visual view, paste it in the JSON view, or have Describe what you need make a draft. A field's description is what the model reads. Leave it empty for a script without arguments.
4. Files. Every file of the package. Text file adds a file you type here, such as main.py. From uploads picks a file from your organisation's uploads, or uploads a new one with Upload a file; use it for binary files such as a template or a font. Saving copies the upload into the version, so removing the upload later leaves the version whole. A path is relative and may not contain .., \ or a leading /. The meters show the limits: at most 200 files and 20 MiB in total.
5. Packages. The libraries the script needs beyond what the sandbox image ships, see Packages. Search an approved package and add it; only approved packages can be chosen.
6. Asynchronous tool, optionally. Whether the model may start the script as a task that keeps running after the turn: Start in the background, Longest run (seconds) and Safe to send again, as described under Asynchronous tool. The default is Never. See Run a tool in the background for what happens then.

The panel beside the form shows How the model sees it and the limits of a call: output returned up to 32 KiB, at most 10 artifacts per call, and no internet. Saving makes version 1; you can try it after that.

Your program reads the model's arguments as JSON from standard input or from the file named by ARTIFIC_ARGUMENTS, and writes the files it wants returned to the directory named by ARTIFIC_OUTPUTS. What the script receives has an example.

A script's page¶

A script's page has three tabs.

• Overview shows the Description for the model, the Parameters with the required ones marked, the facts of the latest version (Tool, Entrypoint, Timeout, Latest version, Files), the packages it names and where it is Used in: the agents that name the script and the toolsets that reach it.
• Versions lists every version with who wrote it and when. Tick two versions and the Compare panel beside the list shows which fields and which files changed.
• Files lists the files of one version with their size and digest. A text file shows a preview; a binary or very large file can be downloaded with Download.

Write a new version¶

A saved version never changes. Select New version to write the next one. The form opens with the latest version's package filled in: text files to edit, binary files carried along, its packages and its Asynchronous tool setting. Change what you need and select Save as v…. The previous version stays as it is, and calls that pin it keep it.

When everything is exactly the same as the latest version, Core saves nothing and the form says Same as the latest version, nothing saved.

A request or an agent uses the latest version unless it pins one; see Offer it to the model.

Drafts¶

Save as draft v…, beside the save button, writes the version as a draft: no key sees or runs it until you publish it, and calls keep running the published version. A new script saved as a draft is marked draft in the list and is no tool for any key yet. Versions marks each draft draft and shows it under the list with Publish and Discard draft, each behind a confirmation. A draft an agent's draft pins cannot be discarded until that agent's draft changes; the confirmation names it.

Call variables¶

A script can read values your application sends with each request, such as a customer's account id. In the form, the At call time card lists them; select Add a variable, type a name and fill in the same fields as for an API connector: type, Required, description, allowed values and default. A script declares them by hand, because its code has no marker to read them from, and none can be Secret: the shell tools can read a script's files. The script reads them from the file ARTIFIC_VARIABLES names (Pass a customer's value to a tool). A name that is also an argument or an install value is refused. They belong to the version, so saving a change writes a new one, and a new version starts with the call variables and install values of the latest.

Try a script¶

Select Try it on the script's page. Choose the key to run as under Run as, the Version, and fill in the arguments, which are made from that version's parameters. When the version declares call variables, a field for each stands between the key and the version. Then select Run. A key that lacks tooling or computer is marked with what it lacks, and cannot run the script.

A trial run is a real call: it runs in the sandbox, counts as a call of that key and costs sandbox time. The result shows:

• Succeeded, Error in the script (an exit code other than 0) or Stopped after … seconds (the timeout passed), with the exit code and the time it took;
• the standard output and standard error, cut at 32 KiB;
• Artifacts: the files the script made, kept as artifacts;
• Left out: files left on the computer, because there were more than 10, a file was too large or not a regular file, or the key has no artifacts.

When the call did not reach the sandbox, Not run shows Core's reason, such as a region the key may not reach, arguments that do not meet the parameters, or a package that is no longer approved.

Delete a script¶

Select Delete on the script's page and confirm. Its versions and their files go with it. Toolsets and aliases refer to the name and do not block a delete. While an agent uses the script, the dialog lists those agents; remove the script there first.

Packages¶

A script can import only approved libraries. The Packages tab, beside Scripts, lists everything your organisation's scripts may use. The Origin column says where an approval comes from:

On an installed script's page a package can also be marked publisher: a package only the publisher of its bundle approved, accepted when you installed it and valid for that script alone. It is not on this tab.

Filter by ecosystem (PyPI or npm) or by origin. Used by names the scripts whose latest version names the package. When a library you need is not on the list, approve it for your organisation, or ask your operator to approve it for every organisation.

A version must name every package it needs beyond the image, including the packages those packages depend on: Core installs offline and resolves no dependencies. A missing dependency shows up as an import error the first time you try the script.

Approve a package¶

1. Select Approve package.
2. Choose the Kind of package: PyPI · wheel or npm · tarball.
3. Choose the file. For PyPI that is the wheel (.whl) from PyPI, never a source distribution: the sandbox builds no packages. For npm it is the tarball (.tgz) as npm pack writes it.
4. Name and Version are filled in from the filename. A package is approved for exactly one version; approve another version separately.
5. Check the Checks: the kind of file, its size (at most 32 MiB) and whether it is new to the list. For a wheel the console shows its Python and platform tags; Core checks on approval whether the wheel fits the sandbox and refuses one that does not.
6. Select Approve.

Your organisation holds at most 500 approvals; the count is at the top of the tab. An approval reaches no other organisation. When the organisation above yours keeps key management to itself, its administrators approve and revoke, and your attempt fails with Core's reason.

Revoke a package¶

Open the row menu of one of your organisation's own packages and choose Revoke. The dialog names the scripts that use it. Revoking deletes the file, and versions that name the package can no longer run: their calls answer that the package was revoked, until you write a version without it. Approve exactly the same file again later and those versions run again; another file does not.

Packages approved for the platform or shipped in the image are revoked only by your operator.

Share a script¶

Pick the script under Scripts when you publish a version of a bundle; its files and the packages only your organisation approved travel with it. What the subscriber sees and accepts is on Publish and install in the console. A script installed from a bundle lists its origin in the Origin column; while it is linked, it offers no New version and cannot be deleted.

What is recorded¶

Each call of a script is usage of its key: one tool call named script__<name>, plus the Sandbox time of the computer it ran on (Computers in the console). The audit trail records creating, versioning and deleting a script, approving and revoking a package, and each call with its script, version, duration and exit code. Arguments, output and file names never reach the audit trail.