NylorunDocsBeta
Build

Build

Define an agent, add only what it needs, compose flows, and save it as an agent manifest.

npx nylorun init agents/support
npx nylorun check agents/support
npx nylorun apply agents/support --agent
npx nylorun chat support --message "Where is order A-1001?"

You author an agent as an agent manifest: an AGENT.md with its name, description, and instructions, and optional JSON files. init writes the folder, check compiles it offline, apply --agent saves it as an agent manifest and makes the Agent support from it, and chat opens a session on that Agent. Folders are the default; the Agents SDK builder, Agent() exported from agents/index.ts, suits agents assembled in code, saved with client.agentManifests.save({ agent, runtime }).

Either way, the agent becomes the manifest's harness section, beside a runtime section that says what it runs in. The Runtime runs each agent from its manifest and the files saved with it, and never calls your code during a session. Your services are reached as HTTP tools and remote MCP servers.

An agent's body is either a ReAct loop, where the model decides what to call, or a flow, where its stages decide what runs next. Start with an agent manifest or the Agent builder, add only the parts that agent uses, then compose when more than one agent or a fixed path is required.

Agents

PartIn a folderIn the builderPage
InstructionsThe AGENT.md body, instructions/*.md.instructions("…")Instructions
Toolstools/<name>.json.tools(http({ name, input, url }))Tools
MCPmcp.json.mcp({ github: { type, url } })MCP
Skillsskills/<name>/SKILL.md.skills("./assistant-skills")Skills
Agent Pluginsplugins/<name>/.plugin("./plugins/github")Plugins
Requirementsruntime.json, the runtime section itself.requires({ sandbox: "pod" })Saving manifests
Memorymemory in AGENT.mdsave({ agent, runtime, memory })Agent memory

Do not set a model on the agent. The Tenant chooses it; see Models. A session gets a sandbox and secrets from the Agent it runs on; see Agents.

Compose

PatternIn a folderIn the builderPage
Subagentsagents/<id>/.subagents(researcher)Subagents
Flow agentsflow.json over agents/<id>/Agent({ id: "report" }).pipe(researcher, analyst)Flow agents
Pipe{ "chain": [{ "agent": "researcher" }, { "agent": "analyst" }] }.pipe(researcher, analyst)Pipe
Switch{ "switch": { "cases": { … }, "default": { … } } }.switch({ bug, docs, default: general })Switch
Parallel{ "parallel": { "security": { … }, "style": { … } } }.parallel({ security, style })Parallel
Map{ "map": { "each": { "agent": "writer" } } }.map(writer)Map
Loop{ "loop": { "run": { … }, "verify": { … }, "max": 3 } }.loop(coder, { verify: tester, max: 3 })Loop

Serve your users

Your app signs people in, holds the application key, and calls the Runtime for each person. The Runtime never signs anyone in.

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

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

const agentId = `users/${authenticatedUser.id}/support`;
await client.agents.put(agentId, { manifest: "support", owner: authenticatedUser.id });

const asUser = client.as(authenticatedUser.id, {
  scopes: ["sessions:own", "agents:read"],
});

const session = await asUser.createSession({
  agent: agentId,
  ownerUserId: authenticatedUser.id,
});

The server makes the person's Agent from the saved support manifest; owner is its owner guard, so only that person's sessions run on it, with its sandbox and secrets. See Agents. as() sends Nylorun-Subject and Nylorun-Scopes. Default scope is sessions:own.

ScopeAllows
sessions:ownThe person's own sessions, and reading Agents.
agents:readReading Agents, agent manifests, triggers, runs, and memories.
agents:writeMaking, moving, forking, and deleting Agents, and writing their secrets, memories, and triggers.
agent-manifests:writeSaving and deleting agent manifests. A trusted issuer's token never carries it.

Another person's session answers 404. A route outside the scopes answers 403 (scope_required). Only an application key can act for a person.

AG-UI

import { createAgUiHandler } from "@nylorun/agents/ag-ui";

const agui = createAgUiHandler({
  agents: ["support"],
  subject: (request) => userFrom(request),
  basePath: "/api/agui",
  scopes: ["sessions:own"],
});

app.all("/api/agui/*", (request) => agui.fetch(request));

agents lists the ids of the Agents the endpoint runs. Every caller's thread runs on that Agent, with its sandbox and secrets: make one Agent per audience, or an Agent of kind none for an endpoint everyone uses.

To store info with a thread's session, add session: it is called when the thread's session is created, and later runs keep what it returned.

const agui = createAgUiHandler({
  agents: ["support"],
  subject: (request) => userFrom(request),
  session: (subject) => ({ info: { plan: planOf(subject) } }),
});

toNodeListener from @nylorun/agents/ag-ui wraps fetch for node:http. Assistant text arrives whole.

A2A

import { createA2aHandler } from "@nylorun/agents/a2a";

const a2a = createA2aHandler({
  agents: ["support"],
  subject: (request) => userFrom(request),
});

agents lists Agent ids, as for AG-UI.

A2A 1.0 JSON-RPC: SendMessage, GetTask, ListTasks, CancelTask, and push notification configs. There is no streaming: updates reach callers by push. Each Agent's card is public, at {basePath}/{agent}/.well-known/agent-card.json; set publicUrl behind a proxy. The rules and extensions every Agent follows over A2A, and the client for calling one, are in A2A.

Rules

  • Browsers go through your server. The Runtime refuses Tenant keys on requests that carry Origin.
  • Strip every Nylorun-* header your clients send.
  • Terminate TLS on your server.
  • Keep the application key on the server.

Request shapes are on the Runtime API. Call a session from Sessions.

Next step

On this page