Agent builder
Define an agent with instructions and a tool, then add only what it needs.
import { Agent, http } from "@nylorun/agents";
import { z } from "zod";
const lookupOrder = http({
name: "lookup_order",
description: "Look up an order by ID.",
input: z.object({ orderId: z.string() }),
output: z.object({ orderId: z.string(), status: z.string() }),
url: "https://orders.example.com/lookup",
});
export const assistant = Agent({ id: "assistant", name: "Order assistant" })
.instructions("Help with orders. Always use lookup_order for order questions.")
.tools(lookupOrder)
.build();Agent({ id, name?, description?, metadata? })takes identity only.idis the stable identifier sessions use;nameis the label Studio shows..instructions()tells the model what to do. See Instructions..tools()adds tools the model may call. Anhttp()tool is one request the Runtime makes to your service. See Tools.
The Runtime runs the agent from its manifest and never calls your code during a
session. client.agentManifests.save refuses a tool that would run your code
(tool({ run })) before it sends anything.
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, made from the runtime section the agent is saved with; see Save it.
The builder's rules
- One method per thing. Instructions, tools, subagents, MCP servers, skills and plugins each have their own method.
- List methods accumulate.
.instructions(),.tools(),.subagents(),.mcp(),.skills()and.plugin()add to what is there, and each takes several items at once:.tools(lookupOrder, refundOrder). - Single values are set once.
.output()and.requires()fail the build withagent.single-valuewhen called twice. - Every call returns a new builder. The original is unchanged, so a shared base agent can be extended in several ways.
The methods are listed on Build. Add only what this agent uses.
Reuse
To give several agents the same tools and instructions, write a function that adds them:
import { Agent, type AgentBuilder } from "@nylorun/agents";
const BILLING = "Ask for an order number before using refund_order.";
const billing = (agent: AgentBuilder) => agent.tools(refundOrder).instructions(BILLING);
export const support = billing(
Agent({ id: "support", name: "Support" }).instructions("Answer order questions."),
);The result is one agent: the function's tools and instructions sit beside the
agent's own. A bundle you publish for other projects is an
Agent Plugin, added with .plugin().
MCP, skills, plugins
export const assistant = Agent({ id: "assistant", name: "Order assistant" })
.instructions("Use the available tools.")
.mcp({
github: { type: "streamable-http", url: "https://mcp.example.com/github" },
})
.skills("./assistant-skills")
.plugin("./plugins/github");MCP servers are remote only: streamable-http or sse, declared by URL. See
MCP, Skills, and
Plugins.
.skills() and .plugin() read files, so they are on the Agent from
@nylorun/agents. @nylorun/agents/define exports the same builder without
them.
Subagents and flows
const researcher = Agent({
id: "researcher",
description: "Investigates an order's history.",
})
.instructions("Investigate one question about one order.")
.tools(searchOrders);
export const assistant = Agent({ id: "assistant" })
.instructions("Delegate research that needs more than two lookups.")
.tools(lookupOrder)
.subagents(researcher);Limits and delegation.* events are on Subagents.
Stages and flow() are on Flow agents.
Save it
An agent runs once it is saved as an agent manifest, with the runtime section it needs, and an Agent is made from that manifest:
await client.agentManifests.save({ agent: assistant, runtime: { kind: "virtual" } });
await client.agents.put("users/alice/assistant", { manifest: "assistant", owner: "alice" });Sessions then open on the Agent:
createSession({ agent: "users/alice/assistant", ownerUserId: "alice" }). Each
save makes a new version of the manifest and moves every Agent that tracks it.
See Saving manifests and
Agents.
Requires
.requires({ sandbox, secrets }) states what the agent needs of the runtime
section it is saved with: a sandbox ("any" or "pod"), and the secret slots
its skills' scripts read. The SDK and nylorun apply check it before a save
and send nothing when it does not fit (ManifestGapsError); see
Requires.
Check before you save
A plan makes every check of a save and saves nothing:
const plan = await client.agentManifests.plan({ agent: assistant, runtime: { kind: "virtual" } });It answers the version a save would move from and to (from, to,
unchanged), each change by section and path, errors (the gaps between the
sections included), warnings, how many Agents a save would move (moves),
and how many run older versions (behind). The skill files are still
uploaded, since the Runtime stores files by content. For an agent written as
an agent manifest (or in the deprecated
three-file format), the CLI does the
same:
npx nylorun apply agents/triage --dry-runConvert to a folder
npx nylorun export --folder assistantexport --folder writes a saved manifest out as files (its latest
version, or assistant@3) to ./assistant, says whether the folder compiles
back to the same manifest, and notes what it writes differently: a skill's
files are not in a manifest, so copy them in. It writes over no file.
folderOfManifest(manifest) from @nylorun/agents is the same converter, and
returns { files, exact, notes }. See
Convert.
Details
.build() returns the assembled agent. Generated projects call .build() so
the registry holds a built agent. Invalid tool schemas or duplicate tool names
raise AgentBuildError with one diagnostic per problem.
descriptionis required when this agent is used as a subagent..output(schema)validates the completed output and types it.JSON.stringify(agent)is the agent's loop manifest:manifestSchemaVersion: 7for a ReAct agent, or a workflow manifest (workflowSchemaVersion: 3) for a flow agent. A save turns it into the manifest'sharnesssection, and the harness runs it in that shape.session.manifest()returns{ sessionId, agentId, definition: { name, version }, manifestHash, manifest }, wheremanifestis the loop manifest the session's harness runs.Agent.from(json, { tools })rebuilds an agent from a loop manifest, with the code of its tools keyed by tool name. HTTP tools and agents used as tools need none. It checks the manifest with the Runtime's own schema and refuses unknown fields or invalid names withagent.build-failed, each message prefixed with its path (tools.0.name: …).harnessSectionOf(loopManifest)returns the harness section a save makes of a built agent, andsectionGaps({ harness, runtime })lists, as messages, the gaps between two sections that a save refuses. Both are exported from@nylorun/agents.
Keep secrets out of the agent
The manifest is public. Do not put API keys or tokens in instructions, URLs, or
headers. An HTTP tool sets credential, naming a secret slot of the runtime
section bound to the tool's URL, and the Runtime adds the Agent's secret for
that slot to each request. See
Secrets and credentials.
Older option-form constructors are listed on Compatibility.
Names
A tool's name and an MCP server's name match ^[A-Za-z0-9_-]{1,64}$: letters,
digits, _ and -, up to 64 characters, which every model provider accepts.
A save is refused naming any other. An MCP server's own tool names need no
change; our harness shows them to the model as server__tool. See
MCP.
- A tool's name may not contain
__, which names an MCP server's tools (tool.invalid-name). - Names are unique within each kind, a plugin's included: tools among tools
(
tool.duplicate-name), skills among skills (skill.duplicate-name), and servers among servers (mcp.duplicate-server).
The build fails on each with that diagnostic, and the Runtime refuses such a manifest.
No name is reserved. The harness adds tools of its own to each session,
though, and a turn fails with agent.build-failed, naming the tool, when one of
the agent's tools shares a name with one of them. Our harness adds:
| Tools | When |
|---|---|
bash, read, write, edit, grep, glob, save_artifact | The Agent has a sandbox (kind virtual or pod). |
read_artifact | Always. |
load_skill, read_skill_resource | The agent has skills. |
tool_search, tool_call | The session's MCP tools are deferred. |
schedule_wake | The manifest sets runtime.selfWake. See Wakes. |
memory | The manifest sets harness.memory. See Agent memory. |
A tool named bash works on an Agent of kind none and fails every turn on a
virtual one.