NylorunDocsBeta
Runtime APIAgents

Restart an Agent on its pending version

POST
/v1/agents/{agentId}/restart

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.

Authorization

headerAuthorizationBearer <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).

Path Parameters

agentId*string

The Agent id, percent-encoded: users%2Falice%2Ftriage for users/alice/triage

Header Parameters

Nylorun-Protocol*string

The protocol version, 18

Nylorun-Subject?string

The person an application key acts for

Nylorun-Scopes?string

The subject's space-separated scopes; required with a subject

Request Body

application/json
  1. body
requestId?string
Length1 <= length
retry?boolean

Response Body

The Agent

application/json
  1. response
id*string
manifest*string
resolvedVersion*integer
Range0 < value
manifestHash*string
tracking*string
Value in"tracking""pinned"
targetVersion*|
Range0 < value
waitingFor*|
Value in"secrets""start"null
failedVersion*|
Range0 < value
startCheck*|null
kind*string
Value in"virtual""pod""none"
harness*string
owner*string|null
labels*
state*string

working, sleeping, input_required, failing or paused; an open set

attention*array<>
desired*string
Value in"on""off"
nextWakeAt*string|null
compute*
runtime*
limits*
sessions*array<>
slots*array<>
disk?
forkedFrom*|null
lastUsedAt*string
createdAt*string
updatedAt*string
import { createClient } from "@nylorun/agents";const client = await createClient();await client.agents.restart("users/alice/assistant"); // { retry: true } retries a failed version
{  "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"}

Reset a pod Agent POST

A new pod on a new, empty volume with the recipe applied; the old pod and volume are deleted. The way out of `agent_lost`. Refused during a turn (`agent_busy`).

Fork an Agent POST

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.