nova-agent 0.3.8
Nova Agent - Browser automation agent for Nova QA platform
Requires Python: >=3.11
Keywords: agent, automation, browser, playwright, qa

# Nova Agent

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

## 설치

```bash
pip install nova-agent
```

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

```bash
playwright install chromium
```

## 빠른 시작

### 1. Agent 등록 (최초 1회)

```bash
nova-agent login
```

브라우저가 열리면:
1. Nova 플랫폼에 로그인
2. Agent 이름 입력 후 등록
3. 발급된 토큰을 터미널에 붙여넣기

### 2. Agent 실행

```bash
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 명령어 옵션

```bash
nova-agent start [OPTIONS]

Options:
  --headless / --no-headless  브라우저 헤드리스 모드 (기본: headless)
  --gateway-url, -g TEXT      Gateway 서버 URL
  --pool-size, -p INTEGER     동시 실행 브라우저 수 (기본: 1, 최대: 10)
  --verbose, -v               상세 로그 출력
```

### 예시

```bash
# 헤드리스 모드로 실행 (기본값)
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`: 목표 달성 확인 요청

## 개발

```bash
# 개발 환경 설치
pip install -e ".[dev]"

# 테스트 실행
pytest

# 린트
ruff check src/

# 타입 체크
mypy src/
```

## 라이선스

MIT License