NylorunDocsBeta
Runtime APIAgents

Get an Agent

GET
/v1/agents/{agentId}

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

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

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();const agent = await client.agents.get("users/alice/assistant");
{  "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"}

Create, find or move an Agent PUT

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.

Delete an Agent DELETE

Deletes the Agent, its vault with every secret, and its disk. Its sessions keep its id; their next turn is refused (`agent_unavailable`) until an Agent with this id exists again.