# define (/docs/reference/agents/define)



```ts
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](/docs/build), [Workflows](/docs/build/workflows).

## `Agent` [#agent]

```ts
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**.

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

## `AgentBuilder` [#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](/docs/build/subagents).

## `tool` [#tool]

```ts
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](/docs/build/tools).

## `capability` [#capability]

```ts
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](/docs/build/capabilities).

## Helpers [#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 [#workflows]

| Builder                              | Page                             |
| ------------------------------------ | -------------------------------- |
| `Loop({ id, run, verify, decide })`  | [Loop](/docs/build/loop)         |
| `Chain({ id, steps })`               | [Chain](/docs/build/chain)       |
| `Switch({ id, on, cases, default })` | [Switch](/docs/build/switch)     |
| `Map({ id, over, each })`            | [Map](/docs/build/map)           |
| `Parallel({ id, branches })`         | [Parallel](/docs/build/parallel) |

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