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

# nora agents

> Agent 블록 관리. 프롬프트, 모델, 제한, 데이터 소스, 메모리

Agent가 Flow의 추론 심장. `agents` 명령 그룹이 Agent 블록을 만들고 편집하고 리소스를 붙이는 CLI 표면.

`agents` 서브커맨드는 모두 활성 Flow에 동작. `nora flows use <slug>`로 고정하거나 `--flow`로 덮어씀.

## 명령

| 명령                                        | 설명                         |
| ----------------------------------------- | -------------------------- |
| `agents create --name <n>`                | 새 Agent 블록 추가.             |
| `agents update <agent-id>`                | 필드 패치(`--set-*` 플래그 다수).   |
| `agents edit <agent-id>`                  | Agent JSON을 `$EDITOR`에 열기. |
| `agents delete <agent-id>`                | Agent 제거(엣지 자동 가지치기).      |
| `agents sources list <agent-id>`          | 붙은 데이터 소스 나열.              |
| `agents sources attach <agent-id>`        | 데이터 소스 붙이기(문서, 메모리, KG).   |
| `agents sources update <agent-id>`        | 붙임 패치(프리셋, 제외).            |
| `agents sources detach <agent-id>`        | 붙임 제거.                     |
| `agents memories list <agent-id>`         | 붙은 메모리 스페이스 나열.            |
| `agents memories attach <agent-id>`       | 메모리 스페이스 붙이기.              |
| `agents memories detach <agent-id>`       | 메모리 스페이스 떼기.               |
| `agents memories set-preset <agent-id>`   | 리트리벌 프리셋을 메모리 스페이스에 묶기.    |
| `agents memories clear-preset <agent-id>` | 프리셋 풀기(최근성 폴백).            |

## `agents create`

```bash theme={null}
nora agents create \
  --name "Support Assistant" \
  --description "고객 지원 질문에 답" \
  --prompt-file prompts/support.md \
  --model gpt-4o-mini \
  --mode api
```

위치 (x, y)를 주면 그 자리에, 안 주면 자동 위치에 새 Agent 생성.

### Create 플래그

| 플래그                    | 목적                                               |
| ---------------------- | ------------------------------------------------ |
| `--name <n>`(필수)       | 표시 이름.                                           |
| `--description <d>`    | 짧은 설명.                                           |
| `--prompt <text>`      | 인라인 시스템 프롬프트.                                    |
| `--prompt-file <path>` | 파일에서 프롬프트 읽기. `--prompt`보다 우선.                   |
| `--model <m>`          | 모델 ID(`nora providers list` 참고).                 |
| `--mode`               | `api` / `internal` / `sdk`. 런타임 실행 모드.           |
| `--dispatch`           | `parallel` / `conditional` / `routed`. 다중 분기 동작. |
| `--x <n>`, `--y <n>`   | 캔버스 위치.                                          |

명령이 새 Agent의 ID를 출력. 이후 `update`/`sources` 호출에 쓰게 저장.

## `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
```

`--set-*` 플래그가 많음. 넘긴 필드만 바뀌고 나머지는 그대로.

### Update 플래그 (그룹별)

**정체성·콘텐츠**

* `--set-name <n>` 표시 이름.
* `--set-description <d>` 설명.
* `--set-prompt <text>` 인라인 프롬프트(교체).
* `--set-prompt-file <path>` 파일에서 프롬프트(교체).

**모델**

* `--set-model <m>` primary 모델.
* `--set-mode <mode>` `api` / `internal` / `sdk` / `local`.
* `--set-dispatch <mode>` `parallel` / `conditional` / `routed`.
* `--set-image-model <m>` 이미지 입력용 모델.
* `--set-voice-model <m>` 음성 입력용 모델.
* `--set-image-output-model <m>` 이미지 출력용 모델.
* `--set-voice-output-model <m>` 음성 출력용 모델.

**제한**

* `--set-max-turns <n>` 도구 호출 왕복 상한.
* `--set-max-tokens <n>` 실행당 토큰 상한.
* `--set-max-cost <usd>` 실행당 달러 상한.
* `--set-memory-max-cost <usd>` 실행당 메모리 작업 달러 상한.

**Trigger 플래그**

* `--mark-trigger` / `--unmark-trigger`이 Agent를 트리거 진입으로 지정.

**출력**

* `--set-output-target <target>` Agent 답변이 하류로 흐르는 곳.

**승인**

* `--set-approval on|off` 출력에 승인 요구.
* `--set-route-approval on|off` 라우팅 결정에 승인 요구.
* `--set-cost-approval <usd>|off` 실행 하나가 이 달러 비용을 넘으면 승인 요구.

**동작**

* `--set-force-fresh-context true|false` 턴마다 이전 컨텍스트 비우기.
* `--set-fuse-optout true|false` 리트리벌 융합 빼기(단일 소스만).

**위치/크기**

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

**한꺼번에**

* `--patch <json>` 병합할 임의 JSON 패치. 고급용. 같은 필드에 대한 다른 `--set-*`와 부딪힘.

`nora agents update --help`가 지금 전체 목록을 출력.

## `agents edit`

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

Agent JSON을 가져와 `$EDITOR`(기본 `vi`)에 열기. 저장하면 CLI가 `update`로 diff를 적용.

여러 필드를 한 번에 바꿀 때 좋음. `--set-*` 플래그를 12개 이어 붙이는 것보다 빠를 때가 많음.

## `agents delete`

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

Agent 제거. 이어진 와이어가 자동으로 가지치기됨. `--yes`를 안 넘기면 확인 필요.

## `agents sources` (데이터 붙이기)

데이터 소스가 Agent가 추론할 때 리트리벌하는 것. 붙임마다 소스 종류, ID, 리트리벌 프리셋(선택)을 지정.

### List

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

모든 소스를 출력: 종류(documents\_folder, memory, kg, vector), ID, 설정됐으면 리트리벌 프리셋.

### Attach

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

플래그:

* `--kind`(필수) `kg` / `vector` / `documents_folder` / `documents_file` / `memory`.
* `--source-id`(필수) 컬렉션 slug, 폴더 태그, 메모리 스페이스 ID 등.
* `--preset <preset-id>` 리트리벌 프리셋(`nora retrieval presets list` 참고).
* `--method <mode>` `vector` / `keyword` / `hybrid` / `kg_only`.
* `--modes <m1,m2>` 추가 리트리벌 모드.
* `--exclude-doc <id,…>` 특정 문서 제외.

### 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
```

기존 붙임 패치. 넘긴 플래그만 바뀜.

* `--set-preset`, `--set-method`, `--set-modes`.
* `--set-exclude-doc-ids <ids>` 제외 목록 교체.
* `--add-exclude-doc <id>` 하나 추가.
* `--remove-exclude-doc <id>` 하나 빼기.

### Detach

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

붙임 제거. 밑바탕 데이터 소스는 안 건드림.

## `agents memories` (메모리 스페이스 붙이기)

메모리 붙임은 소스와 별개. 모양은 같음.

### 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
```

### 리트리벌 프리셋을 메모리 스페이스에 묶기

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

Agent가 그 스페이스에서 리트리벌할 때 이 프리셋을 씀. 스페이스마다 다른 프리셋을 쓸 수 있음.

프리셋 풀기(최근성만으로 폴백):

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

## 레시피

### 프롬프트 + 모델 + 소스로 Agent 띄우기

```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
```

### Flow의 모든 Agent 모델 바꾸기

```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
```

비용을 실험할 때 좋음.

### 모든 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
```

그다음 배포. 모든 출력에 리뷰 게이트가 걸린 고위험 롤아웃.