nova-agent 0.3.3

Nova Agent - Browser automation agent for Nova QA platform

Nova Agent

Nova QA 플랫폼용 로컬 브라우저 자동화 Agent입니다.

설치

pip install nova-agent

설치 후 Playwright 브라우저를 설치해야 합니다:

playwright install chromium

빠른 시작

1. Agent 등록 (최초 1회)

nova-agent login

브라우저가 열리면:

1. Nova 플랫폼에 로그인
2. Agent 이름 입력 후 등록
3. 발급된 토큰을 터미널에 붙여넣기

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