Create, find or move an Agent
Creates the Agent, its vault and its compute from a saved agent manifest, within the Tenant's limits, or answers the one with this id, so get-or-create is one call. manifest: "name" records that it tracks the manifest (its latest version, and each version saved later) and "name@n" that it is pinned; the version it runs is resolvedVersion. On an existing one, labels replace, owner sets or (with null) clears the owner guard, and manifest moves it with its id, disk, vault and sessions: a harness-only change applies at once (each session's next turn runs it), a runtime change of a pod at its next start (targetVersion, waitingFor: start), and a version that adds a required secret once a value is set (waitingFor: secrets). Its manifest's name, kind, harness and storage are fixed (409 agent_fixed_field): fork it to change them. ?dryRun=true answers the move's plan and changes nothing. Creating an Agent opens no session. Kind pod needs sandbox pods (nylorun local sandbox enable) and is created at once.
AuthorizationBearer <token>An application key of the Tenant (PUT /v1/tenant/keys/{keyId}), or Studio's key, derived from the admin key. With Nylorun-Subject and Nylorun-Scopes, it acts for that person, narrowed to those scopes. Never accepted from a browser (Origin).
agentId*stringThe Agent id, percent-encoded: users%2Falice%2Ftriage for users/alice/triage
dryRun?stringtrue: the plan of moving the existing Agent, with nothing changed
"true""false"Nylorun-Protocol*stringThe protocol version, 18
Nylorun-Subject?stringThe person an application key acts for
Nylorun-Scopes?stringThe subject's space-separated scopes; required with a subject
application/json- body
requestId?string1 <= lengthmanifest*stringname (tracking) or name@n (pinned)
owner?|1 <= lengthlabels?from?The Agent, or with dryRun the plan of its move
application/json- response
id*stringmanifest*stringresolvedVersion*integer0 < valuemanifestHash*stringtracking*string"tracking""pinned"targetVersion*|0 < valuewaitingFor*|"secrets""start"nullfailedVersion*|0 < valuestartCheck*|nullkind*string"virtual""pod""none"harness*stringowner*string|nulllabels*state*stringworking, sleeping, input_required, failing or paused; an open set
attention*array<>desired*string"on""off"nextWakeAt*string|nullcompute*runtime*limits*sessions*array<>slots*array<>disk?forkedFrom*|nulllastUsedAt*stringcreatedAt*stringupdatedAt*stringimport { createClient } from "@nylorun/agents";const client = await createClient();const agent = await client.agents.put(`users/${user.id}/assistant`, { manifest: "assistant", // tracks the latest version; "assistant@3" pins one owner: user.id, labels: { team: "ops" },});// plan(id, input) sends ?dryRun=true and changes nothing{ "id": "string", "manifest": "string", "resolvedVersion": 1, "manifestHash": "string", "tracking": "tracking", "targetVersion": 1, "waitingFor": "secrets", "failedVersion": 1, "startCheck": { "from": 1, "startedAt": "string" }, "kind": "virtual", "harness": "string", "owner": "string", "labels": { "property1": "string", "property2": "string" }, "state": "string", "attention": [ { "state": "paused", "sessionId": "string", "reason": "string" } ], "desired": "on", "nextWakeAt": "string", "compute": { "state": "string", "pod": { "desired": "running", "observed": "creating", "volumeGeneration": 0, "hostEpoch": 0, "reason": "string", "imageDigest": "string" } }, "runtime": { "image": "string", "resources": { "cpus": 0, "memory": "string" }, "storage": "string", "network": { "allowedHosts": [ "string" ] }, "harness": "string", "lifecycle": { "idle": "string", "deleteAfter": "string" }, "setup": [ { "command": "string", "cwd": "string", "timeout": "string" } ], "files": [ { "artifactId": "string", "version": 1, "path": "string" } ], "limits": { "artifacts": { "fileBytes": 1, "totalBytes": 1 }, "skills": { "totalBytes": 1 }, "disk": { "versionBytes": 1, "versionEntries": 1 } }, "secrets": { "property1": { "type": "environment_secret", "allowedHosts": [ "string" ], "inject": { "header": "string", "format": "string" }, "required": true, "description": "string" }, "property2": { "type": "environment_secret", "allowedHosts": [ "string" ], "inject": { "header": "string", "format": "string" }, "required": true, "description": "string" } } }, "limits": { "artifacts": { "fileBytes": 0, "totalBytes": 0 }, "skills": { "totalBytes": 0 }, "disk": { "versionBytes": 0, "versionEntries": 0 } }, "sessions": [ { "id": "string", "ownerUserId": "string", "status": "string", "activeTurnId": "string" } ], "slots": [ { "name": "string", "type": "string", "required": true, "set": true } ], "disk": { "latestVersion": 1, "operation": { "kind": "snapshot", "version": 1, "startedAt": "string" } }, "forkedFrom": { "agent": "string", "disk": 1 }, "lastUsedAt": "string", "createdAt": "string", "updatedAt": "string"}Get the Runtime API's document GET
This document. `/openapi.json` is the same.
Get an Agent GET
Its manifest version, what its environment runs, labels, owner guard, derived state with the sessions behind it (`attention`), compute, secret slots, disk, and its sessions (acting for a person, only theirs).