Muse Code SDK란? MSP·권한 제어 구조와 활용 조건
Muse Code SDK의 로컬 프로토콜 연결 구조를 표현한 GPT Image 생성 대표 이미지
Muse Code SDK는 2026년 8월 31일 Meta가 개발자 프리뷰로 공개한 타입스크립트 라이브러리입니다. CLI의 세션·도구·권한 제어 엔진을 애플리케이션에 넣을 수 있지만, 아직 사전 1.0 단계이므로 고정된 호환성을 전제로 프로덕션에 바로 묶기보다 버전 고정과 회귀 검증이 필요합니다.
이 글은 Meta의 정식 출시 발표, 공식 SDK 저장소, 실행 가능한 퀵스타트, Muse Code 초기 설계 문서를 기준으로 MSP 구조와 활용 조건을 구분합니다.
- 정식 출시된 CLI와 개발자 프리뷰 SDK의 상태 차이
- 앱과 로컬 호스트를 잇는 MSP 통신 구조
- 세션 시작·응답 스트림·권한 결정·재개의 실행 순서
- CLI·SDK·Model API를 고르는 기준
- 사전 1.0 도입에서 필요한 안전장치
8월 31일 공식 발표는 Muse Code가 베타를 벗어났다고 명시하지만, 제품 개요 페이지에는 아직 “Now in beta” 문구가 남아 있습니다. 최신 상태 판단은 날짜가 명시된 출시 발표를 우선하되, SDK 자체는 별도로 Developer Preview입니다.
공식 발표: Muse Code: New plans and features
1. Muse Code SDK란 무엇인가
CLI가 정식 출시되고 SDK는 프리뷰로 열렸습니다
Meta는 Muse Code CLI에 세션 간 메시지, Workflow, Rewind를 추가하며 베타 종료를 발표했습니다. 같은 날 공개한 SDK는 CLI 뒤의 세션·도구·권한 제어 기능을 타입스크립트 코드에서 다룰 수 있게 한 별도 개발자 프리뷰입니다.
SDK와 Muse 호스트는 같은 배포물이 아닙니다
@muse-code/sdk는 npm에서 설치하는 라이브러리이고 MIT 라이선스로 공개됐습니다. 실제 에이전트 실행은 로컬의 muse 바이너리가 담당하므로, SDK 저장소가 공개됐다는 사실을 호스트 전체의 오픈소스화로 확대해서 해석하면 안 됩니다.
2. 기존 CLI만으로 부족했던 지점
사용자 인터페이스를 바꾸려면 제어 지점이 필요합니다
터미널 UI는 사람이 직접 대화하기에 빠르지만, 사내 대시보드·이슈 봇·배포 승인 화면처럼 고유한 인터페이스에는 그대로 넣기 어렵습니다. SDK는 세션을 만들고 출력 스트림을 받아 애플리케이션의 화면과 정책에 연결하는 제어면을 제공합니다.
권한 결정을 애플리케이션 정책으로 옮길 수 있습니다
에이전트가 파일 변경이나 명령 실행 승인을 요청하면 애플리케이션이 선택지를 표시하고 approval/decide 명령으로 결과를 돌려줄 수 있습니다. 무조건 허용하는 자동화가 아니라, 조직의 승인 규칙을 에이전트 루프 안에 넣는 방식입니다.
장시간 세션을 프로세스 수명과 분리할 수 있습니다
호스트를 정상 종료한 뒤 새 프로세스에서 같은 세션을 재개할 수 있습니다. 대화 기록, 현재 커서, 대기 중인 승인 요청을 다시 받아 작업을 이어가는 구조라서 한 번의 CLI 창 수명에 모든 상태를 묶지 않아도 됩니다.
3. Muse Code SDK MSP 작동 원리
애플리케이션이 로컬 호스트를 직접 띄웁니다
spawnMspConnection은 muse serve 자식 프로세스를 시작하고 초기 핸드셰이크를 반환합니다. 애플리케이션과 호스트 사이의 Muse Session Protocol, 즉 MSP 제어 통신은 표준 입출력을 사용하므로 별도 웹 서버를 배포할 필요가 없습니다.
공식 발표의 “no server and no network”는 SDK와 로컬 호스트 사이의 MSP 제어 경로를 가리킵니다. 호스트가 모델 제공자에 추론을 요청하는 네트워크 통신까지 없다는 뜻은 아닙니다.
명령과 알림이 상태 변경과 관찰을 나눕니다
session/start, turn/start, approval/decide처럼 상태를 바꾸는 작업은 command로 보냅니다. 응답 토큰과 항목 완료, 턴 종료는 notification으로 받아 화면이나 로그에 반영합니다. 공식 퀵스타트는 알림 핸들러가 하나이므로 핸드셰이크 직후 등록해야 한다고 안내합니다.
세션 내구성과 멱등성이 재시도를 받칩니다
SDK의 command는 명령 ID를 관리해 응답이 끊긴 뒤 같은 작업을 재시도할 때 중복 실행 위험을 줄입니다. 세션은 호스트 종료 후에도 재개할 수 있고, 구조적으로는 VS Code Agent Host의 세션 지속·멀티윈도우 구조처럼 화면과 실행 상태의 수명을 분리한다는 공통점이 있습니다.
4. Muse Code SDK 타입스크립트 최소 실행 흐름
Node 20·SDK·Muse 바이너리가 필요합니다
공식 저장소는 Node.js 20 이상과 @muse-code/sdk를 요구합니다. 라이브러리의 런타임 의존성은 0개지만, 실행 시 대화할 muse 바이너리와 로그인 또는 API 자격 증명이 준비돼 있어야 합니다.
호스트 초기화 뒤 세션을 시작합니다
다음 코드는 공식 퀵스타트의 핵심 순서를 줄인 것입니다. 핸드셰이크가 끝나기 전에는 트래픽을 보낼 수 없고, 초기화 뒤에 알림 핸들러를 등록한 다음 세션을 시작합니다.
import { spawnMspConnection } from "@muse-code/sdk";
const handshake = spawnMspConnection({
command: museBin,
args: ["serve"],
cwd: workspaceRoot,
});
const msp = await handshake.initialize({
clientInfo: { name: "my-app", version: "1.0.0" },
});
msp.connection.onNotification((notification) => {
// 응답 스트림과 승인 요청을 처리합니다.
});
const result = await msp.connection.command(
"session/start",
{ workspaceRoot },
);권한 요청과 세션 재개를 별도 경로로 시험합니다
승인 요청에는 허용·거절 선택을 명시해 응답하고, 종료할 때는 msp.close()로 writer lease를 해제합니다. 새 프로세스에서는 session/resume과 기존 sessionId를 사용해 기록과 대기 요청을 복구합니다.
5. Muse CLI·SDK·Model API 차이
반복 개발은 CLI가 가장 단순합니다
개발자가 터미널에서 저장소를 탐색하고 코드를 고치는 용도라면 완성된 UI와 승인 흐름이 있는 Muse CLI가 맞습니다. 별도 앱 코드를 만들지 않아도 세션과 도구를 바로 사용할 수 있습니다.
제품 안에 세션을 넣을 때 SDK를 고릅니다
맞춤 화면, 자체 권한 정책, 장기 세션, 이벤트 스트림이 필요하면 SDK가 적합합니다. Claude Managed Agents Chat SDK의 세션·보안 설계처럼 에이전트 런타임을 제품의 채널과 승인 체계에 연결하는 문제를 다룰 때 비교 대상이 됩니다.
에이전트 루프 자체를 만들 때 Model API가 필요합니다
Muse Code의 세션·도구 설계를 쓰지 않고 모델 호출, 도구 스키마, 반복 조건을 직접 구성하려면 Model API가 더 낮은 층입니다. 여러 하위 에이전트의 작업 분해가 목적이라면 Google Antigravity Teamwork의 멀티에이전트 패턴도 함께 비교할 수 있습니다.
| 선택지 | 가장 잘 맞는 상황 | 직접 책임질 부분 |
|---|---|---|
| Muse CLI | 터미널 중심 개발 | 작업 지시와 승인 |
| Muse SDK | 맞춤 앱·내부 도구 | UI, 정책, 수명주기 |
| Model API | 독자 에이전트 런타임 | 루프, 도구, 상태 전체 |
6. 개발자 프리뷰 한계와 실패 조건
사전 1.0 API는 minor 버전에서도 바뀔 수 있습니다
공식 README는 안정성 약속이 없으며 API 표면이 자리 잡는 동안 minor 릴리스에서 변경될 수 있다고 명시합니다. 패키지 버전을 범위로 열어 두기보다 정확히 고정하고, 업그레이드 전에 타입 검사와 통합 테스트를 실행하는 편이 안전합니다.
프로토콜 지문 차이는 경고지만 무시할 신호는 아닙니다
SDK는 호스트의 스키마 fingerprint를 비교하고 차이가 나면 경고를 설정합니다. 공식 문서는 이를 즉시 실패가 아닌 경고로 다루지만, 알 수 없는 terminal 값과 새 알림 종류를 견디도록 클라이언트를 작성해야 합니다.
바이너리·자격 증명·실험 기능이 실행을 막을 수 있습니다
muse 바이너리가 없거나 모델 제공자 자격 증명이 없으면 세션이 정상 동작하지 않습니다. 퀵스타트는 호스트 종료 코드 5를 해당 빌드에서 실험 SDK 계층이 꺼진 경우로 설명하므로, 오류 코드와 stderr를 함께 기록해야 합니다.
7. Muse Code SDK 도입 전 실무 체크리스트
워크스페이스와 권한 선택지를 먼저 고정합니다
호스트가 접근할 저장소 경로를 좁게 정하고, 승인 요청의 선택지를 제품 정책에 매핑합니다. 사용자에게 보여 주지 않고 자동 허용할 범위가 있다면 코드와 운영 문서 양쪽에 근거를 남깁니다.
세션 저장·종료·재개를 한 묶음으로 테스트합니다
정상 응답만 확인하지 말고 실행 중 취소, 승인 대기 중 종료, 호스트 충돌, 새 프로세스 재개를 포함합니다. 특히 close() 뒤 다른 프로세스가 writer lease를 얻고 같은 세션을 불러오는지 검증해야 합니다.
버전과 스키마 경고를 배포 조건에 넣습니다
SDK와 Muse 바이너리 버전을 배포 manifest에 기록하고 fingerprint 경고를 관측 지표로 남깁니다. 프리뷰 기간에는 자동 업데이트보다 검증된 조합을 단계적으로 승격하는 방식이 적합합니다.
- Node.js 20 이상 확인
muse바이너리와 로그인 상태 확인- 알림 핸들러를 초기화 직후 등록
- 승인 요청의 기본값을 명시
- 취소·실패·재개 통합 테스트 추가
- SDK와 호스트 버전 고정
8. Muse Code SDK Q&A와 정리
Q1. Muse Code SDK만 설치하면 바로 실행되나요?
아닙니다. Node.js 20 이상, npm 패키지, 로컬 muse 바이너리, 로그인 또는 사용 가능한 제공자 자격 증명이 모두 필요합니다.
Q2. MSP는 원격 서버 프로토콜인가요?
공식 SDK 기본 경로는 애플리케이션이 로컬 muse serve를 띄우고 표준 입출력으로 통신하는 구조입니다. 별도 MSP 웹 서버를 운영하는 방식으로 설명되지 않습니다.
Q3. SDK가 MIT면 Muse Code 전체가 오픈소스인가요?
그렇게 단정할 수 없습니다. 공개 저장소와 MIT 라이선스는 SDK·프로토콜 선언·예제 범위에 적용되며, 실제 Muse 호스트 바이너리는 별도 구성요소입니다.
Q4. 기존 세션을 다른 프로세스에서 이어갈 수 있나요?
정상 종료로 writer lease를 해제한 뒤 새 연결에서 session/resume을 호출할 수 있습니다. 반환되는 history mode가 inline인지 snapshot인지 확인한 뒤 기록을 읽어야 합니다.
Q5. 지금 프로덕션에 써도 되나요?
시험 도입은 가능하지만 SDK는 Developer Preview이고 사전 1.0입니다. 버전 고정, 권한 정책, 오류 분류, 재개 테스트를 갖춘 제한된 범위부터 시작하는 편이 맞습니다.
Muse Code SDK의 핵심은 새 모델이 아니라 CLI의 세션 엔진을 제품 코드에서 제어할 수 있게 한 점입니다. 도입 판단은 기능 수보다 프리뷰 호환성과 권한·수명주기 운영 능력을 기준으로 해야 합니다.
9. 참고 자료
공식 발표와 제품 배경
SDK 코드와 실행 사양
'AI Agent' 카테고리의 다른 글
| GitHub Copilot PR 승인, 사람 리뷰를 대체할 수 있을까? (0) | 2026.09.02 |
|---|---|
| Broadcom AgentMinder 출시, AI 에이전트 도구 호출 통제 원리 (0) | 2026.09.01 |
| Antigravity /boost란? 멀티에이전트 추론·사용 조건 정리 (0) | 2026.09.01 |
| VS Code Agent Host란? 세션 지속·멀티윈도우 구조 정리 (0) | 2026.09.01 |
| Omarchy 사용법: 설치부터 AI 개발 환경·실전 사례까지 (0) | 2026.08.31 |
