nora agents

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 lock <agent-id>`	블록을 잠가 MCP / CLI 편집을 차단.
`agents unlock <agent-id>`	잠금 해제(승인된 unlock 절차).
`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 tools list <agent-id>`	붙은 도구와 유효 정책 나열.
`agents tools set-policy <agent-id>`	붙인 도구의 버짓·실패 처리 오버라이드.
`agents tools clear-policy <agent-id>`	오버라이드 제거. 블록 기본값으로 복귀.

`agents create`

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`

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-output-rules <JSON|@file|-|null> LLM 이 쓴 뒤 적용되는 결정론적 후처리 규칙. null 로 필드 해제.
--set-retry <JSON|@file|-|null> LLM / 도구 실패에 대한 재시도 정책 ({ "maxAttempts": 3, "backoffMs": 1000, ... }). null 로 해제.

위치/크기

--set-x <n>, --set-y <n>, --set-width <n>

한꺼번에

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

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

`agents edit`

nora agents edit ag_abc

Agent JSON을 가져와 $EDITOR(기본 vi)에 엽니다. 저장하면 CLI가 update로 diff를 적용합니다. 여러 필드를 한 번에 바꿀 때 좋습니다. --set-* 플래그를 12개 이어 붙이는 것보다 빠를 때가 많습니다.

`agents delete`

nora agents delete ag_abc

Agent를 제거합니다. 이어진 와이어는 자동으로 가지치기됩니다. --yes를 안 넘기면 확인이 필요합니다.

`agents lock` / `agents unlock`

nora agents lock ag_abc
nora agents unlock ag_abc

에이전트를 잠가 MCP / CLI 편집을 막습니다. update / delete / apply_flow 로 이 에이전트를 수정하려는 호출은 서버가 거절합니다. 해제는 승인된 단일 필드 {"locked": false} 절차. 잠금 시맨틱은 agents · tools · actions · triggers 네 블록 타입이 동일합니다.

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

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

List

nora agents sources list ag_abc

모든 소스를 출력합니다. 종류(documents_folder, memory, kg, vector), ID, 설정됐으면 리트리벌 프리셋이 함께 나옵니다.

Attach

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

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

nora agents sources detach ag_abc \
  --kind documents_folder \
  --source-id billing

붙임을 제거합니다. 밑바탕 데이터 소스는 건드리지 않습니다.

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

메모리 붙임은 소스와 별개입니다. 모양은 같습니다.

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

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

nora agents memories set-preset ag_abc \
  --space-id sp_support_notes \
  --preset recency-boosted

Agent가 그 스페이스에서 리트리벌할 때 이 프리셋을 씁니다. 스페이스마다 다른 프리셋을 쓸 수 있습니다. 프리셋 풀기(최근성만으로 폴백):

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

`agents tools` (붙임별 정책)

같은 Tool 블록이 여러 에이전트에 붙을 수 있습니다. 에이전트마다 그 붙임에 대해 별도의 버짓·실패 처리 정책을 걸 수 있고, 에이전트가 필드를 비워 두면 블록의 기본값이 그대로 적용됩니다.

유효 정책 나열

nora agents tools list ag_abc

붙어 있는 도구마다 유효 정책 행을 출력합니다. 붙임별 오버라이드가 있으면 그 값을, 없으면 블록의 자체 기본값을 씁니다. 필드마다 from 라벨("attachment" / "block" / "default") 이 붙어 값이 어디에서 왔는지 보여 줍니다.

정책 세팅·업데이트

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

플래그(모두 선택이고, 안 넘긴 필드는 현재값 유지):

--tool-block-id <id> (필수) 붙임을 편집할 도구 블록.
--max-calls <n> 에이전트 실행 단위 로 허용되는 호출 수(턴 단위 아님).
--on-failure <fail|skip> 에이전트를 멈출지, 호출을 버리고 계속 갈지.
--max-attempts <n> 호출당 재시도 예산.
--max-cost-usd <n> 이 붙임의 지출 상한.

플래그에 빈 문자열을 넘기면(예: --on-failure "") 그 필드만 블록 기본값으로 되돌립니다. 오버라이드 전체를 지우려면 clear-policy 를 쓰세요.

정책 제거

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

붙임별 정책 행 전체를 지웁니다. 도구 블록의 자체 설정(에이전트 간 공유) 이 다시 적용됩니다.

레시피

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

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 모델 바꾸기

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에 승인 강제

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

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

CLI

SDK

Local App

nora agents

명령

`agents create`

Create 플래그

`agents update`

Update 플래그 (그룹별)

`agents edit`

`agents delete`

`agents lock` / `agents unlock`

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

List

Attach

Update

Detach

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

List / attach / detach

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

`agents tools` (붙임별 정책)

유효 정책 나열

정책 세팅·업데이트

정책 제거

레시피

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

Flow의 모든 Agent 모델 바꾸기

모든 Agent에 승인 강제

​명령

​agents create

​Create 플래그

​agents update

​Update 플래그 (그룹별)

​agents edit

​agents delete

​agents lock / agents unlock

​agents sources (데이터 붙이기)

​List

​Attach

​Update

​Detach

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

​List / attach / detach

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

​agents tools (붙임별 정책)

​유효 정책 나열

​정책 세팅·업데이트

​정책 제거

​레시피

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

​Flow의 모든 Agent 모델 바꾸기

​모든 Agent에 승인 강제

명령

`agents create`

Create 플래그

`agents update`

Update 플래그 (그룹별)

`agents edit`

`agents delete`

`agents lock` / `agents unlock`

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

List

Attach

Update

Detach

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

List / attach / detach

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

`agents tools` (붙임별 정책)

유효 정책 나열

정책 세팅·업데이트

정책 제거

레시피

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

Flow의 모든 Agent 모델 바꾸기

모든 Agent에 승인 강제