Agent
Compose one agent, then add capabilities. Open each capability page for the rest.
Build is authoring. You compose an agent from capabilities and export it. Do
not put model on Agent({}).
This page starts with Agent({ ... }), then adds capabilities in the order
below. Each section is the basic usage only — open that capability’s page
for every nuance. You do not need every capability; add the ones this agent
uses.
| Capability | Basic usage | Page |
|---|---|---|
| Identity | Agent({ id, name }).build() | Agent |
| Instructions | instructions: "…" | Instructions |
| Tools | tools: [lookupOrder] | Tools |
| Hooks | .before("turn", …) / .after("step", …) | Hooks |
| Capabilities | .use(capability({ id, … })) | Capabilities |
| MCP | .use(mcp({ … })) | MCP |
| Sandbox | .use(sandbox()) | Sandbox |
| Skills | .use(skills("./assistant-skills")) | Skills |
| Agent Plugins | .use(plugin("./plugins/github")) | Plugins |
| Subagents | tools: [lookupOrder, researcher] | Subagents |
Identity
Start with a stable id and an optional name:
import { Agent } from "@nylorun/agents";
export const assistant = Agent({
id: "assistant",
name: "Order assistant",
}).build();idis the programmatic identifier used by manifests and sessions.nameis the optional human-readable label.descriptionis optional catalog metadata. Required when this agent is used as a tool — see Subagents.outputSchemais optional and validates completed engine output.toolsandinstructionsonAgent({ ... })compile as capability id"agent".
.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. 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.
Keep runtime concerns outside the agent
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.
Instructions
Tell the model what to do:
export const assistant = Agent({
id: "assistant",
name: "Order assistant",
instructions: "Help with orders. Always use lookup_order for order questions.",
}).build();Lists, capability-owned strings, and before patches are on
Instructions.
Tools
Give the model a typed host-owned function:
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();Schemas, effects, approval, context, and executor versus engine behavior
are on Tools.
Hooks
Patch a turn or decide after a model call:
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.
Capabilities
Bundle instructions, tools, and hooks, then attach them with .use():
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.
MCP
Declare MCP servers the Runtime discovers:
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.
Sandbox
Give the agent Runtime-executed computer tools:
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.
Skills
Load an Agent Skills catalog folder:
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.
Agent Plugins
Attach an Agent Plugin package as one capability:
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.
Subagents
Put an agent in tools so the model can delegate a self-contained task:
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.