define

Agent, tool, capability, helper, and workflow definitions from @nylorun/agents/define.

import { Agent, tool, capability, Chain, Loop } from "@nylorun/agents/define";
import type { BuiltAgent, AgentRef, AgentTool } from "@nylorun/agents/define";

Everything here is also exported from @nylorun/agents, except the AgentRef and AgentTool types. Definitions have no .run(); the Runtime runs them. Guides: Agent, Workflows.

`Agent`

Agent(options: AgentOptions): AgentBuilder

Starts an agent definition. Do not pass model; the Tenant chooses it.

Parameter	Type	Required	Description
`options.id`	`string`	Yes	Stable identifier used by manifests and sessions.
`options.name`	`string`	No	Human-readable label.
`options.description`	`string`	No	Catalog description. Required when the agent is used as a tool.
`options.instructions`	`string \| readonly string[]`	No	Initial model instructions.
`options.tools`	`readonly (ToolDefinition \| AgentTool)[]`	No	Top-level tools (capability id `"agent"`). An agent here becomes a subagent tool.
`options.outputSchema`	`ToolSchemaSource`	No	Contract for completed engine output.
`options.metadata`	`JsonObject`	No	Opaque JSON.

Returns an AgentBuilder.

Agent.from(manifest, implementations) reconstructs a built agent from a manifest and rejects schema 3.

export const assistant = Agent({
  id: "assistant",
  name: "Order assistant",
  instructions: "Help with orders.",
  tools: [lookupOrder],
}).build();

`AgentBuilder`

Method	Parameters	Returns	Description
`use(declaration)`	capability or helper result	`AgentBuilder`	Adds a named capability. Returns a new snapshot.
`before(scope, fn)`	`"turn" \| "step"`, `BeforeHook`	`AgentBuilder`	Hook that returns a `Patch`.
`after(scope, fn)`	`"step" \| "turn"`, `AfterHook`	`AgentBuilder`	Hook that returns a `Decision` or `TurnDecision`.
`build()`	none	`BuiltAgent`	Assembles the agent.
`id` / `name` / `manifest` / `toJSON()`	none	identity	`toJSON()` is `manifestSchemaVersion: 4`.

Throws AgentBuildError from build() for invalid tool schemas, duplicate tool names, or incompatible contributions.

BuiltAgent is a type-only facade (id, name, manifest). AgentTool is Pick<BuiltAgent, "id" | "manifest" | "getBinding">: a built agent or builder placed in another agent's tools. See Subagents.

`tool`

tool(options: ToolOptions): ToolDefinition

Field	Type	Required	Description
`name`	`string`	Yes	Tool name the model sees.
`description`	`string`	No	Model-facing text. Strongly recommended.
`input` / `output`	Zod or JSON schema	`input`	Argument and result schemas.
`run`	`(input, ctx) => output`	Yes	Implementation. A plain `return` is a completed result.
`approval`	`boolean \| string`	No	Code-only. Pauses for approval before `run`.
`effects`	`"read" \| "idempotent" \| "write"`	No	Code-only side-effect class.

inputSchema, outputSchema, and execute are accepted aliases. run receives a ToolExecutionContext; ctx.agent is an optional AgentRef { id, path, delegationId? } identifying the root or delegated agent.

Throw new ToolError(code, message) inside run to produce a failed tool result. See Tools.

`capability`

capability({
  id: "support",
  instructions: "…",
  tools: [findOrder],
  before: { turn?: fn, step?: fn },
  after: { step?: fn, turn?: fn },
})

Bundles instructions, tools, and hooks for .use(). tools accepts ToolDefinition | AgentTool. capability({ model }) is deprecated. Durable manifests reject arbitrary middleware closures. See Capabilities.

Helpers

Helper	Default capability id	Notes
`mcp(servers, { id? })`	`"mcp"`	Keys must equal each server `name`. Transports: `stdio`, `streamable-http`, `sse`.
`sandbox(options?, { id? })`	`"sandbox"`	Options: `image`, `network`, `resources`, `idle`.
`skills(directory, { id? })`	catalog basename	Injects `load_skill` / `read_skill_resource`.
`plugin(directory)`	plugin name	`type: "agent-plugin"`. Also `loadPlugin`.

Built-in tools:

Sandbox: bash, read, write, edit, grep, glob, executed by the Runtime. Calling the SDK stubs in-process throws sandbox.runtime-only.
Skills: load_skill { name }; read_skill_resource { name, path } when resources exist.
MCP: names come from the discovered server and are pinned in mcpSnapshot.

Workflows

Builder	Page
`Loop({ id, run, verify, decide })`	Loop
`Chain({ id, steps })`	Chain
`Switch({ id, on, cases, default })`	Switch
`Map({ id, over, each })`	Map
`Parallel({ id, branches })`	Parallel

Each returns a BuiltWorkflow that is exported, saved, and run like an agent. Invalid graphs throw WorkflowBuildError.

define

AgentCopy Anchor Link

AgentBuilderCopy Anchor Link

toolCopy Anchor Link

capabilityCopy Anchor Link

HelpersCopy Anchor Link