# Build (/docs/build)



```sh
npx nylorun init agents/support
npx nylorun check agents/support
npx nylorun apply agents/support --agent
npx nylorun chat support --message "Where is order A-1001?"
```

You author an agent as an [agent manifest](/docs/build/agent-manifests): an
`AGENT.md` with its name, description, and instructions, and optional JSON
files. `init` writes the folder, `check` compiles it offline, `apply --agent`
saves it as an [agent manifest](/docs/run/agent-manifests) and makes the
[Agent](/docs/run/agents) `support` from it, and `chat` opens a session on that
Agent. Folders are the default; the Agents SDK builder, `Agent()` exported from
`agents/index.ts`, suits agents assembled in code, saved with
`client.agentManifests.save({ agent, runtime })`.

Either way, the agent becomes the manifest's `harness` section, beside a
`runtime` section that says what it runs in. The Runtime runs each agent from
its manifest and the files saved with it, and never calls your code during a
session. Your services are reached as [HTTP tools](/docs/build/tools) and
remote [MCP servers](/docs/build/mcp).

An agent's body is either a ReAct loop, where the model decides what to call,
or a flow, where its stages decide what runs next. Start with an
[agent manifest](/docs/build/agent-manifests) or the
[Agent builder](/docs/build/agent), add only the parts that agent uses, then
[compose](/docs/build/subagents) when more than one agent or a fixed path is
required.

## Agents [#agents]

| Part          | In a folder                                | In the builder                       | Page                                                   |
| ------------- | ------------------------------------------ | ------------------------------------ | ------------------------------------------------------ |
| Instructions  | The `AGENT.md` body, `instructions/*.md`   | `.instructions("…")`                 | [Instructions](/docs/build/instructions)               |
| Tools         | `tools/<name>.json`                        | `.tools(http({ name, input, url }))` | [Tools](/docs/build/tools)                             |
| MCP           | `mcp.json`                                 | `.mcp({ github: { type, url } })`    | [MCP](/docs/build/mcp)                                 |
| Skills        | `skills/<name>/SKILL.md`                   | `.skills("./assistant-skills")`      | [Skills](/docs/build/skills)                           |
| Agent Plugins | `plugins/<name>/`                          | `.plugin("./plugins/github")`        | [Plugins](/docs/build/plugins)                         |
| Requirements  | `runtime.json`, the runtime section itself | `.requires({ sandbox: "pod" })`      | [Saving manifests](/docs/run/agent-manifests#requires) |
| Memory        | `memory` in `AGENT.md`                     | `save({ agent, runtime, memory })`   | [Agent memory](/docs/run/memory)                       |

Do not set a model on the agent. The Tenant chooses it; see
[Models](/docs/run/models). A session gets a sandbox and secrets from the
Agent it runs on; see [Agents](/docs/run/agents).

## Compose [#compose]

| Pattern     | In a folder                                                        | In the builder                                      | Page                               |
| ----------- | ------------------------------------------------------------------ | --------------------------------------------------- | ---------------------------------- |
| Subagents   | `agents/<id>/`                                                     | `.subagents(researcher)`                            | [Subagents](/docs/build/subagents) |
| Flow agents | `flow.json` over `agents/<id>/`                                    | `Agent({ id: "report" }).pipe(researcher, analyst)` | [Flow agents](/docs/build/flows)   |
| Pipe        | `{ "chain": [{ "agent": "researcher" }, { "agent": "analyst" }] }` | `.pipe(researcher, analyst)`                        | [Pipe](/docs/build/pipe)           |
| Switch      | `{ "switch": { "cases": { … }, "default": { … } } }`               | `.switch({ bug, docs, default: general })`          | [Switch](/docs/build/switch)       |
| Parallel    | `{ "parallel": { "security": { … }, "style": { … } } }`            | `.parallel({ security, style })`                    | [Parallel](/docs/build/parallel)   |
| Map         | `{ "map": { "each": { "agent": "writer" } } }`                     | `.map(writer)`                                      | [Map](/docs/build/map)             |
| Loop        | `{ "loop": { "run": { … }, "verify": { … }, "max": 3 } }`          | `.loop(coder, { verify: tester, max: 3 })`          | [Loop](/docs/build/loop)           |

## Serve your users [#serve-your-users]

Your app signs people in, holds the application key, and calls the Runtime for
each person. The Runtime never signs anyone in.

```ts
import { createClient } from "@nylorun/agents";

const client = createClient({
  url: process.env.NYLORUN_RUNTIME_URL!,
  key: process.env.NYLORUN_SERVER_KEY!,
});

const agentId = `users/${authenticatedUser.id}/support`;
await client.agents.put(agentId, { manifest: "support", owner: authenticatedUser.id });

const asUser = client.as(authenticatedUser.id, {
  scopes: ["sessions:own", "agents:read"],
});

const session = await asUser.createSession({
  agent: agentId,
  ownerUserId: authenticatedUser.id,
});
```

The server makes the person's Agent from the saved `support` manifest; `owner`
is its owner guard, so only that person's sessions run on it, with its sandbox
and secrets. See [Agents](/docs/run/agents). `as()` sends `Nylorun-Subject`
and `Nylorun-Scopes`. Default scope is `sessions:own`.

| Scope                   | Allows                                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------------------ |
| `sessions:own`          | The person's own sessions, and reading Agents.                                                   |
| `agents:read`           | Reading Agents, agent manifests, triggers, runs, and memories.                                   |
| `agents:write`          | Making, moving, forking, and deleting Agents, and writing their secrets, memories, and triggers. |
| `agent-manifests:write` | Saving and deleting agent manifests. A trusted issuer's token never carries it.                  |

Another person's session answers `404`. A route outside the scopes answers
`403` (`scope_required`). Only an application key can act for a person.

### AG-UI [#ag-ui]

```ts
import { createAgUiHandler } from "@nylorun/agents/ag-ui";

const agui = createAgUiHandler({
  agents: ["support"],
  subject: (request) => userFrom(request),
  basePath: "/api/agui",
  scopes: ["sessions:own"],
});

app.all("/api/agui/*", (request) => agui.fetch(request));
```

`agents` lists the ids of the Agents the endpoint runs. Every caller's thread
runs on that Agent, with its sandbox and secrets: make one Agent per audience,
or an Agent of kind `none` for an endpoint everyone uses.

To store `info` with a thread's session, add `session`: it is called when the
thread's session is created, and later runs keep what it returned.

```ts
const agui = createAgUiHandler({
  agents: ["support"],
  subject: (request) => userFrom(request),
  session: (subject) => ({ info: { plan: planOf(subject) } }),
});
```

`toNodeListener` from `@nylorun/agents/ag-ui` wraps `fetch` for `node:http`.
Assistant text arrives whole.

### A2A [#a2a]

```ts
import { createA2aHandler } from "@nylorun/agents/a2a";

const a2a = createA2aHandler({
  agents: ["support"],
  subject: (request) => userFrom(request),
});
```

`agents` lists Agent ids, as for AG-UI.

A2A 1.0 JSON-RPC: `SendMessage`, `GetTask`, `ListTasks`, `CancelTask`, and
push notification configs. There is no streaming: updates reach callers by
push. Each Agent's card is public, at
`{basePath}/{agent}/.well-known/agent-card.json`; set `publicUrl` behind a
proxy. The rules and extensions every Agent follows over A2A, and the client
for calling one, are in [A2A](/docs/a2a).

### Rules [#rules]

* Browsers go through your server. The Runtime refuses Tenant keys on requests
  that carry `Origin`.
* Strip every `Nylorun-*` header your clients send.
* Terminate TLS on your server.
* Keep the application key on the server.

Request shapes are on the [Runtime API](/reference/runtime). Call a session
from [Sessions](/docs/run/sessions).

## Next step [#next-step]

<Cards>
  <Card title="Agent manifests" description="Write an agent as Markdown and JSON, and check it offline." href="/docs/build/agent-manifests" />

  <Card title="Sessions" description="Open a session for a signed-in person." href="/docs/run/sessions" />
</Cards>
