> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# nora agents

> Manage Agent blocks — prompts, models, limits, data sources, memory.

An Agent is the reasoning core of a Flow. The `agents` command group is the CLI surface for creating, editing, and attaching resources to Agent blocks.

Every `agents` subcommand operates on the active Flow. Pin with `nora flows use <slug>` or override with `--flow`.

## Commands

| Command                                   | Description                                   |
| ----------------------------------------- | --------------------------------------------- |
| `agents create --name <n>`                | Add a new Agent block.                        |
| `agents update <agent-id>`                | Patch fields (many `--set-*` flags).          |
| `agents edit <agent-id>`                  | Open the Agent's JSON in `$EDITOR`.           |
| `agents delete <agent-id>`                | Remove the Agent (edges auto-prune).          |
| `agents sources list <agent-id>`          | List attached data sources.                   |
| `agents sources attach <agent-id>`        | Attach a data source (documents, memory, KG). |
| `agents sources update <agent-id>`        | Patch an attachment (preset, exclusions).     |
| `agents sources detach <agent-id>`        | Remove an attachment.                         |
| `agents memories list <agent-id>`         | List attached memory spaces.                  |
| `agents memories attach <agent-id>`       | Attach a memory space.                        |
| `agents memories detach <agent-id>`       | Detach a memory space.                        |
| `agents memories set-preset <agent-id>`   | Bind a retrieval preset to a memory space.    |
| `agents memories clear-preset <agent-id>` | Unbind the preset (fall back to recency).     |

## `agents create`

```bash theme={null}
nora agents create \
  --name "Support Assistant" \
  --description "Answers customer support questions" \
  --prompt-file prompts/support.md \
  --model gpt-4o-mini \
  --mode api
```

Creates a new Agent at position (x, y) if given; otherwise auto-positions.

### Create flags

| Flag                    | Purpose                                                       |
| ----------------------- | ------------------------------------------------------------- |
| `--name <n>` (required) | Display name.                                                 |
| `--description <d>`     | Short description.                                            |
| `--prompt <text>`       | Inline system prompt.                                         |
| `--prompt-file <path>`  | Read prompt from file. Overrides `--prompt`.                  |
| `--model <m>`           | Model id (see `nora providers list`).                         |
| `--mode`                | `api` / `internal` / `sdk`. Runtime execution mode.           |
| `--dispatch`            | `parallel` / `conditional` / `routed`. Multi-branch behavior. |
| `--x <n>`, `--y <n>`    | Canvas position.                                              |

The command prints the new Agent's ID — save it for subsequent `update`/`sources` calls.

## `agents update`

```bash theme={null}
nora agents update ag_abc \
  --set-prompt-file prompts/support-v2.md \
  --set-max-cost 0.25 \
  --set-approval on
```

The command supports many `--set-*` flags. Only fields you pass change; the rest stay as they were.

### Update flags — grouped

**Identity & content**

* `--set-name <n>` — display name.
* `--set-description <d>` — description.
* `--set-prompt <text>` — inline prompt (replaces).
* `--set-prompt-file <path>` — prompt from file (replaces).

**Model**

* `--set-model <m>` — primary model.
* `--set-mode <mode>` — `api` / `internal` / `sdk`.
* `--set-dispatch <mode>` — `parallel` / `conditional` / `routed`.
* `--set-image-model <m>` — model for image inputs.
* `--set-voice-model <m>` — model for voice inputs.
* `--set-voice-model-locale <l>` — voice model locale.

**Limits**

* `--set-max-turns <n>` — tool-call round-trip cap.
* `--set-max-tokens <n>` — token cap per run.
* `--set-max-cost <usd>` — dollar cap per run.
* `--set-memory-max-cost <usd>` — dollar cap for memory ops per run.

**Trigger flag**

* `--mark-trigger` / `--unmark-trigger` — designate this Agent as the trigger entry.

**Output**

* `--set-output-target <target>` — where the Agent's answer flows to downstream.

**Approvals**

* `--set-approval on|off` — require approval on output.
* `--set-route-approval on|off` — require approval on routing decisions.
* `--set-cost-approval <usd>|off` — require approval when a single run exceeds this dollar cost.

**Behavior**

* `--set-force-fresh-context true|false` — clear prior context each turn.
* `--set-fuse-optout true|false` — opt out of retrieval fusion (use single source).

**Position/size**

* `--set-x <n>`, `--set-y <n>`, `--set-width <n>`.

**Bulk**

* `--patch <json>` — arbitrary JSON patch to merge in. Advanced use; conflicts with other `--set-*` flags for the same field.

`nora agents update --help` prints the current full list.

## `agents edit`

```bash theme={null}
nora agents edit ag_abc
```

Fetches the Agent's JSON, opens it in `$EDITOR` (default: `vi`). On save, the CLI applies the diff via `update`.

Best when you want to change several fields at once — often faster than chaining a dozen `--set-*` flags.

## `agents delete`

```bash theme={null}
nora agents delete ag_abc
```

Removes the Agent. Wires connected to it are pruned automatically. Requires confirmation unless `--yes` is passed.

## `agents sources` — attach data

Data sources are what the Agent can retrieve from at inference. Each attachment specifies a source kind, an ID, and optional retrieval preset.

### List

```bash theme={null}
nora agents sources list ag_abc
```

Prints all sources: kind (documents\_folder, memory, kg, vector), ID, and retrieval preset if set.

### Attach

```bash theme={null}
nora agents sources attach ag_abc \
  --kind documents_folder \
  --source-id billing \
  --preset high-precision \
  --method hybrid
```

Flags:

* `--kind` (required) — `kg` / `vector` / `documents_folder` / `documents_file` / `memory`.
* `--source-id` (required) — collection slug, folder tag, memory space ID, etc.
* `--preset <preset-id>` — retrieval preset (see `nora retrieval presets list`).
* `--method <mode>` — `vector` / `keyword` / `hybrid` / `kg_only`.
* `--modes <m1,m2>` — additional retrieval modes.
* `--exclude-doc <id,…>` — exclude specific documents.

### Update

```bash theme={null}
nora agents sources update ag_abc \
  --kind documents_folder \
  --source-id billing \
  --set-preset different-preset \
  --add-exclude-doc doc_xyz
```

Patch an existing attachment. Only flags passed change.

* `--set-preset`, `--set-method`, `--set-modes`.
* `--set-exclude-doc-ids <ids>` — replace the exclusion list.
* `--add-exclude-doc <id>` — append one.
* `--remove-exclude-doc <id>` — drop one.

### Detach

```bash theme={null}
nora agents sources detach ag_abc \
  --kind documents_folder \
  --source-id billing
```

Removes the attachment. The underlying data source is not touched.

## `agents memories` — attach memory spaces

Memory attachments are separate from sources. Same shape.

### List / attach / detach

```bash theme={null}
nora agents memories list ag_abc
nora agents memories attach ag_abc --space-id sp_support_notes
nora agents memories detach ag_abc --space-id sp_support_notes
```

### Bind a retrieval preset to a memory space

```bash theme={null}
nora agents memories set-preset ag_abc \
  --space-id sp_support_notes \
  --preset recency-boosted
```

The Agent uses this preset when retrieving from that specific space. Different spaces can use different presets.

Clear the preset (fall back to recency-only):

```bash theme={null}
nora agents memories clear-preset ag_abc --space-id sp_support_notes
```

## Recipes

### Bootstrap an Agent with prompt + model + sources

```bash theme={null}
AGENT=$(nora agents create \
  --name "Support" \
  --prompt-file prompts/support.md \
  --model gpt-4o \
  --max-turns 10 \
  | jq -r '.id')

nora agents sources attach $AGENT --kind documents_folder --source-id policies
nora agents memories attach $AGENT --space-id customer_history
```

### Swap the model on every Agent in a Flow

```bash theme={null}
for id in $(nora flows get support | jq -r '.blocks[] | select(.kind=="agent").id'); do
  nora agents update $id --set-model gpt-4o-mini
done
```

Handy when doing cost experiments.

### Enforce approvals on every Agent

```bash theme={null}
for id in $(nora flows get support | jq -r '.blocks[] | select(.kind=="agent").id'); do
  nora agents update $id --set-approval on
done
```

Then publish — high-stakes rollout with a review gate on every output.