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

# SDK 개요

> 앱 코드에서 Nora Flow를 부르고 되먹이는 TypeScript 클라이언트

\*\*`@conscience-technology/nora-sdk`\*\*는 Nora 플랫폼의 TypeScript 클라이언트입니다. 에이전트 정의는 Nora(UI / MCP / CLI)에서 만들고, SDK는 앱 코드에서 그 에이전트를 **부르고, 들여다보고, 결과를 되먹입니다**. 정의는 못 씁니다. 정의 변경 경로는 UI / MCP / CLI → 승인 → 새 버전 하나뿐입니다. 대신 실행하고, 결과를 읽고, 피드백을 담고, 개선 큐를 제품 안에서 굴릴 수 있습니다.

<Note>
  **상태 (2026-09-06)**: 리포에 구현·tsc 통과, 현재 `0.0.1`. 공용 npm scope로 게시가 진행 중입니다. 계약이 안정적이라 게시 후 install URL만 바꾸면 됩니다.
</Note>

## 언제 SDK를 쓰나

코드에서 Nora와 대화하는 세 갈래, 호출자에 따라 다릅니다.

| 방식                                          | 적합                                                | 인증            |
| ------------------------------------------- | ------------------------------------------------- | ------------- |
| **SDK** (`@conscience-technology/nora-sdk`) | 앱 백엔드. 타입 · 에러 클래스 · 재시도 · 구조화 로깅 다 붙음            | PAT + 트리거 시크릿 |
| **MCP `run_flow`**                          | 코딩 에이전트(Claude Desktop, Cursor)가 사용자를 대신해 Flow 호출 | PAT / 세션      |
| **HTTP**                                    | 그 밖 (cron, curl, JS 아닌 백엔드)                       | 트리거 시크릿       |

앱이 이미 Node/TS로 돌고, 타입 결과 · 호출 단위 idempotency · `onBehalfOf` 감사 트레일 · 제품 안에 박힌 개선 루프가 필요하면 SDK가 정답입니다.

## 서버 사이드 전용

PAT과 트리거 시크릿을 다루므로 **브라우저에서 초기화하면 예외를 던집니다**. 조용히 도는 게 최악의 실패입니다. 최종 사용자 화면에서 실행이 필요하면 고객 서버가 프록시하세요.

## 시작하기

1. **[설치](/ko/sdk/install)** `npm install @conscience-technology/nora-sdk`, 사전 조건(Node 18+, ESM), 버전 pin.
2. **[Auth](/ko/sdk/auth)** PAT · 트리거 시크릿 발급, 필요한 스코프 선택.
3. **[클라이언트 옵션](/ko/sdk/client-options)** `ClientOptions` 전체 레퍼런스(baseUrl · 재시도 · 로깅 · 커스텀 fetch · trigger header).

## 메서드

CLI의 명령 그룹처럼, 메서드 카테고리별로 페이지가 나뉘어 있습니다.

| 카테고리                           | 인증                           | Verb                                                                                    |
| ------------------------------ | ---------------------------- | --------------------------------------------------------------------------------------- |
| [실행](/ko/sdk/execution)        | 트리거 시크릿                      | `flows.run` · `newTraceRef`                                                             |
| [피드백](/ko/sdk/feedback)        | 트리거 시크릿                      | `feedback` · `signals.report`                                                           |
| [투명성](/ko/sdk/transparency)    | PAT `read`                   | `resolve`                                                                               |
| [개선과 버전](/ko/sdk/improvements) | PAT `read` / `approve`       | `improvements.{list,get,approve,reject,revert,staleFixes}` · `versions.{list,rollback}` |
| [시뮬레이션](/ko/sdk/simulations)   | PAT `simulate`               | `simulations.{estimate,run,get,remaining,requery,promote}`                              |
| [리소스](/ko/sdk/resources)       | PAT `content` + `onBehalfOf` | `memory.{read,write}` · `knowledge.{upload,list}`                                       |
| [에러와 실패 모델](/ko/sdk/errors)    | 해당 없음                        | 타입 에러 클래스, 실패 4층, 로깅                                                                    |

## 관련

* [`nora flows run`](/ko/cli/flows) `flows.run`의 CLI 대응. SDK 게시 전까지 실전에 씁니다.
* [`nora feedback`](/ko/cli/feedback) `feedback` · `signals.report`의 CLI 대응.
* [`nora approvals`](/ko/cli/approvals) 개선 큐가 플랫폼과 공유하는 승인 워크플로우.