NylorunDocsBeta
Runtime API

Agents SDK

The TypeScript client your app server uses to call the Runtime API.

npm install @nylorun/agents
import { createClient } from "@nylorun/agents";

const client = await createClient();

const session = await client.createSession({
  agent: "teams/support", // the Agent it runs on: its manifest version, sandbox, and secrets
  ownerUserId: user.id,
});
const sent = await session.input("Where is order demo-123?", {
  idempotencyKey: crypto.randomUUID(),
});
// sent.status: "accepted", or "queued" while another turn runs

@nylorun/agents calls the Runtime API with an application key. Run it on your server, never in a browser: the Runtime refuses a key sent with an Origin header. It requires Node 24 or later.

Each endpoint page in this section shows the SDK call first, then cURL.

The client

CallEndpoints
client.agentManifests (save, plan, saveFolder, planFolder, get, list, versions, delete)Agent manifests
client.agentManifests.source(), sourceFile(), sourceDiff()A version's folder, one of its files, two versions compared
client.filesDefinition files
client.agents (put, plan, get, list, page, stop, restart, reset, delete)Agents
client.agents.secretsSecrets
client.agents.snapshot(), restore(), versions(), deleteVersion()Disk versions
client.agents.fork(), planFork()Fork an Agent
client.agents.events()An Agent's events
client.agents.triggers(), pauseTrigger(), resumeTrigger(), runTrigger(), rotateWebhookSecret(), runs()Triggers
client.agents.memoriesMemory
client.createSession(), client.session(id), client.sessions.page()Sessions API
session.toolCalls()Tool calls
session.trace(turnId)A turn's trace
client.artifactsArtifacts
client.hostFeatures(), client.access.jwks()Runtime
client.as(subject)Any of the above, for one signed-in person

client.agentManifests.plan(input) answers what a save would do: the version, each change, warnings, errors, and the Agents it would move. client.agents.plan(id, input) answers what moving an Agent to another version would do, and planFork() what a fork would do. None of them makes anything. The client is AgentsClient; client.agents is an AgentInstancesClient.

Agent manifests

import { runtimeFiles } from "@nylorun/agents";

const config = await runtimeFiles("/workspace/config", {
  "settings.json": JSON.stringify({ region: "eu" }),
});

await client.agentManifests.save(
  {
    agent: assistant,
    name: "support",
    runtime: {
      kind: "virtual",
      network: { allowedHosts: ["api.github.com"] },
      files: [config.entry],
    },
  },
  { files: config.bytes },
);
await client.agents.put("teams/support", { manifest: "support" });

A manifest's files are sent by hash, and the Runtime compiles them and keeps them as the version's source:

import { packFolder } from "@nylorun/agents";

const folder = await packFolder("agents/triage");
await client.agentManifests.planFolder(folder);
await client.agentManifests.saveFolder(folder);

const source = await client.agentManifests.source("triage", 3); // its files: path, size, sha256
const diff = await client.agentManifests.sourceDiff("triage", 2, 3);
// diff.added, diff.removed, diff.changed by path and SHA-256; diff.unchanged counts the rest

A version saved as JSON has no source: source() and sourceDiff() answer 404 for it. folderOfManifest() writes a saved manifest out as files, the one npx nylorun export --folder <name> writes:

import { folderOfManifest } from "@nylorun/agents";

const saved = await client.agentManifests.get("triage");
const { files, exact, notes } = folderOfManifest(saved.manifest);
// files: path → text or bytes; exact: it compiles back to the same manifest

A manifest written as three files, a format that is deprecated, saves the same way as a document. composeManifest() reads it and warns; npx nylorun migrate folder <dir> converts it to AGENT.md and its files. See Three files.

import { composeManifest } from "@nylorun/agents";

const composed = await composeManifest("agents/triage");
await client.agentManifests.save(composed);
ExportRole
agentManifest(input)Checks an agent manifest v8, or builds one from an agent, against the schema the Runtime enforces; fills in manifestSchemaVersion and drops $schema.
runtimeFiles(path, contents)Hashes files for a runtime section's files entry. Returns entry for the manifest and bytes for agentManifests.save(input, { files }), which uploads those the Runtime lacks. At most 2 GiB per file.
packFolder(dir), isAgentFolder(dir)Lists an agent manifest's files with their sizes and SHA-256, for agentManifests.planFolder() and saveFolder(): skips .git, node_modules, and what the folder's .nyloignore names, and resolves extends in runtime.json (the packed file is the merge). Whether a folder holds an AGENT.md.
checkFolder(folder), diagnosticLine(diagnostic)Compiles a packed folder offline with the Runtime's compiler: { manifest?, diagnostics, compiler }; a diagnostic as file:line:column severity: message.
folderOfManifest(manifest, { files? })The files that compile back to a manifest: { files, exact, notes }. With files, the bytes behind the manifest's hashes, it writes skills' files too.
ignoreMatcher(text), FOLDER_IGNORE_FILEA matcher for gitignore-syntax text, as packFolder() reads .nyloignore; the file's name.
AGENT_FOLDER_MEDIA_TYPEapplication/vnd.nylorun.folder+json, the content type of a folder sent to PUT /v1/agent-manifests/{name}.
harnessSectionOf(agent.manifest), sectionGaps(manifest)The harness section agentManifests.save() makes from a built agent's or flow's manifest; the gaps the Runtime refuses between a manifest's two sections.
composeManifest(dir), manifestFolders(dir)The deprecated three-file format: reads the agent.manifest.json in a folder, with the harness and runtime files it names, into a manifest to save, and warns; lists the folders nylorun apply would read.
requirementGaps(requires, runtime)Where a runtime section misses what a harness file's requires asks.
AGENT_EVENT_TYPES, AGENT_STATESThe event types client.agents.events(id, { types }) filters on, and an Agent's states.
RUNTIME_LIMIT_DEFAULTSThe default of each Runtime limit.

The types of what these calls answer are exported too, among them AgentManifestSource, AgentManifestSourceDiff, AgentFolderDiagnostic, SessionUsageTotals, ModelCall, and CostSplit (a session's or a model call's cost by token kind: input, cacheRead, cacheWrite, output).

agentManifests.save(input, { ifMatch }) refuses a save over a newer version with 412 manifest_changed. A manifest whose sections do not fit, or that misses its requires, throws ManifestGapsError before anything is sent, or the Runtime answers 422 manifest_inconsistent. A save moves every Agent that tracks the manifest. See Saving manifests and Agents in Guides.

AG-UI and A2A

The AG-UI and A2A endpoints are for those protocols' clients. createAgUiHandler() from @nylorun/agents/ag-ui and createA2aHandler() from @nylorun/agents/a2a serve them from your own server. Their agents option lists Agent ids: every caller's session runs on that Agent's disk and secrets. createA2aClient() calls an Agent over A2A, and verifyA2aPush() checks its push deliveries; see A2A client.

Connect

import { createClient } from "@nylorun/agents";

const client = await createClient(); // environment, then the project link

const deployed = createClient({
  url: process.env.NYLORUN_RUNTIME_URL!,
  key: process.env.NYLORUN_SERVER_KEY!,
});

With a destination, createClient() returns the client at once. Without one, it returns a promise and resolves the connection in this order:

  1. NYLORUN_RUNTIME_URL and NYLORUN_SERVER_KEY, both set
  2. The project link that nylorun start wrote, in the nearest .nylorun/ from the working directory upward, never at or above the home directory

There is no tenant option: a Runtime serves one Tenant. When nothing resolves, or the link or credentials.json does not validate, createClient() throws ConnectionError (connection_missing) naming what it tried.

Destination

Prop

Type

Pass key or token, not both. The client sends Nylorun-Protocol: 18. The first request checks the Runtime's /health and throws IncompatibleRuntimeError when the Runtime does not serve protocol 18 with the features the client needs, such as usage-by-kind: it needs Runtime 0.29 or later. A client with a token skips that check.

Act for a person

const forUser = client.as(user.id, { scopes: ["sessions:own"] });
const sessions = await forUser.sessions.page();

client.as(subject) sends Nylorun-Subject and Nylorun-Scopes on every call. The Runtime limits it to those scopes and to that person's own sessions. Your server signs the person in; nothing is minted or cached.

An application key reaches every Agent. Acting for a person, reading an Agent takes sessions:own, agents:read, or agents:write; making, moving, or deleting an Agent or writing its secrets takes agents:write. Saving or deleting an agent manifest takes agent-manifests:write, which a trusted issuer's token never carries. A token reaches only the Agents its issuer's agents grants allow.

resolveConnection

import { resolveConnection } from "@nylorun/agents";

const { url, key, source } = await resolveConnection();
// source: "options" | "environment" | "project-link"

The same resolution as createClient(), without building a client. It takes { url?, key?, cwd? }; cwd is where to look for the project link.

Errors

import { RuntimeError } from "@nylorun/agents";

try {
  await session.input(text, { idempotencyKey });
} catch (error) {
  if (error instanceof RuntimeError && error.status === 409) {
    // the same idempotencyKey with different content,
    // or session_busy when sent with delivery: "reject"
  }
  throw error;
}

Client errors

ClassThrown whenFields
RuntimeErrorThe Runtime answers with an error statusstatus, body
IncompatibleRuntimeErrorThe Runtime's protocol is outside the client's range, or lacks a feature the call needscompatibility, remedy, host
ConnectionErrorcreateClient() finds no connectioncode

IncompatibleRuntimeError.remedy says what to upgrade: for an older Runtime, the Runtime itself (on a local Tenant, restart it with the current nylorun: npx nylorun start); for an older client, @nylorun/agents.

RuntimeError.body is the Runtime's JSON error, with the code in body.code. A refused key or token is status 401: credential_required when none was sent, credential_invalid when the Tenant does not know the key or the token fails a check. Each endpoint page lists the statuses it answers with; Troubleshooting explains the common codes.

Definition errors

ClassThrown whenFields
AgentBuildErrorAn agent is invaliddiagnostics
WorkflowBuildErrorA flow is invaliddiagnostics
McpErrorAn MCP server is invalid, such as a stdio servercode
SkillsErrorA skills folder cannot be loadedcode, diagnostics
PluginErrorA plugin package cannot be loadedcode, diagnostics
ManifestGapsErrorAn agent manifest's sections do not fit, or it misses its requires; nothing was sentmanifest, gaps
ComposeErrorcomposeManifest() cannot read or check a manifest filepath
FolderErrorpackFolder() cannot read a folder, or it is over an agent manifest's limitsdir
FolderInvalidErrorAn agent manifest does not compile; planFolder() and saveFolder() sent nothingdir, diagnostics

Entry points

ImportContents
@nylorun/agentsThe client, the agent builder, tools, the skill and plugin loaders, agentManifest(), runtimeFiles(), composeManifest(), packFolder(), checkFolder(), folderOfManifest(), and errors
@nylorun/agents/clientcreateClient, the client classes, agentManifest(), and runtimeFiles(), without composeManifest() and packFolder(), which read files, or folderOfManifest()
@nylorun/agents/defineThe agent builder and tools, without the file-reading .skills() and .plugin()
@nylorun/agents/ag-uicreateAgUiHandler()
@nylorun/agents/a2acreateA2aHandler(), createA2aClient(), verifyA2aPush(), readInteraction(), readProgress(), readTelemetry(), readFiles(), listTurnChanges(), A2A_EXTENSIONS, and A2aError

Defining agents, tools, and flows is covered in Build.

On this page