nora tools

Tool은 Agent가 런타임에 부르는 것입니다. tools 명령 그룹은 Tool 블록을 만들고 편집하고 설정합니다. Tool은 런타임(HTTP나 인라인), 타입 있는 파라미터, HTTP 헤더(선택)를 가집니다.

명령

명령	설명
`tools create --name <n>`	Tool 블록 추가.
`tools update <tool-id>`	필드 패치(`--set-*` 플래그 다수).
`tools edit <tool-id>`	Tool JSON을 `$EDITOR`에 열기.
`tools delete <tool-id>`	Tool 제거.
`tools lock <tool-id>`	블록을 잠가 MCP / CLI 편집을 차단.
`tools unlock <tool-id>`	잠금 해제(승인된 unlock 절차).
`tools verify-db <tool-id>`	SQL 툴의 DB 연결 테스트.
`tools params list <tool-id>`	선언한 파라미터 출력.
`tools params add <tool-id>`	파라미터 추가.
`tools params update <tool-id>`	파라미터 패치.
`tools params remove <tool-id>`	파라미터 제거.
`tools params reorder <tool-id>`	파라미터 재정렬.
`tools headers list <tool-id>`	HTTP 헤더 출력.
`tools headers add <tool-id>`	HTTP 헤더 추가.
`tools headers remove <tool-id>`	HTTP 헤더 제거.

`tools create`

nora tools create \
  --name refund_order \
  --description "order_id로 주문 환불" \
  --runtime '{"kind":"http","method":"POST","url":"https://api.example.com/refunds/{{order_id}}"}' \
  --params '[{"name":"order_id","type":"string","required":true,"description":"주문 ID","location":"url","source":"llm"}]'

플래그:

--name <n>(필수) Agent가 참조하는 방법
--description <d> 가장 중요한 필드. Agent가 이걸 보고 언제 툴을 부를지 정합니다. 분명히 쓰세요
--runtime <json> 런타임 스펙(HTTP 또는 인라인)
--params <json> 파라미터 배열. 정확한 모양은 nora schema show 참고
--x <n>, --y <n> 캔버스 위치

런타임 모양을 한눈에 봅니다: HTTP

{
  "kind": "http",
  "method": "POST",
  "url": "https://api.example.com/refunds/{{order_id}}",
  "auth": {"kind": "bearer", "value": "secrets://api_key"}
}

Inline(JS/Python/SQL)

{
  "kind": "inline",
  "lang": "javascript",
  "code": "return { doubled: input * 2 };"
}

명령이 새 Tool의 ID를 출력합니다.

`tools update`

nora tools update t_refund \
  --set-description "주문 환불 (부분이나 전체)" \
  --set-http-url "https://api.example.com/refunds/v2/{{order_id}}"

Update 플래그 (그룹별)

정체성

--set-name <n>
--set-description <d>
--set-icon <name>

동작

--set-idempotent on|off 두 번 불러도 한 번 부른 것과 같은지
--set-required on|off Agent가 실행마다 적어도 한 번 부릅니다
--set-approval on|off 호출 전마다 승인 요구
--set-max-turns <n> Agent가 한 실행에서 이걸 몇 번 부를 수 있는지 상한
--set-retry-safe on|off 일시적 실패에 재시도 안전 (켜면 서버가 자동 재시도).
--set-dedupe-key-template <template> 호출당 dedupe 키 템플릿. {{param}} 로 렌더링하고, 같은 렌더링 키를 가진 두 호출은 한 번의 실행으로 합쳐집니다. 자연 id 가 없는 idempotent 부작용에 씁니다.

HTTP 런타임

--set-runtime-kind http|inline 런타임 전환
--set-http-method <m> GET / POST / PATCH / PUT / DELETE
--set-http-url <url>
--set-http-auth-kind <k> none / api_key / bearer
--set-http-auth-header <name> api_key auth 용 헤더 이름. bearer는 무시됩니다
--set-http-auth-value <v> auth 값(리터럴이나 secrets://ref)

Inline 런타임

--set-inline-lang <lang> javascript / python / sql
--set-inline-code <text> 인라인 코드
--set-inline-code-file <path> 파일에서 코드(--set-inline-code 교체)
--set-inline-database-url <url> SQL 용 DB 연결 문자열. secrets://ref 받음

검증

--verify SQL 툴용. DB 연결을 테스트하고 성공하면 connected=true로 표시합니다

위치/크기

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

한꺼번에

--patch <json> 임의 JSON 병합

런타임 --set-* 플래그는 기존 런타임 객체에 deep-merge 됩니다. 그래서 전체를 다시 주지 않고 한 필드만 바꿉니다.

`tools edit`

nora tools edit t_refund

Tool JSON을 $EDITOR에 엽니다. 저장하면 적용됩니다.

`tools lock` / `tools unlock`

nora tools lock t_refund
nora tools unlock t_refund

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

`tools verify-db`

nora tools verify-db t_query_users

SQL Tool 용입니다. 설정한 DB에 연결해 프로브 쿼리를 돌립니다. 성공하면 runtime.connected=true로 표시되어 앱에서 Tool이 초록으로 보입니다. 실패하면 정확한 에러를 출력합니다(잘못된 URL, 드라이버 누락, auth 실패).

`tools params` (선언한 입력)

파라미터는 Agent가 값을 선택하는 형식화된 입력입니다. 파라미터마다 이름, 타입, 소스(Agent 선택이나 fixed), 위치, 설명이 있습니다.

List

nora tools params list t_refund

모든 파라미터를 JSON으로 출력합니다.

Add

nora tools params add t_refund \
  --name amount_cents \
  --type integer \
  --required \
  --location body \
  --source llm \
  --description "환불 금액 (센트)"

플래그:

--name <n>(필수)
--type <t>(필수) string / integer / number / float / boolean / array / object
--description <d> Agent가 값을 선택할 때 읽는 설명
--required 기본은 아닙니다. Agent가 줘야 합니다
--location <loc> url / query / body / header. HTTP 요청에서 값이 가는 곳
--source <src> llm(Agent 선택) 또는 fixed
--fixed-value <v> source=fixed 용

Update

nora tools params update t_refund \
  --name amount_cents \
  --set-required

패치합니다. 넘긴 필드만 바뀝니다.

Remove·reorder

nora tools params remove t_refund --name unused_param
nora tools params reorder t_refund --names order_id,amount_cents,reason

reorder는 전체 순열이 필요합니다(모든 param을 정확히 한 번).

`tools headers` (HTTP 헤더)

HTTP Tool 용입니다. 헤더는 런타임에 저장됩니다.

List / add / remove

nora tools headers list t_refund
nora tools headers add t_refund --name X-Api-Version --value "2026-07-01"
nora tools headers add t_refund --name Authorization --value 'secrets://refund_api_key'
nora tools headers remove t_refund --name X-Api-Version

시크릿 값은 secrets://<ref>로 넘기거나(워크스페이스 시크릿 참조) 평문 문자열로 넘깁니다(인라인 저장). 인터랙티브 시크릿 입력:

nora tools headers add t_refund --name Authorization --value ?
# CLI가 물어보고 입력을 가림

모든 입력 모드는 파이핑·시크릿을 참고하세요.

레시피

Tool을 한 URL에서 다른 URL로 옮기기

nora tools update t_refund --set-http-url https://api-v2.example.com/refunds/{{order_id}}

배포는 따로 합니다.

그걸 쓰는 모든 Tool의 API 키 돌리기

new_key="Bearer $(cat new-key.txt)"
for id in $(nora flows get support | jq -r '.blocks[] | select(.kind=="tool").id'); do
  # 이전 헤더 제거, 새 것 추가
  nora tools headers remove $id --name Authorization 2>/dev/null
  nora tools headers add $id --name Authorization --value "$new_key"
done

길게 보면 이게 낫습니다. secrets://api_key를 쓰고 밑바탕 시크릿을 한 번만 돌립니다.

Tool 인자 얼리기

Agent가 선택하도록 둔 인자를 특정 롤아웃용으로 fixed로 전환합니다:

nora tools params update t_refund \
  --name reason \
  --set-source fixed \
  --set-fixed-value "customer_requested"

이후 모든 호출이 Agent 출력과 상관없이 "customer_requested"를 씁니다.

CLI

SDK

Local App

명령

`tools create`

`tools update`

Update 플래그 (그룹별)

`tools edit`

`tools lock` / `tools unlock`

`tools verify-db`

`tools params` (선언한 입력)

List

Add

Update

Remove·reorder

`tools headers` (HTTP 헤더)

List / add / remove

레시피

Tool을 한 URL에서 다른 URL로 옮기기

그걸 쓰는 모든 Tool의 API 키 돌리기

Tool 인자 얼리기

​명령

​tools create

​tools update

​Update 플래그 (그룹별)

​tools edit

​tools lock / tools unlock

​tools verify-db

​tools params (선언한 입력)

​List

​Add

​Update

​Remove·reorder

​tools headers (HTTP 헤더)

​List / add / remove

​레시피

​Tool을 한 URL에서 다른 URL로 옮기기

​그걸 쓰는 모든 Tool의 API 키 돌리기

​Tool 인자 얼리기

명령

`tools create`

`tools update`

Update 플래그 (그룹별)

`tools edit`

`tools lock` / `tools unlock`

`tools verify-db`

`tools params` (선언한 입력)

List

Add

Update

Remove·reorder

`tools headers` (HTTP 헤더)

List / add / remove

레시피

Tool을 한 URL에서 다른 URL로 옮기기

그걸 쓰는 모든 Tool의 API 키 돌리기

Tool 인자 얼리기