Agents SDK
The TypeScript client your app server uses to call the Runtime API.
npm install @nylorun/agentsimport { 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
| Call | Endpoints |
|---|---|
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.files | Definition files |
client.agents (put, plan, get, list, page, stop, restart, reset, delete) | Agents |
client.agents.secrets | Secrets |
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.memories | Memory |
client.createSession(), client.session(id), client.sessions.page() | Sessions API |
session.toolCalls() | Tool calls |
session.trace(turnId) | A turn's trace |
client.artifacts | Artifacts |
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 restA 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 manifestA 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);| Export | Role |
|---|---|
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_FILE | A matcher for gitignore-syntax text, as packFolder() reads .nyloignore; the file's name. |
AGENT_FOLDER_MEDIA_TYPE | application/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_STATES | The event types client.agents.events(id, { types }) filters on, and an Agent's states. |
RUNTIME_LIMIT_DEFAULTS | The 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:
NYLORUN_RUNTIME_URLandNYLORUN_SERVER_KEY, both set- The project link that
nylorun startwrote, 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
| Class | Thrown when | Fields |
|---|---|---|
RuntimeError | The Runtime answers with an error status | status, body |
IncompatibleRuntimeError | The Runtime's protocol is outside the client's range, or lacks a feature the call needs | compatibility, remedy, host |
ConnectionError | createClient() finds no connection | code |
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
| Class | Thrown when | Fields |
|---|---|---|
AgentBuildError | An agent is invalid | diagnostics |
WorkflowBuildError | A flow is invalid | diagnostics |
McpError | An MCP server is invalid, such as a stdio server | code |
SkillsError | A skills folder cannot be loaded | code, diagnostics |
PluginError | A plugin package cannot be loaded | code, diagnostics |
ManifestGapsError | An agent manifest's sections do not fit, or it misses its requires; nothing was sent | manifest, gaps |
ComposeError | composeManifest() cannot read or check a manifest file | path |
FolderError | packFolder() cannot read a folder, or it is over an agent manifest's limits | dir |
FolderInvalidError | An agent manifest does not compile; planFolder() and saveFolder() sent nothing | dir, diagnostics |
Entry points
| Import | Contents |
|---|---|
@nylorun/agents | The client, the agent builder, tools, the skill and plugin loaders, agentManifest(), runtimeFiles(), composeManifest(), packFolder(), checkFolder(), folderOfManifest(), and errors |
@nylorun/agents/client | createClient, the client classes, agentManifest(), and runtimeFiles(), without composeManifest() and packFolder(), which read files, or folderOfManifest() |
@nylorun/agents/define | The agent builder and tools, without the file-reading .skills() and .plugin() |
@nylorun/agents/ag-ui | createAgUiHandler() |
@nylorun/agents/a2a | createA2aHandler(), createA2aClient(), verifyA2aPush(), readInteraction(), readProgress(), readTelemetry(), readFiles(), listTurnChanges(), A2A_EXTENSIONS, and A2aError |
Defining agents, tools, and flows is covered in Build.