agent-browser | AI를 위한 헤드리스 브라우저 자동화

import { pageMetadata } from "@/lib/page-metadata"

export const metadata = pageMetadata("sessions")

# 세션

다양한 고립된 브라우저 인스턴스를 실행합니다:

```bash
# 서로 다른 세션
agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

# 환경 변수를 통해 설정
AGENT_BROWSER_SESSION=agent1 agent-browser click "#btn"

# 활성 세션 목록 보기
agent-browser session list
# 출력:
# 활성 세션:
# -> default
#    agent1

# 현재 세션 표시
agent-browser session

세션 고립성

각 세션은 다음을 독자적으로 가집니다:

브라우저 인스턴스
쿠키 및 저장소
탐색 기록
인증 상태

지속적인 프로필

기본적으로 브라우저가 닫힐 때 브라우저 상태는 소실됩니다. 다시 시작해도 상태를 유지하려면 --profile 옵션을 사용하세요:

# 지속 가능한 프로필 디렉터리 사용
agent-browser --profile ~/.myapp-profile open myapp.com

# 한 번 로그인한 후 인증된 세션 재사용
agent-browser --profile ~/.myapp-profile open myapp.com/dashboard

# 환경 변수를 통해 설정
AGENT_BROWSER_PROFILE=~/.myapp-profile agent-browser open myapp.com

프로필 디렉터리는 다음을 저장합니다:

쿠키 및 localStorage
IndexedDB 데이터
서비스 워커
브라우저 캐시
로그인 세션

세션 지속성

--session-name을 사용하여 브라우저 재시작 시 쿠키와 localStorage를 자동으로 저장하고 복원할 수 있습니다:

# "twitter" 세션에 대해 상태 자동 저장/로드
agent-browser --session-name twitter open twitter.com

# 한 번 로그인한 후 상태가 자동으로 유지됨
agent-browser --session-name twitter click "#login"

# 환경 변수를 통해 설정
export AGENT_BROWSER_SESSION_NAME=twitter
agent-browser open twitter.com

상태 파일은 ~/.agent-browser/sessions/에 저장되며, 데몬 시작 시 자동으로 로드됩니다.

세션 이름 규칙

세션 이름은 알파벳, 숫자, 하이픈, 밑줄만 포함해야 합니다:

# 유효한 세션 이름
agent-browser --session-name my-project open example.com
agent-browser --session-name test_session_v2 open example.com

# 무효 (거부됨)
agent-browser --session-name "../bad" open example.com    # 경로 탐색
agent-browser --session-name "my session" open example.com # 공백 포함
agent-browser --session-name "foo/bar" open example.com    # 슬래시 포함

상태 암호화

AES-256-GCM 알고리즘을 사용하여 저장된 상태 파일(쿠키, localStorage)을 암호화합니다:

# 256비트 키 생성 (64개의 16진수 문자)
openssl rand -hex 32

# 암호화 키 설정
export AGENT_BROWSER_ENCRYPTION_KEY=<your-64-char-hex-key>

# 이제 상태 파일이 자동으로 암호화됨
agent-browser --session-name secure-session open example.com

# 상태 목록은 암호화 상태 표시
agent-browser state list

상태 자동 만료

오래된 상태 파일을 자동으로 삭제하여 누적을 방지합니다:

# 만료 기간 설정 (기본값: 30일)
export AGENT_BROWSER_STATE_EXPIRE_DAYS=7

# 수동으로 오래된 상태 정리
agent-browser state clean --older-than 7

상태 관리 명령어

# 저장된 모든 상태 목록 보기
agent-browser state list

# 상태 요약 정보 보기 (쿠키, 원본, 도메인)
agent-browser state show my-session-default.json

# 상태 파일 이름 변경
agent-browser state rename old-name new-name

# 특정 세션 이름에 대한 상태 삭제
agent-browser state clear my-session

# 모든 저장된 상태 삭제
agent-browser state clear --all

# 수동 저장/로드 (사용자 지정 경로용)
agent-browser state save ./backup.json
agent-browser state load ./backup.json

인증된 세션

특정 원본에 대해 HTTP 헤더를 설정하려면 --headers를 사용하세요:

# api.example.com에만 적용되는 헤더
agent-browser open api.example.com --headers '{"Authorization": "Bearer <token>"}'

# api.example.com로의 요청에는 인증 헤더 포함
agent-browser snapshot -i --json
agent-browser click @e2

# 다른 도메인으로 이동 - 헤더 미전달
agent-browser open other-site.com

유용한 사례:

로그인 흐름 건너뛰기 - 헤더를 통해 인증
사용자 전환 - 각 세션마다 다른 인증 토큰
API 테스트 - 보호된 엔드포인트 접근
보안 강화 - 헤더는 원본 범위 내에서만 적용, 유출 방지

여러 원본 사용

agent-browser open api.example.com --headers '{"Authorization": "Bearer token1"}'
agent-browser open api.acme.com --headers '{"Authorization": "Bearer token2"}'

글로벌 헤더

모든 도메인에 적용되는 헤더 설정:

agent-browser set headers '{"X-Custom-Header": "value"}'

환경 변수

변수	설명
`AGENT_BROWSER_SESSION`	브라우저 세션 ID (기본값: "default")
`AGENT_BROWSER_SESSION_NAME`	자동 저장/로드 상태 지속성 이름
`AGENT_BROWSER_ENCRYPTION_KEY`	AES-256-GCM 암호화용 64자 16진수 키
`AGENT_BROWSER_STATE_EXPIRE_DAYS`	N일 이상 지난 상태 자동 삭제 (기본값: 30)