Agents

@nylorun/agents · beta

import { Agent, tool, capability, createClient, connectAgents } from "@nylorun/agents";
import type { BuiltAgent, ToolExecutionContext } from "@nylorun/agents";
import type { AgentRef, AgentTool } from "@nylorun/agents/define";

Authoring helpers live on @nylorun/agents (and @nylorun/agents/define). They are not @nylorun/harness root exports. Definitions have no .run().

`Agent`

Import: import { Agent } from "@nylorun/agents"

Name	Type	Required	Description
`options.id`	`string`	Yes	Stable programmatic agent identifier.
`options.name`	`string`	No	Human-readable label.
`options.description`	`string`	No	Catalog description. Required when this agent is used as a tool.
`options.instructions`	`string` or `readonly string[]`	No	Initial model instructions.
`options.tools`	`readonly (ToolDefinition \| AgentTool)[]`	No	Top-level tools (capability id `"agent"`). An `Agent` here becomes a tool named after the child's `id`.
`options.outputSchema`	`ToolSchemaSource`	No	Agent-level contract for completed engine output.
`options.metadata`	`JsonObject`	No	Opaque JSON.
Returns	`AgentBuilder`	—	Builder that accepts capabilities and hooks.

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

`AgentBuilder`

Method	Parameters	Returns	Description
`use(declaration)`	capability or helper result	`AgentBuilder`	Adds a named capability. New snapshot.
`before(scope, fn)`	`"turn" \| "step"`, `BeforeHook`	`AgentBuilder`	Returns a `Patch`.
`after(scope, fn)`	`"step" \| "turn"`, `AfterHook`	`AgentBuilder`	`Decision` or `TurnDecision`.
`build()`	None	`BuiltAgent`	Assembled facade.
`id` / `name` / `manifest` / `toJSON()`	—	identity	`toJSON()` is `manifestSchemaVersion: 4`.

BuiltAgent is a type-only facade (id, name, manifest). Invalid builds raise AgentBuildError.

AgentTool is Pick<BuiltAgent, "id" | "manifest" | "getBinding"> — a built agent or builder placed in another agent's tools. Import the type from @nylorun/agents/define (it is not re-exported on @nylorun/agents). See Subagents.

`tool`

Prefer input / output / run. Aliases: inputSchema / outputSchema / execute.

Field	Description
`name`	Tool name.
`description`	Model-facing text.
`input` / `output`	Zod or JSON schema.
`run` / `execute`	Implementation. Plain `return` is a completed result.
`approval`	Code-only. Truthy string or `true` pauses before `run`.
`effects`	Code-only: `"read" \| "idempotent" \| "write"`.

`capability`

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

tools accepts ToolDefinition | AgentTool, same as Agent({ tools }). capability({ model }) is deprecated. Durable manifests reject arbitrary middleware closures.

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 — Runtime-executed. SDK stubs throw sandbox.runtime-only if you call them in-process.

Skills: load_skill { name }; read_skill_resource { name, path } when resources exist.

MCP: names come from the discovered server; pinned in mcpSnapshot.

Session client

createClient({ url?, key? }) → AgentsClient. Defaults: NYLORUN_RUNTIME_URL, NYLORUN_SERVER_KEY.

Method	HTTP
`saveAgent`	`PUT /v1/agents/:id`
`listAgents`	`GET /v1/agents`
`createSession`	`PUT /v1/sessions/:id`
`listSessions`	`GET /v1/sessions`
`session(id)`	`SessionClient`
Vault CRUD	`/v1/vaults/...`

SessionClient: input, approve, respond, cancel (each needs idempotencyKey), history, observe, inspect.

history({ cursor?, agent?, signal? }) pages GET /v1/sessions/:id/items. agent filters by payload.agent.delegationId (one child invocation) or payload.agent.path (every concurrent child that shares that path).

Tools receive ToolExecutionContext. ctx.agent is optional AgentRef { id, path, delegationId? } — the root agent, or the child when this call belongs to a delegation. delegationId is absent on the root.

connectAgents({ agents: [parent] }) serves the parent and any agents used as its tools. Child tools cannot declare approval. ctx.ask, ctx.approve, ctx.sleep, and ctx.waitFor inside a delegated agent fail with delegation.interaction-unsupported.

`connectAgents`

Executor destination: NYLORUN_RUNTIME_URL + NYLORUN_EXECUTOR_KEY. implementationVersion defaults from NYLORUN_IMPLEMENTATION_VERSION, then dev. Claims send { requestId, implementationVersion } only.

Guides: Agent, Sessions, Executors.

Agents

On this page