NylorunDocsBeta
BuildDefine

Agent builder

Define an agent with instructions and a tool, then add only what it needs.

agents/assistant/agent.ts
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. id is the stable identifier sessions use; name is the label Studio shows.
  • .instructions() tells the model what to do. See Instructions.
  • .tools() adds tools the model may call. An http() 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 with agent.single-value when 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-run

Convert to a folder

npx nylorun export --folder assistant

export --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.

  • description is 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: 7 for a ReAct agent, or a workflow manifest (workflowSchemaVersion: 3) for a flow agent. A save turns it into the manifest's harness section, and the harness runs it in that shape.
  • session.manifest() returns { sessionId, agentId, definition: { name, version }, manifestHash, manifest }, where manifest is 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 with agent.build-failed, each message prefixed with its path (tools.0.name: …).
  • harnessSectionOf(loopManifest) returns the harness section a save makes of a built agent, and sectionGaps({ 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:

ToolsWhen
bash, read, write, edit, grep, glob, save_artifactThe Agent has a sandbox (kind virtual or pod).
read_artifactAlways.
load_skill, read_skill_resourceThe agent has skills.
tool_search, tool_callThe session's MCP tools are deferred.
schedule_wakeThe manifest sets runtime.selfWake. See Wakes.
memoryThe 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.

Next step

On this page