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

> 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>`       | 메모리 스페이스 detach.             |
| `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` — 리트리벌 융합 opt out (단일 소스 사용).

**위치/크기**

* `--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 fetch, `$EDITOR` (기본: `vi`) 에 열기. 저장 시 CLI 가 `update` 로 diff 적용.

여러 필드 한 번에 바꾸고 싶을 때 최적 — 종종 12개 `--set-*` 플래그 체이닝보다 빠름.

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

그 다음 배포 — 모든 출력에 리뷰 게이트 있는 고위험 롤아웃.