Fork an Agent
Copies the Agent into a new one, which is how an Agent changes what is fixed for its life: a new Agent id, made from manifest (default the source's manifest name, tracking, at its latest version), its disk started from a version of this one's (disk: latest, the default, takes a snapshot first; a version number; or empty) and its secrets copied inside the Runtime (secrets: copy, the default, copies those the new manifest declares; none). On a fork onto other setup the new manifest's setup runs on the copied disk before its first turn. This Agent keeps what it runs, its disk and its sessions. dryRun answers the plan and makes nothing. To move an Agent to another version of the same manifest, with the same kind, harness and storage, PUT it instead.
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
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 <= lengthid*stringAn Agent id, such as triage or users/alice/triage
manifest?stringname (tracking) or name@n (pinned)
disk?||secrets?string"copy""none"labels?owner?|1 <= lengthdryRun?booleanThe plan (dryRun)
application/json- response
dryRun*truetrueplan*import { createClient } from "@nylorun/agents";const client = await createClient();const { agent, plan } = await client.agents.fork("users/alice/assistant", { id: "users/alice/assistant-trial", manifest: "assistant@4", disk: "latest", secrets: "copy",});// planFork(...) answers the plan and makes nothing{ "dryRun": true, "plan": { "source": "string", "id": "string", "kind": "virtual", "manifest": { "name": "string", "version": 1 }, "disk": 1, "setup": true, "secrets": { "copied": [ "string" ], "dropped": [ "string" ], "missing": [ "string" ] }, "changes": [ { "path": "string", "from": null, "to": null } ], "sessions": 0, "memories": 0 }}Restart an Agent on its pending version POST
Applies a version the Agent waits to apply: a running pod stops, so the next turn starts it on the version, on the same volume; a stopped or failed one is asked to run at once. `retry: true` first moves it to the version that failed to start (`failedVersion`) again. Kinds `virtual` and `none` apply a version at once, so there is nothing to wait for. Refused during a turn (`agent_busy`). The body is optional.
Save an agent manifest PUT
Saves the manifest as its next version, or answers the latest unchanged when nothing differs. Every Agent that tracks the manifest moves to the new version: at once, at its pod's next start for a runtime change a pod applies only when it starts, or once a required secret the version adds is set; a pinned one stays, and so does one whose kind, harness or storage the version changes (`agents_behind`). The Runtime checks the harness and runtime sections against each other: a custom harness needs a pod with an image, every credential the harness names is a declared slot of the right type, and the runtime's kind gives the loop the sandbox it needs; every gap is named in one `422 manifest_inconsistent` (`details.gaps`). `If-Match: <version>` refuses the save with `412 manifest_changed` when the latest version is no longer the one you read (`0` for a manifest that does not exist yet). With `?dryRun=true` the answer is the plan: the changes by section, every reason a save would be refused (`errors`, the gaps first), warnings, the Agents it would move (`moves`) and how many stay on older versions (`behind`); nothing is saved. Clients compose the authoring files and drop their `$schema` before they send one document. With `Content-Type: application/vnd.nylorun.folder+json` the body is an agent folder by hash instead (feature `agent-folders`): every file uploaded first with `PUT /v1/files/sha256:<hex>`, the Runtime compiles it with `@nylorun/core/folder`, a folder that does not compile is `422 folder_invalid` (`details.diagnostics`, each with its file, line and column), and the version keeps the folder as its source; the plan adds the compiled `manifest`, the compiler's `diagnostics` and `compiler`.