nora agents

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 lock <agent-id>`	Freeze the block against MCP / CLI edits.
`agents unlock <agent-id>`	Unlock (sanctioned unlock ceremony).
`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 tools list <agent-id>`	List the agent’s connected tools with the effective policy.
`agents tools set-policy <agent-id>`	Override an attached tool’s budget / failure handling.
`agents tools clear-policy <agent-id>`	Remove the override and fall back to the block’s own default.

`agents create`

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`

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 / local.
--set-dispatch <mode>: parallel / conditional / routed.
--set-image-model <m>: model for image inputs.
--set-voice-model <m>: model for voice inputs.
--set-image-output-model <m>: model for image outputs.
--set-voice-output-model <m>: model for voice outputs.

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).
--set-output-rules <JSON|@file|-|null>: deterministic post-processing rules applied after the LLM writes. null clears the field.
--set-retry <JSON|@file|-|null>: retry policy for LLM / tool failures ({ "maxAttempts": 3, "backoffMs": 1000, ... }). null clears.

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`

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`

nora agents delete ag_abc

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

`agents lock` / `agents unlock`

nora agents lock ag_abc
nora agents unlock ag_abc

Freezes the agent against MCP / CLI edits: update / delete / apply_flow calls that would modify it are rejected server-side. Unlock is the sanctioned single-field {"locked": false} ceremony. Same lock semantics apply across agents, tools, actions, and triggers.

`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

nora agents sources list ag_abc

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

Attach

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

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

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

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

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):

nora agents memories clear-preset ag_abc --space-id sp_support_notes

`agents tools`: per-attachment policy

The same Tool block can be wired into several agents. Each agent can carry its own budget and failure-handling policy for that attachment. The block’s own defaults still apply where the agent leaves a field blank.

List effective policy

nora agents tools list ag_abc

Prints every connected tool with the effective policy row: the per-attachment override where one exists, otherwise the block’s own default. Each field carries a from marker: "attachment" / "block" / "default" so you can tell where the value actually comes from.

Set / update policy

nora agents tools set-policy ag_abc \
  --tool-block-id t_refund \
  --max-calls 3 \
  --on-failure skip \
  --max-attempts 2 \
  --max-cost-usd 0.10

Flags (all optional; omitted fields keep their current value):

--tool-block-id <id> (required): the tool block whose attachment to edit.
--max-calls <n>: calls allowed per agent run (not per turn).
--on-failure <fail|skip>: halt the agent or drop the tool call and continue.
--max-attempts <n>: retry budget per call.
--max-cost-usd <n>: spend ceiling for this attachment.

Passing a flag with the empty string (e.g. --on-failure "") clears that single field back to the block default. To wipe the whole override, use clear-policy instead.

Clear policy

nora agents tools clear-policy ag_abc --tool-block-id t_refund

Removes the entire per-attachment row so the tool block’s own settings (shared across agents) apply again.

Recipes

Bootstrap an Agent with prompt + model + sources

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

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

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.

CLI

SDK

Local App

nora agents

Commands

`agents create`

Create flags

`agents update`

Update flags: grouped

`agents edit`

`agents delete`

`agents lock` / `agents unlock`

`agents sources`: attach data

List

Attach

Update

Detach

`agents memories`: attach memory spaces

List / attach / detach

Bind a retrieval preset to a memory space

`agents tools`: per-attachment policy

List effective policy

Set / update policy

Clear policy

Recipes

Bootstrap an Agent with prompt + model + sources

Swap the model on every Agent in a Flow

Enforce approvals on every Agent

​Commands

​agents create

​Create flags

​agents update

​Update flags: grouped

​agents edit

​agents delete

​agents lock / agents unlock

​agents sources: attach data

​List

​Attach

​Update

​Detach

​agents memories: attach memory spaces

​List / attach / detach

​Bind a retrieval preset to a memory space

​agents tools: per-attachment policy

​List effective policy

​Set / update policy

​Clear policy

​Recipes

​Bootstrap an Agent with prompt + model + sources

​Swap the model on every Agent in a Flow

​Enforce approvals on every Agent

Commands

`agents create`

Create flags

`agents update`

Update flags: grouped

`agents edit`

`agents delete`

`agents lock` / `agents unlock`

`agents sources`: attach data

List

Attach

Update

Detach

`agents memories`: attach memory spaces

List / attach / detach

Bind a retrieval preset to a memory space

`agents tools`: per-attachment policy

List effective policy

Set / update policy

Clear policy

Recipes

Bootstrap an Agent with prompt + model + sources

Swap the model on every Agent in a Flow

Enforce approvals on every Agent