Libretto

Libretto는 견고한 웹 통합 (web integrations)을 구축하기 위한 툴킷입니다. 이는 여러분의 코딩 에이전트 (coding agent)에게 라이브 브라우저와 토큰 효율적인 CLI를 제공하여 다음과 같은 작업을 수행할 수 있게 합니다:

• 최소한의 컨텍스트 오버헤드 (context overhead)로 라이브 페이지 조사
• 사이트 API를 역공학 (reverse-engineer)하기 위한 네트워크 트래픽 캡처
• 사용자 동작을 기록하고 이를 자동화 스크립트 (automation scripts)로 재생
• 실제 사이트를 대상으로 중단된 워크플로 (workflows)를 대화형으로 디버깅

Saffron Health의 저희 팀은 일반적인 헬스케어 소프트웨어에 대한 브라우저 통합을 유지 관리하기 위해 Libretto를 구축했습니다. 다른 팀들도 동일한 작업을 더 쉽게 수행할 수 있도록 이를 오픈 소스로 공개합니다.

빠른 링크

• 웹사이트: libretto.sh
• 문서: libretto.sh/docs
• 저장소: github.com/saffron-health/libretto
• Discord: discord.gg/NYrG56hVDt

설치 (Installation)

npm install libretto

# 최초 온보딩: 스킬 설치 및 Chromium 다운로드
...

setup은 --skip-browsers를 전달하지 않는 한 .libretto/ 디렉토리를 생성하고, 에이전트 스킬 (agent skills)을 설치하며, Chromium을 다운로드합니다.

사용 사례 (Use cases)

Libretto는 코딩 에이전트를 통해 스킬 (skill)로 사용되도록 설계되었습니다. 다음은 몇 가지 프롬프트 (prompts) 예시입니다:

원샷 스크립트 생성 (One-shot script generation)

Libretto 스킬을 사용해줘. LinkedIn에 접속해서 처음 10개의 게시물에 대해 콘텐츠, 작성자, 반응 수, 처음 25개의 댓글, 그리고 처음 25개의 재게시(reposts) 내용을 스크래핑해줘.

여러분의 코딩 에이전트가 LinkedIn에 로그인할 수 있는 창을 열어줄 것이며, 그 후 자동으로 탐색을 시작할 것입니다.

대화형 스크립트 구축 (Interactive script building)

eclinicalworks EHR에서 환자의 주 보험 ID (primary insurance ID)를 가져오는 워크플로우 (workflow)를 보여드리겠습니다. Libretto skill을 사용하여 환자 이름과 생년월일 (dob)을 입력값으로 받아 보험 ID를 반환하는 Playwright 스크립트로 변환하세요. URL은 ...

Libretto는 브라우저에서 수행하는 사용자의 동작을 읽을 수 있으므로, 사용자가 워크플로우를 수행하면 그 동작을 사용하여 워크플로우를 재구축하도록 요청할 수 있습니다.

브라우저 자동화를 네트워크 요청으로 변환 (Convert browser automation to network requests)

./integration.ts에 Hacker News로 이동하여 처음 10개의 게시물을 가져오는 브라우저 스크립트가 있습니다. 이를 직접적인 네트워크 스크립트로 변환하세요. Libretto skill을 사용하세요.

Libretto는 브라우저의 네트워크 요청 (network requests)을 읽을 수 있으며, 이를 사용하여 API를 역공학 (reverse engineer)하고 해당 요청을 직접 호출하는 스크립트를 생성할 수 있습니다. API를 직접 호출하는 것은 UI 자동화 (UI automation)보다 더 빠르고 신뢰할 수 있습니다. 또한 Libretto에게 보안 분석 (security analysis)을 수행하도록 요청하여 요청 내의 일반적인 보안 쿠키 (security cookies)를 분석함으로써, 네트워크 요청 방식이 안전한지 이해할 수 있습니다.

깨진 통합 기능 수정 (Fix broken integrations)

./integration.ts에 Availity로 이동하여 환자의 자격 확인 (eligibility check)을 수행하는 브라우저 스크립트가 있습니다. 하지만 실행 시 깨진 셀렉터 (broken selector) 에러가 발생합니다. 이를 수정하세요. Libretto skill을 사용하세요.

에이전트 (Agents)는 Libretto를 사용하여 실패 상황을 재현하고, 워크플로우의 어느 지점에서든 일시 중지하며, 라이브 페이지를 검사하고, 모든 과정을 자율적으로 수행하여 문제를 수정할 수 있습니다.

CLI 사용법 (CLI usage)

명령줄 (command line)에서 직접 Libretto를 사용할 수도 있습니다. 모든 명령은 특정 세션을 대상으로 하는 --session <name> 옵션을 허용합니다.

npx libretto open <url>                    # 브라우저를 실행하고 URL을 엽니다
npx libretto run ./integration.ts --headless # 워크플로우를 실행하고 성공 시 종료합니다
npx libretto run ./integration.ts --headless --stay-open-on-success # 성공적인 실행 후 검사할 수 있도록 열린 상태를 유지합니다
...

run 세션은 open 세션과 동일하게 데몬(daemon) 기반 명령어를 통해 검사할 수 있습니다. 성공적인 실행은 기본적으로 브라우저를 종료합니다. pages, snapshot, exec를 위해 브라우저를 열린 상태로 유지하려면 --stay-open-on-success를 전달하세요. 실패하거나 일시 중지된 워크플로(workflow)는 브라우저를 열린 상태로 유지하므로, 워크플로를 수정하거나 재개하기 전에 정확한 페이지 상태를 검사할 수 있습니다.

전체 명령어 목록을 확인하려면 npx libretto help를 실행하세요.

설정 (Configuration)

모든 Libretto 상태는 프로젝트 루트의 .libretto/ 디렉토리에 저장됩니다. 설정 파일, 세션 및 프로필에 대한 자세한 내용은 설정 문서를 참조하세요.

커뮤니티 참여 (Join the Community)

Discord에 참여하여 다른 개발자들과 소통하고, 도움을 받고, 여러분이 만든 것을 공유하세요:

긴 형식의 스레드는 GitHub Discussions를 방문하세요. 버그를 발견하셨나요? 이슈를 생성(Open an issue)하세요.

라이선스 (License)

MIT License — 상업적 프로젝트 및 오픈 소스 프로젝트에서 자유롭게 사용할 수 있습니다.

개발 (Development)

이 저장소에서 로컬 개발을 진행하려면:

pnpm i
pnpm build
pnpm type-check
...

소스 레이아웃(Source layout):

• packages/libretto/src/cli/ — CLI 명령어
• packages/libretto/src/runtime/ — 브라우저 런타임 (network, recovery, downloads, extraction)
• packages/libretto/src/shared/ — 공유 유틸리티 (config, LLM client, logging, state)
• packages/libretto/test/ — 테스트 파일 (*.spec.ts)
• packages/libretto/README.template.md — 저장소 및 패키지 README의 진실의 원천 (source of truth)
• packages/libretto/skills/libretto/ — Libretto 스킬의 진실의 원천 (source of truth)

packages/libretto/README.template.md 또는 packages/libretto/skills/libretto/ 하위의 내용을 편집한 후에는 pnpm sync:mirrors를 실행하세요.

생성된 README, 스킬 미러(skill mirrors) 및 스킬 버전 메타데이터가 수정 없이 동기화되어 있는지 확인하려면 pnpm check:mirrors를 실행하세요. 릴리스를 하려면 pnpm prepare-release를 실행하세요.

[!NOTE]
이것은 활발하게 개발 중인 초기 단계의 프로젝트입니다. API는 버전 1.0 이전에 변경될 수 있습니다. 프로덕션 환경에서는 특정 버전을 고정(pinning)하여 사용하는 것을 권장합니다.

Saffron Health 팀에 의해 제작되었습니다.