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 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가 한 실행에서 이걸 몇 번 부를 수 있는지 상한.

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 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"를 씀.

시작

플로우

블록

데이터·지식

신뢰성

워크스페이스

레퍼런스

명령

`tools create`

`tools update`

Update 플래그 (그룹별)

`tools edit`

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

`tools params` (선언한 입력)

List

Add

Update

Remove·reorder

`tools headers` (HTTP 헤더)

List / add / remove

레시피

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

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

Tool 인자 얼리기