# Capabilities (/docs/build/capabilities) Add a named capability and attach it with `.use()`. The following snippet assumes an application-owned `orders` service; construct that client in the host. ```ts import { Agent, capability, tool } from "@nylorun/agents"; import { z } from "zod"; type SupportInfo = { accountId?: string }; type OrderService = { find( orderNumber: string, options: { signal: AbortSignal; accountId?: string }, ): Promise<{ orderNumber: string; status: string }>; }; export function supportCapability(orders: OrderService) { const findOrder = tool({ name: "find_order", description: "Find an order by its public order number.", input: z.object({ orderNumber: z.string() }), output: z.object({ orderNumber: z.string(), status: z.string() }), effects: "read", async run({ orderNumber }, context) { return orders.find(orderNumber, { signal: context.signal, accountId: context.info?.accountId, }); }, }); return capability({ id: "support", instructions: "Ask for an order number before using find_order.", tools: [findOrder], }); } export const assistant = Agent({ id: "assistant", name: "Assistant" }) .use(supportCapability(orders)) .build(); ``` Construct `orders` and other service clients in the application, then close over them in the capability. Per-session host data is `info` on the Runtime session (tools read `context.info`). Top-level `tools` and `instructions` on `Agent({ ... })` are first-class and compile as capability id `"agent"`. `tools` on either surface can include another `Agent` — see [Subagents](/docs/build/subagents). ## Understand hooks [#understand-hooks] Durable definitions use scoped hooks. They can add instructions, tools, or state, or deny / approve / retry / block a candidate. They cannot set `model` — Runtime owns model resolution. | Contribution | Declarative field | Dynamic API | | ---------------------- | --------------------------- | ---------------------------------- | | Instructions | `instructions` | `before("turn"\|"step")` → `Patch` | | Tools | `tools` | `before("turn"\|"step")` → `Patch` | | Session memory | tools write `context.state` | `before` reads `state` | | After a model call | — | `after("step")` → `Decision` | | After the final answer | — | `after("turn")` → `TurnDecision` | `capability({ model })` is deprecated. Durable manifests reject arbitrary middleware closures. Use [hooks](/docs/build/hooks). Helpers such as `mcp()`, `sandbox()`, `skills()`, and `plugin()` each return one capability. See those pages for the options they accept. ## Manage ordering and ownership [#manage-ordering-and-ownership] The application owns resources. Create clients in the host, close over them from tools, and shut them down in the application. There is no capability `state` factory. Capabilities are applied in `.use()` order. Use stable, unique ids and separate declarations for independent concerns. The published catalog row is `capabilities[]` with `id`, `type` (`agent` or `agent-plugin`), optional instructions, tools, skills, MCP servers, sandbox, and `hooks: { at, scope }[]`. ## Next step [#next-step] # Chain (/docs/build/chain) `Chain` runs a non-empty list of agents, tools, or nested workflows in order. Each step receives the preceding step's output unless a slot supplies an `input` function. ```ts import { Chain } from "@nylorun/agents/define"; export const report = Chain({ id: "report", steps: [ researcher, { run: analyst, input: ({ results }) => `Summarize: ${results.researcher.findings}`, }, { run: publish, input: ({ value }) => ({ summary: value.summary }), }, ], }); ``` ## Values and results [#values-and-results] * `value` is the immediately preceding step's output. * `results` contains earlier outputs keyed by step id. * `input` is the original workflow input. A direct step keeps its runnable id. Set `id` on a slot when the same runnable appears more than once or when you want a stable result key: ```ts { id: "final-review", run: reviewer, input: ({ value, input, results }) => ({ value, input, results }), } ``` The chain output is the final step's output. Step ids must be unique among siblings. Runtime checkpoints every node boundary, so a resumed chain does not repeat completed effects. See the shipped [`chain` example](https://github.com/nylorun/agents/tree/main/examples/agents/chain), then learn how to [route with Switch](/docs/build/switch). # Examples (/docs/build/examples) The generated registry contains one **Order assistant** with a `lookup_order` tool: ```sh npm create @nylorun/agent my-agent cd my-agent npx nylorun up npx @nylorun/cli tenant create npm run dev ``` The [Agents repository examples](https://github.com/nylorun/agents/tree/main/examples/agents) show instructions, tools, hooks, MCP, sandbox, skills, plugins, subagents, and media-oriented agents. Copy definitions and capabilities into your own `agents/` tree; do not copy credentials or generated data. ## Workflow examples [#workflow-examples] Six runnable examples demonstrate the workflow primitives: | Example | Pattern | | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | | [`chain`](https://github.com/nylorun/agents/tree/main/examples/agents/chain) | Run nodes in order and pass output through slots. | | [`switch`](https://github.com/nylorun/agents/tree/main/examples/agents/switch) | Choose one branch from input. | | [`parallel`](https://github.com/nylorun/agents/tree/main/examples/agents/parallel) | Run independent branches concurrently. | | [`map`](https://github.com/nylorun/agents/tree/main/examples/agents/map) | Apply a node to every input item. | | [`loop`](https://github.com/nylorun/agents/tree/main/examples/agents/loop) | Repeat a body until its condition is satisfied. | | [`ship-feature`](https://github.com/nylorun/agents/tree/main/examples/agents/ship-feature) | Combine agents and control-flow nodes in a larger workflow. | Start a new Studio session after changing a definition. Existing sessions stay pinned to the manifest with which they started unless an input supplies a turn manifest. ## Next step [#next-step] Learn to [add a typed tool](/docs/build/tools), [compose workflows](/docs/build/workflows), or inspect execution in [Studio](/docs/studio). # Hooks (/docs/build/hooks) Hooks intercept a turn or a model step. Register them on the builder or inside a capability. There are no compatibility aliases for the old names. ```ts import { Agent } from "@nylorun/agents"; export const support = Agent({ id: "support", instructions: "Help with orders.", }) .before("turn", ({ info }) => ({ instructions: [`Tenant ${info?.tenantId ?? "unknown"}`], })) .after("step", ({ text, toolCalls, attempt }) => { if (toolCalls.length === 0 && !text) { return attempt < 2 ? { retry: "Answer or call a tool." } : { block: "Empty step." }; } return {}; }) .after("turn", ({ text, attempt }) => { if (!text?.trim()) { return attempt < 2 ? { retry: "Give a short final answer." } : {}; } return {}; }) .build(); ``` | Registration | When it runs | Return | | --------------------- | ------------------------------------------------------------------- | -------------- | | `.before("turn", fn)` | Once per turn; the `Patch` applies to every model call in that turn | `Patch` | | `.before("step", fn)` | Every model call | `Patch` | | `.after("step", fn)` | After every model call, before tools or text take effect | `Decision` | | `.after("turn", fn)` | After the final answer | `TurnDecision` | `before("turn")` is issued only in a turn's first segment. In a Runtime, every capability registered at one hook point runs in a **single** executor action, so a hook point costs one round trip per turn or per model call. Hooks may run more than once when a delivery is retried: an expired hook claim is offered again instead of becoming uncertain. Keep side effects in tools. ## Patch, Decision, and TurnDecision [#patch-decision-and-turndecision] A `Patch` can add `instructions`, toggle `capabilities` or `tools`, merge `state`, or `block` the model call. It cannot set `model`. A `Decision` can replace `text`, `deny` or `approve` proposed tool calls, `retry` with feedback, or `block`. A `TurnDecision` can replace final `text` (plain-text agents) or `output` (agents with an `outputSchema`), `retry`, or `block`. `retry` now retries. From `after("step")` it denies the proposed tool calls with the feedback, or sends a text answer back with the feedback as a message; from `after("turn")` it sends the final answer back. The engine does not cap retries: bound them with `attempt`, for example `attempt < 2 ? { retry: "…" } : { block: "…" }`. Capability form: ```ts capability({ id: "policy", before: { turn: ({ info }) => ({ instructions: [`Tenant ${info?.tenantId}`] }) }, after: { step: ({ text }) => ({}), turn: ({ text }) => ({}) }, }) ``` The published manifest lists each hook as `{ at, scope }` on `capabilities[].hooks`. Action kind is `hook` with `{ at, scope, capabilityIds }`. Rebuild agents after upgrading; Runtime cancels leftover old hook actions and fails in-flight schema 3 turns. Start new sessions. See [Capabilities](/docs/build/capabilities) and the [0.15 → 0.17 migration](/docs/compatibility#breaking-changes). ## Next step [#next-step] # Agent (/docs/build) An agent is a definition: an id, instructions, and the tools the model may call. You export it from `agents/index.ts`; the Runtime picks the model. ```ts title="agents/assistant/agent.ts" import { Agent, tool } from "@nylorun/agents"; import { z } from "zod"; const lookupOrder = tool({ name: "lookup_order", description: "Look up a sample order by ID. Try demo-123.", input: z.object({ orderId: z.string() }), output: z.object({ orderId: z.string(), status: z.string() }), async run({ orderId }) { return { orderId, status: orderId === "demo-123" ? "shipped" : "not found" }; }, }); export const assistant = Agent({ id: "assistant", name: "Order assistant", instructions: "Help with orders. Always use lookup_order for order questions.", tools: [lookupOrder], }).build(); ``` * `id` is the stable identifier sessions use. `name` is the label Studio shows. * `instructions` tell the model what to do. See [Instructions](/docs/build/instructions). * `tools` are typed functions that run in your process. See [Tools](/docs/build/tools). Do not put `model` on `Agent({})`. The Tenant's model settings choose it; see [Models](/docs/run/models). ## Add capabilities [#add-capabilities] Each row is the basic usage only. Open a page for the details. Add only what this agent uses. | Capability | Basic usage | Page | | ------------- | ------------------------------------------ | ---------------------------------------- | | Instructions | `instructions: "…"` | [Instructions](/docs/build/instructions) | | Tools | `tools: [lookupOrder]` | [Tools](/docs/build/tools) | | Hooks | `.before("turn", …)` / `.after("step", …)` | [Hooks](/docs/build/hooks) | | Capabilities | `.use(capability({ id, … }))` | [Capabilities](/docs/build/capabilities) | | MCP | `.use(mcp({ … }))` | [MCP](/docs/build/mcp) | | Sandbox | `.use(sandbox())` | [Sandbox](/docs/build/sandbox) | | Skills | `.use(skills("./assistant-skills"))` | [Skills](/docs/build/skills) | | Agent Plugins | `.use(plugin("./plugins/github"))` | [Plugins](/docs/build/plugins) | ## Compose agents [#compose-agents] | Pattern | Basic usage | Page | | --------- | --------------------------------------------- | ---------------------------------- | | Subagents | `tools: [lookupOrder, researcher]` | [Subagents](/docs/build/subagents) | | Loop | `Loop({ id, run, verify, decide })` | [Loop](/docs/build/loop) | | Chain | `Chain({ id, steps: [researcher, analyst] })` | [Chain](/docs/build/chain) | | Switch | `Switch({ id, on, cases, default })` | [Switch](/docs/build/switch) | | Map | `Map({ id, over, each })` | [Map](/docs/build/map) | | Parallel | `Parallel({ id, branches: { a, b } })` | [Parallel](/docs/build/parallel) | | Workflows | Export any of the above like an agent | [Workflows](/docs/build/workflows) | ## Hooks [#hooks] Patch a turn or decide after a model call: ```ts export const assistant = Agent({ id: "assistant", name: "Order assistant", instructions: "Help with orders.", tools: [lookupOrder], }) .before("turn", ({ info }) => ({ instructions: [`Tenant ${info?.tenantId ?? "unknown"}`], })) .build(); ``` `before("turn"|"step")`, `after("step"|"turn")`, `Patch` / `Decision` / `TurnDecision`, and retry bounds are on [Hooks](/docs/build/hooks). ## Capabilities [#capabilities] Bundle instructions, tools, and hooks, then attach them with `.use()`: ```ts import { Agent, capability } from "@nylorun/agents"; export const assistant = Agent({ id: "assistant", name: "Order assistant", }).use( capability({ id: "support", instructions: "Ask for an order number before using find_order.", tools: [findOrder], }), ); ``` `.use()` returns a **new** snapshot. Ordering, ownership, catalog rows, and helpers that return one capability are on [Capabilities](/docs/build/capabilities). ## MCP [#mcp] Declare MCP servers the Runtime discovers: ```ts import { Agent, mcp } from "@nylorun/agents"; export const assistant = Agent({ id: "assistant", name: "Order assistant", instructions: "Use the available tools.", }).use( mcp({ github: { name: "github", type: "streamable-http", url: "https://mcp.example.com/github", }, }), ); ``` Transports, capability ids, snapshots, and `McpError` are on [MCP](/docs/build/mcp). ## Sandbox [#sandbox] Give the agent Runtime-executed computer tools: ```ts import { Agent, sandbox } from "@nylorun/agents"; export const assistant = Agent({ id: "assistant", instructions: "Analyse the data the user gives you. Use Python.", }).use(sandbox()); ``` Images, network presets, backends, idle, and `sandbox.*` events are on [Sandbox](/docs/build/sandbox). ## Skills [#skills] Load an Agent Skills catalog folder: ```ts import { Agent, skills } from "@nylorun/agents"; export const assistant = Agent({ id: "assistant", name: "Order assistant", tools: [lookupOrder], }).use(skills("./assistant-skills")); ``` Folder layout, the agentskills.io spec, `load_skill` / `read_skill_resource`, and build-copy are on [Skills](/docs/build/skills). ## Agent Plugins [#agent-plugins] Attach an Agent Plugin package as one capability: ```ts import { Agent, plugin } from "@nylorun/agents"; export const assistant = Agent({ id: "assistant", name: "Order assistant", instructions: "Use the plugin tools and skills.", }).use(plugin("./plugins/github")); ``` `loadPlugin`, diagnostics, `pluginRoot`, and plugin MCP/skills are on [Plugins](/docs/build/plugins). ## Subagents [#subagents] Put an agent in `tools` so the model can delegate a self-contained task: ```ts const researcher = Agent({ id: "researcher", description: "Investigates an order's history. Returns a short summary with the ids it relied on.", instructions: "Investigate one question about one order.", tools: [searchOrders, readTicket], }); export const assistant = Agent({ id: "assistant", instructions: "For anything needing more than two lookups, delegate to researcher with a complete, self-contained task.", tools: [lookupOrder, researcher], }); ``` `{ task: string }`, required `description`, `ctx.agent`, `history({ agent })`, `delegation.*` events, and one-level / non-interactive limits are on [Subagents](/docs/build/subagents). ## Loop [#loop] Run, verify, and retry until the output passes: ```ts import { Loop } from "@nylorun/agents/define"; export const polish = Loop({ id: "polish", run: coder, verify: ({ output }) => output.answer?.trim() ? { pass: true } : { pass: false, feedback: "Answer is empty." }, decide: ({ output, verdict, iteration }) => { if (verdict.pass) return { output }; if (iteration >= 3) throw new Error("Still empty after 3 tries"); return { input: verdict.feedback }; }, }); ``` Iteration limits and verifier agents are on [Loop](/docs/build/loop). ## Chain [#chain] Run steps in order; each step receives the previous output: ```ts import { Chain } from "@nylorun/agents/define"; export const report = Chain({ id: "report", steps: [researcher, analyst] }); ``` Slots, `value`, and `results` are on [Chain](/docs/build/chain). ## Switch [#switch] Run exactly one branch chosen from the input: ```ts import { Switch } from "@nylorun/agents/define"; export const route = Switch({ id: "route", on: (ticket) => ticket.kind, cases: { bug: bugAgent, billing: billingAgent }, default: generalAgent, }); ``` Deterministic keys and slots are on [Switch](/docs/build/switch). ## Map [#map] Run one node for every item in a list, concurrently: ```ts import { Map } from "@nylorun/agents/define"; export const write = Map({ id: "write", over: (plan) => plan.sections, each: sectionWriter }); ``` Ordering and `index` are on [Map](/docs/build/map). ## Parallel [#parallel] Run a fixed set of named branches on the same input: ```ts import { Parallel } from "@nylorun/agents/define"; export const checks = Parallel({ id: "checks", branches: { security: securityReviewer, style: styleReviewer }, }); ``` Result keys are on [Parallel](/docs/build/parallel). ## Workflows [#workflows] `Loop`, `Chain`, `Switch`, `Map`, and `Parallel` nest into one workflow. A workflow is exported, saved, and run exactly like an agent: same registry, same session client, same executor. See [Workflows](/docs/build/workflows). ## Details [#details] `.build()` returns the assembled facade. You can export the builder; generated projects call `.build()` so the registry holds a `BuiltAgent`. Invalid tool schemas, duplicate tool names, or other incompatible contributions raise `AgentBuildError`. * `description` is optional catalog metadata. It is required when this agent is used as a tool; see [Subagents](/docs/build/subagents). * `outputSchema` is optional and validates completed engine output. * `tools` and `instructions` on `Agent({ ... })` compile as capability id `"agent"`. * `JSON.stringify(agent)` is the public manifest (`manifestSchemaVersion: 4`). Bindings stay local; `getBinding()` is not a wire format. `Agent.from(manifest, implementations)` reconstructs a definition and rejects schema 3. Construct service clients in the application and close over them from tools. Do not put API keys, database handles, HTTP routing, or deployment policy in an agent manifest. Full signatures are in [Reference → define](/docs/reference/agents/define). ## Next step [#next-step] # Instructions (/docs/build/instructions) Instructions are what the model reads before it answers. A generated agent sets them on `Agent({ ... })`: ```ts export const assistant = Agent({ id: "assistant", name: "Order assistant", instructions: "Help with orders. Always use lookup_order for order questions.", }).build(); ``` `instructions` accepts one string or an ordered list. A string is normalized to a one-element array at build. Top-level instructions compile as capability id `"agent"`. Named capabilities can add their own: ```ts capability({ id: "support", instructions: "Ask for an order number before using find_order.", tools: [findOrder], }) ``` ## Dynamic instructions [#dynamic-instructions] A `before("turn")` or `before("step")` hook can return a `Patch` with extra `instructions`. Turn-scoped patches apply to every model call in that turn; step-scoped patches apply to that model call only. ```ts export const support = Agent({ id: "support", instructions: "Help with orders.", }) .before("turn", ({ info }) => ({ instructions: [`Tenant ${info?.tenantId ?? "unknown"}`], })) .build(); ``` `info` is host identity from the Runtime session. It is not model-visible unless a hook copies it into instructions. See [Hooks](/docs/build/hooks). Do not put secrets in instructions, manifests, or hook patches that become history. ## Next step [#next-step] # Loop (/docs/build/loop) `Loop` repeats three durable stages: `run`, `verify`, and `decide`. The decision either returns final `output` or supplies the next `input`. ```ts import { Loop } from "@nylorun/agents/define"; export const polish = Loop({ id: "polish", run: coder, verify: ({ output }) => { const text = output.answer ?? ""; if (text.trim().length >= 8) return { pass: true }; return { pass: false, feedback: "Answer must be at least eight characters. Try again.", }; }, decide: ({ output, verdict, iteration }) => { if (verdict.pass) return { output }; if (iteration >= 3) throw new Error("Still too short after 3 tries"); return { input: verdict.feedback }; }, }); ``` `run` may be an agent, tool, workflow, or slot. `verify` may be a function, tool, or verifier agent. A verifier agent must declare an output schema that accepts both verdict shapes: ```ts { pass: true } { pass: false, feedback: "What to improve" } ``` `decide` receives the current `output`, `verdict`, `iteration`, original `input`, and prior `history`. Always define a terminal condition: return an output, cap attempts, or throw a useful error. Runtime checkpoints each iteration and Studio shows its node status and history. See the shipped [`loop` example](https://github.com/nylorun/agents/tree/main/examples/agents/loop) or return to the [Workflows overview](/docs/build/workflows) to register and run the composed workflow. # Map (/docs/build/map) `Map` derives a list with `over`, runs `each` once per item concurrently, and returns the outputs in the original item order. An empty list returns `[]`. ```ts import { Chain, Map } from "@nylorun/agents/define"; export const digest = Chain({ id: "digest", steps: [ planner, Map({ id: "write", over: (plan) => plan.sections, each: sectionWriter, }), { run: merge, input: ({ value }) => ({ parts: value }), }, ], }); ``` `over` is durable workflow logic. Keep it deterministic and return a JSON-safe array. `each` can be an agent, tool, nested workflow, or slot. A slot can use `index` while shaping each item's input: ```ts Map({ id: "write", over: (plan) => plan.sections, each: { run: sectionWriter, input: ({ value, index }) => ({ title: value, position: index }), }, }) ``` Use `Map` for data-driven fan-out. Use [Parallel](/docs/build/parallel) when branches have different names or behavior known at definition time. See the shipped [`map` example](https://github.com/nylorun/agents/tree/main/examples/agents/map), then use [Loop](/docs/build/loop) for repeat-until-accepted work. # MCP (/docs/build/mcp) Declare MCP servers with `mcp(...)`. The map shape matches Agent Plugins `mcpServers`: each key must equal that server's `name`. ```ts import { Agent, mcp } from "@nylorun/agents"; export const assistant = Agent({ id: "assistant", name: "Assistant", instructions: "Use the available tools.", }).use( mcp({ github: { name: "github", type: "streamable-http", url: "https://mcp.example.com/github", }, }), ); ``` Transports follow [Agent Plugins MCP servers](https://agent-plugins.org/plugin-authors/mcp-servers): `stdio`, `streamable-http`, and `sse`. Pass `{ id: "…" }` as the second argument to override the default capability id `"mcp"`. ```ts mcp( { local: { name: "local", type: "stdio", command: "npx", args: ["-y", "@example/mcp-server"], }, }, { id: "docs-mcp" }, ) ``` Runtime discovers tools on the session's first turn and pins them in `mcpSnapshot`. The snapshot contains no secrets. A later session PUT may replace `vaultIds` and `credentialSelections`; `agentId`, `ownerUserId`, and `info` stay the creation identity. URL-bound credentials for outbound MCP calls belong in an end-user [vault](/docs/run/vault) with the same `ownerUserId` as the session. The host vault is not attachable to a session. A mismatched key and `name` throws `McpError` (`mcp.name-mismatch`). An empty map throws `mcp.empty`. ## Next step [#next-step] # Parallel (/docs/build/parallel) `Parallel` sends the same input to a fixed object of named branches and runs them concurrently. It returns an object keyed by those branch names. ```ts import { Chain, Parallel } from "@nylorun/agents/define"; export const review = Chain({ id: "review", steps: [ Parallel({ id: "checks", branches: { security: securityReviewer, style: styleReviewer, tests: testAuditor, }, }), { run: summarizer, input: ({ value }) => `Summarize these reviews:\n${JSON.stringify(value, null, 2)}`, }, ], }); ``` Use `Parallel` when the number and names of branches are known while defining the workflow. Branch names become stable result keys and manifest paths. Each branch can be an agent, tool, nested workflow, or slot. The example above produces a value shaped like: ```ts { security: securityResult, style: styleResult, tests: testResult, } ``` All branches share the workflow session sandbox. Cancelling the parent cancels active branches; completed node effects remain checkpointed. See the shipped [`parallel` example](https://github.com/nylorun/agents/tree/main/examples/agents/parallel). Use [Map](/docs/build/map) instead when the branch count comes from input data. # Plugins (/docs/build/plugins) Read an [Agent Plugin](https://agent-plugins.org/) package and attach it with `.use(plugin(directory))`: ```ts import { Agent, plugin } from "@nylorun/agents"; export const assistant = Agent({ id: "assistant", name: "Assistant", instructions: "Use the plugin tools and skills.", }).use(plugin("./plugins/github")); ``` `plugin(directory)` calls `loadPlugin` and returns one capability: * `type: "agent-plugin"` * `id` is the plugin name * optional `pluginRoot` (stored beside the definition; not part of the manifest hash) * optional skills (`load_skill` / `read_skill_resource`) * optional `mcpServers` `loadPlugin` is the lower-level reader if you want the loaded package and diagnostics before attaching it. Capability diagnostics stay on the returned object; they are not serialized into the public manifest. MCP servers inside a plugin use the same map shape as [`mcp()`](/docs/build/mcp). Runtime discovers those tools on the first turn and pins them on the session. ## Next step [#next-step] # Sandbox (/docs/build/sandbox) Give an agent an isolated computer with `sandbox()`: ```ts import { Agent, sandbox } from "@nylorun/agents"; export const analyst = Agent({ id: "analyst", instructions: "Analyse the data the user gives you. Use Python.", }).use(sandbox()); ``` The model gets `bash`, `read`, `write`, `edit`, `grep`, and `glob` on a Linux machine with a persistent `/workspace`. These tools run in the Runtime, not in your process, so sandbox-only agents need no connected executor. The agent declares what it needs; the Runtime decides where it runs. Every option is optional plain data: ```ts .use(sandbox({ image: "python:3.13", network: { preset: "dev", allow: ["api.example.com"] }, resources: { cpus: 2, memory: "2GiB" }, idle: "15m", })) ``` | Option | Default | Meaning | | --------------------------- | ------------------------------------ | -------------------------------------------------- | | `image` | Runtime default (`python:3.13-slim`) | Any OCI image. | | `network.preset` | `"dev"` | `"none"`, `"dev"`, or `"open"`. | | `network.allow` | — | Extra hosts, for example `api.example.com`. | | `resources.cpus` / `memory` | Runtime default | Compute budget. Memory is a size such as `"2GiB"`. | | `idle` | Runtime default | Stop compute when idle; files persist. | The `dev` preset allows package registries and code hosts. Private networks, loopback, the host, and cloud metadata endpoints are always blocked. Options from the full design that are not in this version (`setup`, `files`, `secrets`, `mount`, `onStart`, `scope`, …) throw a `SandboxError` that says so. Runtime owns one virtual sandbox per session, created on the first sandbox tool call and reattached with its files after idle stops or restarts. The backend is an emulated shell in the Runtime process, not a VM security boundary. Set `NYLORUN_SANDBOX=auto` or `virtual`; both select the virtual backend. `GET /v1/tenant/sandbox` and `nylo doctor sandbox` report it. Tool calls emit `sandbox.state` and `sandbox.exec` session events. A sandbox call interrupted by a crash becomes uncertain and is never re-run. Virtual workspaces live in the Tenant's `sandboxes/` directory. Pass `{ id: "…" }` as the second argument to override the default capability id `"sandbox"`. An agent may declare only one sandbox capability. ## Next step [#next-step] # Skills (/docs/build/skills) Load Agent Skills from a local catalog folder with `skills(path)`: ```ts import { Agent, skills } from "@nylorun/agents"; export const assistant = Agent({ id: "assistant", name: "Order assistant", instructions: "Use lookup_order for orders.", tools: [lookupOrder], }).use(skills("./assistant-skills")); ``` Each subdirectory under the catalog must contain a `SKILL.md` with YAML frontmatter (`name`, `description`) per [Agent Skills](https://agentskills.io/home). Supporting files (for example `references/`) are available through `read_skill_resource` after `load_skill`. ```text assistant-skills/ lookup-order/SKILL.md refund/ SKILL.md references/policy.md ``` The helper sets both the manifest skill catalog and the on-disk skill records so you do not duplicate content. The engine injects: | Tool | Input | Role | | --------------------- | ---------------- | ----------------------------------------------- | | `load_skill` | `{ name }` | Skill instructions and the resource list | | `read_skill_resource` | `{ name, path }` | A supporting file, when the skill has resources | Capability id defaults to the catalog directory basename. Override it with `skills("./assistant-skills", { id: "order-skills" })`. `plugin()` can also contribute skills from an Agent Plugin package. See [Plugins](/docs/build/plugins). ## Next step [#next-step] # Subagents (/docs/build/subagents) Put an agent in another agent's `tools` to let the model delegate to it. ```ts import { Agent } from "@nylorun/agents"; import { z } from "zod"; const researcher = Agent({ id: "researcher", description: "Investigates an order's history. Returns a short summary with the ids it relied on.", instructions: "Investigate one question about one order. Be exhaustive, then be brief.", tools: [searchOrders, readTicket], outputSchema: z.object({ summary: z.string(), evidence: z.array(z.string()), }), }); const support = Agent({ id: "support", instructions: "For anything needing more than two lookups, delegate to researcher with a complete, self-contained task.", tools: [lookupOrder, refundOrder, researcher], }); ``` The tool is named after the child's `id` and takes `{ task: string }`. The child's `description` (required) is what the parent's model reads. The child starts with a fresh context: it sees its own instructions and the task, nothing of the parent's conversation, and only its final text (or `outputSchema` result) comes back. `connectAgents({ agents: [support] })` serves both. Children share the session's sandbox, keep their own tools, hooks, skills, and MCP servers, and start with empty `ctx.state`. Tools can read `ctx.agent` (`{ id, path, delegationId }`). Several delegation calls in one model response run in parallel. An empty answer, a failure (with the child's last text marked as evidence), or a cancelled child reaches the parent's model as a **failed** tool result, never as success. Runtime emits `delegation.started` and `delegation.completed`. `session.history({ agent })` filters by `delegationId` (one child invocation) or by path such as `support/researcher` (every concurrent child that shares that path). This version is one level deep and non-interactive: a delegated agent cannot use agents as tools, its tools cannot declare `approval` (keep those on the parent), and `ctx.ask`, `ctx.approve`, `ctx.sleep`, or `ctx.waitFor` inside it fail with `delegation.interaction-unsupported`. Delegation is not an approval boundary; approvals live on tools. Delegate when the parent should keep the answer. When a specialist should own the rest of the conversation, switch capabilities with a `before("step")` patch instead. See [Compatibility](/docs/compatibility) for the tested package set. ## Next step [#next-step] # Switch (/docs/build/switch) `Switch` computes a key from its input and runs exactly one matching case. Add `default` when inputs may produce keys outside the declared cases. ```ts import { Chain, Switch } from "@nylorun/agents/define"; export const support = Chain({ id: "support", steps: [ triager, Switch({ id: "route", on: (ticket) => ticket.kind, cases: { bug: bugAgent, billing: billingAgent, }, default: generalAgent, }), ], }); ``` `on` is durable workflow logic: keep it deterministic and derive the key only from its input. Case names become manifest paths, so use stable names and do not use the reserved key `default`. Each case may be an agent, tool, workflow, or slot. A slot can reshape the selected branch's input: ```ts cases: { bug: { run: bugAgent, input: ({ value }) => `Investigate: ${value.summary}`, }, } ``` The switch output is the selected branch's output. Studio shows the chosen case and leaves unselected branches inactive. See the shipped [`switch` example](https://github.com/nylorun/agents/tree/main/examples/agents/switch), then learn how to [run fixed branches in Parallel](/docs/build/parallel). # Tools (/docs/build/tools) A tool exposes a host-owned function to the model. Prefer `input` / `output` / `run`. A plain `return` is a completed result. Legacy `inputSchema` / `execute` and tagged `{ kind: "completed" }` outcomes still work. ```ts import { Agent, tool } from "@nylorun/agents"; import { z } from "zod"; const lookupOrder = tool({ name: "lookup_order", description: "Look up a sample order by ID. Try demo-123.", input: z.object({ orderId: z.string() }), output: z.object({ orderId: z.string(), status: z.string() }), async run({ orderId }) { return { orderId, status: orderId === "demo-123" ? "shipped" : "not found" }; }, }); export const assistant = Agent({ id: "assistant", name: "Order assistant", tools: [lookupOrder], }).build(); ``` `input` validates model-generated arguments before execution. Add `output` when downstream code relies on a specific completed result. Runtime checks a successful tool result against that output schema and stores a mismatch as a failed outcome. A valid schema is not authorization: check the current user in the host service. ## Execution context [#execution-context] Forward `context.signal` to network clients so cancellation stops in-flight work. Context also includes `idempotencyKey`, optional `redelivery`, `state`, `session.id`, and optional `agent` (`{ id, path, delegationId? }` — the root agent, or the child when this call belongs to a [delegation](/docs/build/subagents)). Durable wait helpers (`ask`, `approve`, `sleep`, `waitFor`, `step`) exist on the context; automatic timer and event wakeups are not in this release. Code-only fields (never serialized into the manifest): * `effects`: `"read" | "idempotent" | "write"` * `approval`: return a prompt string (or `true`) to pause before `run` ## Connected execution versus the engine [#connected-execution-versus-the-engine] The default path is a **connected executor**: the CLI (or `connectAgents`) claims actions from Runtime and runs your implementations in the application process. | Behavior | Connected executor (`connectAgents`) | In-process engine (`harness/run`) | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | Invalid tool input | Failed result `tool.invalid-input`. The message is a JSON string of issues. There is no engine `details: { phase, issues }` shape. | Failed result `tool.invalid-arguments` with `details: { phase, issues }`. | | `context.progress` | No-op. Progress transport is not implemented on this path. | Emits a `tool.progress` observation when a listener is present. | Document the mode you are using. Do not treat engine-only validation detail or live progress as part of the starter workflow. ## Ownership [#ownership] Construct service clients in the application and close over them from tools. Per-session host data is `info` on the Runtime session (tools read `context.info`). Definitions do not create clients, supply credentials, or authorize external calls. Tools belong in a capability so their ownership is visible. Use separate capabilities when tools depend on different services, credentials, or policies. Sandbox tools (`bash`, `read`, `write`, `edit`, `grep`, `glob`) run in Runtime, not in your executor. See [Sandbox](/docs/build/sandbox). Put a built `Agent` in `tools` to let the model delegate a self-contained task. The child becomes a tool named after its `id` and takes `{ task: string }`. See [Subagents](/docs/build/subagents). ## Next step [#next-step] # Workflows (/docs/build/workflows) A workflow is a registered runnable with `kind: "workflow"`. It uses the same Tenant session API as an agent, but its manifest describes a graph of agent, tool, function, and verification nodes. ```ts title="agents/report/agent.ts" import { Agent, Chain, tool } from "@nylorun/agents/define"; import { z } from "zod"; const researcher = Agent({ id: "researcher", name: "Researcher", description: "Gathers concise findings.", instructions: "Research the topic and return { findings }.", outputSchema: z.object({ findings: z.string() }), }).build(); const publish = tool({ name: "publish", description: "Records finished findings.", input: z.object({ findings: z.string() }), output: z.object({ published: z.boolean() }), async run() { return { published: true }; }, }); export const report = Chain({ id: "report", steps: [ researcher, { run: publish, input: ({ value }) => value, }, ], }); ``` Export the workflow from the registry exactly as you export an agent: ```ts title="agents/index.ts" import { report } from "./report/agent.js"; export const agents = [report]; ``` ## Primitives [#primitives] | Primitive | Behavior | | ---------------------------------- | -------------------------------------------------------------------------------- | | [`Loop`](/docs/build/loop) | Runs a node, verifies its output, and either returns or supplies the next input. | | [`Chain`](/docs/build/chain) | Runs steps in order; each result becomes the next step's value. | | [`Switch`](/docs/build/switch) | Computes a key and runs the matching case or default branch. | | [`Map`](/docs/build/map) | Runs one node per item concurrently and returns ordered results. | | [`Parallel`](/docs/build/parallel) | Runs a fixed object of named branches concurrently. | Primitives nest, so a `Chain` can contain a `Map` whose `each` node is a `Loop`. Runtime persists each node boundary and resumes from completed effects instead of repeating them. ## Slots and data [#slots-and-data] A direct node receives the current value. Wrap it in a slot to give the node a stable `id` or reshape its input: ```ts { id: "summarize", run: summarizer, input: ({ value, results, input }) => ({ current: value, earlier: results.researcher, original: input, }), } ``` `value` is the preceding node output, `results` contains completed keyed nodes, and `input` is the workflow's original turn input. Functions used for slot inputs, switch keys, map expansion, and loop decisions run as durable `fn` or `verify` executor actions. ## Sessions and manifests [#sessions-and-manifests] Use `saveAgent`, `createSession`, `input`, `observe`, `pending`, `approve`, and `cancel` exactly as for agents. Text agents accept `content`; workflows can also accept structured `data`. Saving a workflow first saves the agents it references. Agent sessions can carry a turn-only `message.manifest`; see [Sessions](/docs/run/sessions#turn-manifests). Workflow sessions retain their workflow pin. Studio renders the workflow manifest tree, live node states, iterations, and links to child agent sessions. All nodes in one workflow share the session sandbox. Cancelling the parent cancels active child work. ## Examples [#examples] See the shipped [`chain`, `switch`, `parallel`, `map`, `loop`, and `ship-feature`](/docs/build/examples#workflow-examples) examples. ## Next step [#next-step] Start with [Chain](/docs/build/chain), or open [Sessions](/docs/run/sessions) to run a workflow and [Studio](/docs/studio) to inspect its manifest and node progress. # App server (/docs/deploy/app-server) Your **app server** is your own application. In production it does two jobs: 1. **Runs your tools.** `connectAgents` registers agents and executes their tools when the Runtime asks. 2. **Serves your users.** It signs people in and calls the Runtime for each person. The starter project does the first job. Add the second when people use your agents. ## Build and start [#build-and-start] ```sh npm run build npm start # node dist/src/main.js ``` Set three variables, or print them for the linked project with `eval "$(npx @nylorun/cli env)"`: | Variable | Value | | --------------------- | ---------------------------------------------------------------------------------------------- | | `NYLORUN_RUNTIME_URL` | Where your app reaches the Runtime. See [Docker](/docs/deploy/docker#connect-your-app-server). | | `NYLORUN_TENANT` | The Tenant id. | | `NYLORUN_SERVER_KEY` | The Tenant's application key. Server-side only. | The app does not start the stack, Studio, or a file watcher. Start the Runtime first (`npx nylorun up`), under the same supervisor if you use one. You can also create Tenants with [`@nylorun/admin`](/docs/reference/admin). ### How the connection is found [#how-the-connection-is-found] `createClient()` and `connectAgents()` use exactly one complete source, in this order: 1. Explicit `{ url, key, tenant }` options. 2. `NYLORUN_RUNTIME_URL`, `NYLORUN_SERVER_KEY` or `NYLORUN_EXECUTOR_KEY`, and `NYLORUN_TENANT`. 3. The nearest `.nylorun/link.json` plus `credentials.json`. Sources never mix. If any variable is set, all of them must be, or the call fails with `connection_missing`. ## Executors [#executors] The compiled app connects every exported agent and workflow: ```ts title="src/main.ts" import { connectAgents } from "@nylorun/agents"; import { agents } from "../agents/index.js"; const connection = connectAgents({ agents, implementationVersion: process.env.NYLORUN_IMPLEMENTATION_VERSION ?? "app-1", runtime: { url: process.env.NYLORUN_RUNTIME_URL!, tenant: process.env.NYLORUN_TENANT!, key: process.env.NYLORUN_SERVER_KEY!, }, onError: console.error, }); await connection.ready; ``` Restarts and replicas re-register idempotently. Credentials, retries, and uncertain work are on [Run → Executors](/docs/run/executors). ## Serve people [#serve-people] Your server signs people in and keeps the Tenant key. For each request it names the person with `client.as()`. The Runtime then limits the call to that person's sessions and vaults: ```ts import { createClient } from "@nylorun/agents"; const app = createClient(); // the Tenant key, on the server only // Per request, after your own sign-in: const person = app.as(`app:${user.id}`, { scopes: ["sessions:own", "vaults:own"] }); const session = await person.createSession({ agentId: "support", ownerUserId: `app:${user.id}` }); await person.listSessions(); // only this person's sessions ``` `as()` sends `Nylorun-Subject` and `Nylorun-Scopes` on every call, event streams included. Nothing is minted or cached, so calling it per request is cheap. Another person's session answers `404`, like a missing one; a route outside the scopes answers `403` (`scope_required`). | Scope | Allows | | ----------------- | ---------------------------------------------------------------------------------------- | | `sessions:own` | The person's own sessions: create, list, read, stream, message, approve, respond, cancel | | `vaults:own` | The person's own vaults and credentials | | `agents:read` | Listing the Tenant's agents | | `agents:write` | Saving agents; listing agents, models, and providers | | `tenant:settings` | The Tenant's status, model provider, and sandbox settings | The default is `["sessions:own"]`. Full options are in [Reference → client](/docs/reference/agents/client#as). ### Serve a chat UI with AG-UI [#serve-a-chat-ui-with-ag-ui] For a web or desktop chat UI, mount the AG-UI handler. It maps each AG-UI thread to one session per person, agent, and thread, and calls the Runtime as that person: ```ts import { createServer } from "node:http"; import { createAgUiHandler, toNodeListener } from "@nylorun/agents/ag-ui"; import support from "./agents/support.js"; const agui = createAgUiHandler({ basePath: "/api/agui", agents: [support], // nothing else is reachable subject: async (request) => (await getSignedInUser(request))?.id, // undefined → 401 }); createServer(toNodeListener(agui)).listen(3000); // Next.js, Hono, Bun, Deno, Workers: export or mount agui.fetch directly. ``` Point CopilotKit or `@ag-ui/client`'s `HttpAgent` at `/api/agui/support`. A complete web backend with a test is in the [AG-UI example](https://github.com/nylorun/agents/tree/main/examples/src/ag-ui). Routes, approvals, and limitations are in [Reference → ag-ui](/docs/reference/agents/ag-ui). ### Rules for an app server [#rules-for-an-app-server] * Browsers always go through your server. Never let one call the Runtime. * Drop every `Nylorun-*` header your own clients send. Never forward `Origin`; the Runtime refuses browser requests. * Terminate TLS for your clients. * Keep the admin key and application keys on the server. A server that holds the admin key can derive its Tenant key instead of storing one (`deriveTenantKey(adminKey, tenantId, principalId)` from `@nylorun/admin`, for a Tenant created with that derived principal). * Removing a person is your decision: stop acting for them and close their open streams. There is no per-person credential to revoke. * Keep the Runtime off the network. How your server reaches it is on [Docker](/docs/deploy/docker#connect-your-app-server). ## Next step [#next-step] # Nylorun Cloud (/docs/deploy/cloud) Nylorun Cloud is not available in this release. Early-access applications are reviewed manually, with no guaranteed approval timeline. Nylorun intends the hosted Runtime to share the same execution foundation and session protocol as the Runtime you run with Docker. That is a direction, not a current deployment or migration guarantee. ## What to use now [#what-to-use-now] Run the Runtime with [Docker](/docs/deploy/docker): `npx nylorun up`, create a Tenant with `npx @nylorun/cli tenant create`, and connect your app with `npm run dev` or `npm start`. Local Postgres schemas, S2 streams, project credentials, and Console organization keys do not become Cloud credentials. ## Connect [#connect] Not yet. There is no Cloud Runtime URL or key to connect an app server to. ## Next step [#next-step] # Docker (/docs/deploy/docker) `npx nylorun up` runs the Runtime as one Docker Compose project named `nylorun`. This is the supported deployment in this release. ```sh npx nylorun up # start, or leave running if already up npx nylorun status # service, port, and readiness state npx nylorun down # stop containers and keep data ``` ## Services [#services] | Service | Role | | ---------- | ---------------------------------------------------- | | `postgres` | Session Store; one `tenant_` schema per Tenant. | | `restate` | Durable session execution, wakes, and Tenant sweeps. | | `s2` | s2-lite streams for session history and SSE. | | `runtime` | Tenant and Admin HTTP APIs and workers. | | `studio` | Local dashboard and trusted proxy. | ## Images [#images] Runtime and Studio ship as multi-architecture images (`linux/amd64`, `linux/arm64`) tagged with their package versions: | Image | Notes | | ------------------------------------------- | ----------------------------- | | `ghcr.io/nylorun/runtime:` | `--role api`, `worker`, `all` | | `ghcr.io/nylorun/studio:` | Not published to npm | `nylorun up` runs the versions its release pins beside the official Postgres, Restate, and s2-lite images. Tags are never moved and there is no `latest` tag. Override the pins with `NYLORUN_RUNTIME_IMAGE` and `NYLORUN_STUDIO_IMAGE`, for example with a local build. The local stack runs the Runtime with the combined `all` role. ## Ports [#ports] | Service | Default | | ---------- | ---------------- | | Runtime | `127.0.0.1:8787` | | Studio | `127.0.0.1:4161` | | Restate UI | `127.0.0.1:9070` | The first start stores configured or free ports in `stack/.env`. Change them there with `NYLORUN_PORT`, `NYLORUN_STUDIO_PORT`, and `NYLORUN_RESTATE_PORT`. ## Container configuration [#container-configuration] * Database: `NYLORUN_DATABASE_URL` * Restate: `NYLORUN_RESTATE_*` * S2: `NYLORUN_S2_*` * Listener: `NYLORUN_LISTEN_HOST`, `NYLORUN_LISTEN_PORT`, `NYLORUN_ALLOWED_HOSTS`, and `NYLORUN_PUBLIC_URL` `GET /ready` checks Postgres, Restate, and S2 and returns `503` while a required dependency is unavailable. `GET /health` reports version and protocol compatibility. ## Storage [#storage] Two things hold all state, and they belong together: 1. **The Host root** (`NYLORUN_HOME` or `~/.nylorun`): identity, the admin key, stack configuration, and per-Tenant files. 2. **Docker volumes**: each Tenant's Postgres schema, S2 session streams, Restate state, and workspaces. ```text ~/.nylorun/ host.json host-credentials.json # admin key stack/ compose.yaml .env # mode 0600 restate-identity.pem tenants// vault-kek plugin-data/ logs/ home/ tmp/ sandboxes/ trash/ ``` * Keep the Host root private and persistent. Keep each project's `.nylorun/link.json` and `credentials.json` private too. * Back up and restore the Host root and the volumes **together**; credentials and database state are not independent. * `nylorun down` stops containers and keeps data. `nylorun reset` deletes all volumes and every Tenant. * Run one stack per machine. SQLite Tenants from earlier releases are not migrated. On first start they move to `trash/-sqlite-