Paragent
브라우저 작업을 한 번 기록합니다. 모델 없이 결정론적으로 재현하고, 페이지가 변경되면 수정합니다.
CI
License: MIT
TypeScript
브라우저 에이전트는 실행할 때마다 동일한 작업을 재도출합니다. 대시보드에서 보고서를 가져오라고 요청하면, DOM을 다시 읽고, 계획을 다시 세우며, 모든 클릭을 다시 추론합니다. 이는 어제 이미 찾았던 경로를 재발견하는 데 토큰과 실제 시간을 소모하며, 틀릴 새로운 기회를 만듭니다.
Paragent는 두 번째 실행에서 모델을 제외합니다. 개발자가 웹 UI를 통과하는 성공적인 궤적을 기록하고, 이를 모든 단계에 후조건 단언(post-condition assertion)이 포함된 결정론적으로 재현 가능한 스크립트로 컴파일하며, 모델 없이 재현합니다. 단언이 실패할 경우 — 버튼이 이동했거나, 레이블이 변경되었을 때 — 모델이 다시 호출되어 해당 단계만 수정하고, 수정된 스크립트가 다음번에 실행됩니다.
<p align="center">
<img src="https://raw.githubusercontent.com/myselfsiddharth/Paragent/HEAD/docs/assets/demo.gif" alt="궤적을 기록하고, 모델 없이 재현하며, UI 변경 후 수정하는 과정" width="720">
</p>
<p align="center">
<sub>
문서화된 <code class="npm run">npm run</code> 명령어 대신, 예시 스크립트에 의해 구동되는 번들된 픽스처(fixture)를 대상으로 실제 실행을 수행합니다. 저장소에서 제공하는 것은 <b class="record">기록(record)</b>과 <b class="replay">재현(replay)</b> 기능입니다. 여기서 오늘날의 <b class="record">기록</b>은 에이전트가 제안하는 것이 아니라 개발자가 직접 궤적을 타이핑하는 것(<code class="src/recorder/cli.ts">src/recorder/cli.ts</code>)을 의미합니다. 이 방식은 범위가 지정되어 있지만, 아직 구축되지 않았습니다([https://github.com/DevToolie/Paragent/issues/127](https://github.com/DevToolie/Paragent/issues/127)). <b class="repair">복구(repair)</b> 기능은 기본적으로 아무것도 제안하지 않는 <code class="StubRepairModelClient">StubRepairModelClient</code>를 사용합니다. 두 가지 옵트인 클라이언트가 존재합니다 — 키가 필요한 <code class="AnthropicRepairModelClient">AnthropicRepairModelClient</code>([https://github.com/DevToolie/Paragent/issues/27](https://github.com/DevToolie/Paragent/issues/27), #27)와 키가 필요 없는 <code class="DelegatedRepairModelClient">DelegatedRepairModelClient</code>([https://github.com/DevToolie/Paragent/issues/189](https://github.com/DevToolie/Paragent/issues/189), #189) — 하지만 실제 자체 복구(self-heal)는 아직 측정된 바가 없습니다.
</sub>
</p>
작동 방식 (How it works)
| 단계 (Stage) | 발생하는 일 (What happens) | 관련된 모델? (Model involved?) |
|---|
| 기록(Record) | 개발자가 수동으로 작업을 한 번 완료합니다. 모든 동작과 그 후의 조건이 궤적(trajectory)으로 포착됩니다. | 없음 (No) |
| ... | | |
단계별 단언(assertion-per-step) 설계가 핵심입니다: 잘못된 작업을 조용히 완료하는 대신, 오류가 발생한 단계에서 명확하게 실패하는 재현이 가능합니다.
API 키가 필요 없는 복구 (Repair without an API key)
이미 모델 접근 권한을 가진 에이전트라면 Paragent는 자체적인 것이 필요하지 않습니다. 콜백(callback)을 전달하고 사용자의 예산으로 직접 복구를 수행할 수 있습니다 — ANTHROPIC_API_KEY도, 두 번째 청구서도 없습니다:
import { DelegatedRepairModelClient } from "paragent/dist/src/runner/repair-delegated.js";
...
null을 반환하여 거부할 수 있으며, 이 단계는 다른 실패한 제안과 마찬가지로 REPAIR_EXHAUSTED를 기록합니다.
에이전트가 비용을 지불하기 때문에 Paragent는 복구 비용(repair cost)을 알 수 없습니다. 해당 실행은 0으로 계산되는 대신 repair_cost_measured: false로 표시되며 §9 비용 측정 항목에서 제외됩니다 — 자세한 내용은 ADR-0020를 참조하십시오. 게이트(gate) 측정 실행에는 여전히 AnthropicRepairModelClient가 필요합니다.
60초 만에 사용해 보기
클론(clone), 자격 증명(credentials), 라이브 사이트 없이도 패키지 내부에 브라우저 피처(fixture)가 포함되어 있습니다.
npx playwright install chromium
...
npx playwright install chromium은 의도적으로 별도의 단계입니다: 이 명령어는 브라우저를 다운로드하며, npm install 과정에서 사용자에게 묻지 않고 약 150MB의 패키지를 가져오는 것은 좋지 않은 습관입니다. 그 외 모든 것은 오프라인으로 작동합니다.
해당 번들을 재생하려면 피처 페이지에 대해 서버에 바인딩된 host와 port가 필요하며, 이는 실제 사이트를 대상으로 기록할 때 발생하는 것과 동일한 전제 조건입니다.
대신 기록기를 실제 사이트에 연결하십시오:
npx paragent record --base-url http://127.0.0.1:3000 --headed
기록된 값은 파라미터 슬롯(parameter slots)이 되므로, 하나의 기록으로 실행 계열(family of runs) 전체를 커버할 수 있습니다:
npx paragent record --fixture --dashboard-title "Q3 Latency" --series-count 5
<details>
<summary>클론을 사용하는 경우, 기여하고 싶다면</summary>
git clone https://github.com/DevToolie/Paragent.git
cd Paragent
npm install
...
npm 스크립트는 TypeScript 소스 코드를 tsx를 통해 실행하며; 배포된 패키지는 컴파일된 JavaScript만 포함하므로 이 과정이 필요하지 않습니다.
</details>
자격 증명은 PARAGENT_USERNAME / PARAGENT_USER_SECRET에서 읽어오며 디스크에 절대 영구 저장되지 않습니다. 전체 명령어 목록: docs/DEVELOPMENT.md.
배치되는 위치
대부분의 브라우저 에이전트 프레임워크는 첫 번째 실행에 최적화되어 있습니다 — 더 나은 계획 수립, 더 나은 DOM 접지(DOM grounding), 더 나은 복구 능력을 갖추도록 합니다. Paragent는 이들을 대체하기보다는 결합되도록 설계되었습니다: 이미 신뢰하는 에이전트의 출력을 기록한 다음 이를 재생합니다. 이것이 목표이며, 오늘 배포되는 것은 아닙니다 — 리코더(recorder)는 #127가 구현될 때까지 임의의 에이전트가 아닌 개발자가 직접 입력한 동작을 캡처합니다.
이는 반복적이며, 브라우저 내에서, 깔끔한 API가 존재하지 않는 작업을 목표로 합니다 — UI가 그저 멈춰만 있다면 스크립트를 작성할 만한 경우들입니다.
프로젝트 현황 — 의존하기 전에 이것을 읽어주세요
Paragent는 시드 이전 단계(pre-seed)이며, 두 주 된 프로젝트이고, 핵심 가설은 아직 증명되지 않았습니다. 우리는 코드와 함께 실패 사례도 공개합니다:
| 트랙 | 질문 | 상태 |
|---|
| Track 1 | 컴파일된 궤적(trajectories)이 사이트 변경에 살아남는가? | 하네스 작업 진행 중 — 아직 게이트 번호 없음 |
| ... | | |
연속적인 수직 FAIL은 이 프로젝트가 현재 아직 존재하지 않는 Track-1 메커니즘 번호에 의존하고 있음을 의미합니다. 이 README에는 보고할 성능 벤치마크가 없기 때문에 아무것도 없습니다. 나중에 여기서 보게 될 어떤 숫자든 게이트 실행(gate run)으로 추적 가능할 것입니다.
연구, 결정 기록, 두 가지 FAIL 메모, 피치 팩(pitch pack), 그리고 기여자 규칙 등 전체 내부 정보는 **docs/README-internal.md**에 원문 그대로 보존되고 최신 상태로 유지됩니다. 만약 당신이 에이전트, 기여자, 후보자 또는 투자자라면 그곳부터 시작하세요. 거기서는 아무것도 완화되지 않았고 숨겨진 것도 없습니다.
문서(Docs)
기여하기(Contributing)
어떤 PR이든 제출되기 전에 npm run ci는 녹색이어야 합니다 — 비밀 스캔(secret-scan), 계약 유효성 검사(contract validation), 린트(lint), 타입 체크(typecheck), 단위 테스트(unit tests)를 거친 후 통합 테스트(integration tests)가 필요합니다. 개인 정보 보호 카나리아(npm run test:canary)는 별도의 병합 차단 작업입니다.
이 레포지토리는 설계상 공개(public by design)입니다 (ADR-0005).
자격 증명(credentials), 쿠키(cookies), 세션 상태(session state), .env 파일, 토큰(tokens), 고객 또는 디자인 파트너 이름, 또는 타사 포털 콘텐츠는 절대 커밋하지 마십시오.
푸시 보호 기능이 활성화된 비밀 스캐닝(Secret scanning)이 적용되어 있으며, 이 검사는 약화될 수 없습니다.
먼저 CONTRIBUTING.md를 읽어보십시오. 규칙 4는 발견 사항을 절대 완화하지 않으며, 이는 모두에게 적용됩니다.
라이선스 (License)
MIT
