Nova Agent
Nova QA 플랫폼용 로컬 브라우저 자동화 Agent입니다.
설치
pip install nova-agent
설치 후 Playwright 브라우저를 설치해야 합니다:
playwright install chromium
빠른 시작
1. Agent 등록 (최초 1회)
nova-agent login
브라우저가 열리면:
- Nova 플랫폼에 로그인
- Agent 이름 입력 후 등록
- 발급된 토큰을 터미널에 붙여넣기
2. Agent 실행
nova-agent start
Agent가 Gateway에 연결되어 Job을 대기합니다.
CLI 명령어
| 명령어 | 설명 |
|---|---|
nova-agent login |
Agent 등록 및 토큰 발급 |
nova-agent start |
Agent 실행 |
nova-agent status |
연결 상태 확인 |
nova-agent logout |
토큰 삭제 및 로그아웃 |
nova-agent --help |
도움말 |
옵션
start 명령어 옵션
nova-agent start [OPTIONS]
Options:
--headless / --no-headless 브라우저 헤드리스 모드 (기본: headless)
--gateway-url, -g TEXT Gateway 서버 URL
--pool-size, -p INTEGER 동시 실행 브라우저 수 (기본: 1, 최대: 10)
--verbose, -v 상세 로그 출력
예시
# 헤드리스 모드로 실행 (기본값)
nova-agent start
# 브라우저 UI 표시하며 실행 (디버깅용)
nova-agent start --no-headless
# 커스텀 Gateway URL 사용
nova-agent start --gateway-url wss://gateway.example.com/ws
# 동시에 3개 Job 처리 (브라우저 풀)
nova-agent start --pool-size 3
# 상세 로그 출력
nova-agent start --verbose
설정
토큰 파일
토큰은 ~/.nova-agent/token 에 저장됩니다.
환경 변수
.env 파일 또는 환경 변수로 설정할 수 있습니다:
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
NOVA_GATEWAY_URL |
Gateway WebSocket URL | ws://localhost:9100/ws/agent |
NOVA_HEADLESS |
헤드리스 모드 | true |
NOVA_POOL_SIZE |
브라우저 풀 크기 | 1 |
NOVA_LOG_LEVEL |
로그 레벨 | INFO |
환경 선택: NOVA_ENV=prod로 설정하면 .env.prod 파일을 로드합니다.
아키텍처
┌──────────────────────────────────┐ WebSocket ┌─────────────────┐
│ Nova Agent │◄──────────────────►│ Nova Gateway │
│ (This package) │ │ │
├──────────────────────────────────┤ └────────┬────────┘
│ Browser Pool │ │
│ ┌──────────┐ ┌──────────┐ │ │ WebSocket
│ │ Browser 1│ │ Browser 2│ ... │ ▼
│ │ Job A │ │ Job B │ │ ┌─────────────────┐
│ └──────────┘ └──────────┘ │ │ Nova Runner │
└──────────────────────────────────┘ │ │
└─────────────────┘
브라우저 풀 동작 방식
- Job 할당 시 브라우저 시작, Job 완료 시 즉시 종료
--pool-size로 동시 실행 가능한 브라우저 수 설정- 풀이 가득 차면 다음 Job은 대기열에서 대기
메시지 프로토콜
Agent는 Gateway를 통해 Runner와 통신합니다:
Agent → Gateway
agent_connect: Agent 연결 요청heartbeat: 연결 유지 (30초 간격)job_accepted: Job 수락step_started: Step 시작dom_extracted: DOM 추출 완료script_executed: 스크립트 실행 완료step_completed: Step 완료goal_achieved: 목표 달성 (Runner 판단 후 응답)job_completed: Job 완료error: 에러 발생
Gateway → Agent
registered: 연결 및 인증 성공job_assign: Job 할당extract_dom: DOM 추출 요청execute_script: 스크립트 실행 요청next_step: 다음 Step 진행job_cancel: Job 취소check_goal: 목표 달성 확인 요청
개발
# 개발 환경 설치
pip install -e ".[dev]"
# 테스트 실행
pytest
# 린트
ruff check src/
# 타입 체크
mypy src/
라이선스
MIT License
1 maintainer
Metadata
1 maintainer
Release files for nova-agent 0.3.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| nova_agent-0.3.8.tar.gz | 56.4 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nova_agent-0.3.8-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 109.3 kB
Release files / nova_agent-0.3.8.tar.gz
| Download URL | nova_agent-0.3.8.tar.gz |
|---|---|
| Size | 56.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ab3f90e8fcc05f1664bc5407b9d86c1e10a71da1dfd9945b9c1341c0b8795937
|
|
BLAKE2b-256 checksum How to use checksums |
7a07fd6439ce1bb8f85e42b450c0889095a5cecc7765c400078d84689039e4bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.2
|
Release files / nova_agent-0.3.8-py3-none-any.whl
| Download URL | nova_agent-0.3.8-py3-none-any.whl |
|---|---|
| Size | 52.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4b96bac1d06ef303a1c1f3c56aa1c9d183859ecf692a31c91f8d4fc0f884c629
|
|
BLAKE2b-256 checksum How to use checksums |
1e45745e5ee80c1f1f9aae9490e1d86a72a443d6f553cc559b9244537ed9ccd2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.2
|
Security for nova-agent 0.3.8
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
