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
| Part | In a folder | In the builder | Page |
|---|---|---|---|
| Instructions | The AGENT.md body, instructions/*.md | .instructions("…") | Instructions |
| Tools | tools/<name>.json | .tools(http({ name, input, url })) | Tools |
| MCP | mcp.json | .mcp({ github: { type, url } }) | MCP |
| Skills | skills/<name>/SKILL.md | .skills("./assistant-skills") | Skills |
| Agent Plugins | plugins/<name>/ | .plugin("./plugins/github") | Plugins |
| Requirements | runtime.json, the runtime section itself | .requires({ sandbox: "pod" }) | Saving manifests |
| Memory | memory in AGENT.md | save({ 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
| Pattern | In a folder | In the builder | Page |
|---|---|---|---|
| Subagents | agents/<id>/ | .subagents(researcher) | Subagents |
| Flow agents | flow.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.
| Scope | Allows |
|---|---|
sessions:own | The person's own sessions, and reading Agents. |
agents:read | Reading Agents, agent manifests, triggers, runs, and memories. |
agents:write | Making, moving, forking, and deleting Agents, and writing their secrets, memories, and triggers. |
agent-manifests:write | Saving 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.