agent-browser

개요

agent-browser란?

agent-browser는 inference.sh 플랫폼 위에서 동작하는 AI 에이전트를 위해 설계된 브라우저 자동화 스킬입니다. 내부적으로 Playwright를 사용하며, 단순한 JSON 기반 인터페이스를 제공해 에이전트가 다음과 같은 작업을 수행할 수 있게 합니다.

• 실제 브라우저에서 웹 페이지 열기 및 이동
• 안정적인 @e 참조를 사용한 엘리먼트 상호작용
• 클릭, 입력, 드래그앤드롭, 파일 업로드
• 스크래핑·리서치를 위한 구조화된 데이터 추출
• 세션의 스크린샷 및 비디오 녹화

직접 Playwright 코드를 작성하는 대신, infsh CLI(또는 Bash 명령을 실행할 수 있는 에이전트)를 통해 agent-browser를 호출합니다. 이 스킬이 브라우저 세션을 관리하고, 페이지에 대한 머신 친화적인 설명을 반환하며, 에이전트가 단계별로 상호작용을 주도할 수 있도록 해 줍니다.

agent-browser는 누가 사용하면 좋나요?

agent-browser는 다음과 같은 사용자층을 대상으로 합니다.

• 실제 웹사이트에 AI 에이전트를 연결하려는 개발자
• 재현 가능한 브라우저 워크플로우가 필요한 자동화 엔지니어
• 타겟 웹 스크래핑이나 UI 기반 리서치를 수행하는 데이터·리서치 팀
• inference.sh를 오케스트레이션 레이어로 사용하는 워크플로우 빌더

이미 inference.sh를 사용 중이거나, inference.sh 도입을 고려하면서 브라우저를 에이전트가 접근 가능한 제어 가능한 도구로 쓰고 싶은 경우에 특히 잘 맞습니다.

어떤 문제를 해결하나요?

agent-browser는 흔한 브라우저 자동화 과제를 해결하는 데 도움을 줍니다.

• 로그인, 내비게이션, 폼 제출 등 반복적인 브라우징 플로우 자동화
• 검색 폼, 필터, 페이지네이션처럼 상호작용이 필요한 구조화된 콘텐츠 스크래핑
• 실제 사이트에서 에이전트가 수행하는 “테스트와 유사한” 시나리오 실행
• 리뷰를 위해 자동화된 브라우징 세션의 비디오 녹화

Playwright 스크립트를 직접 다루지 않고, @e 엘리먼트 참조 기반의 상위 수준 액션 세트를 에이전트에 제공하여 여러 단계에 걸쳐 상호작용을 안정적으로 유지하도록 도와줍니다.

언제 agent-browser를 쓰면 좋을까요?

다음과 같은 경우 agent-browser 사용을 고려해 보세요.

• inference.sh를 통해 에이전트를 실행하며, 이들이 웹을 탐색해야 할 때
• Playwright 수준의 신뢰성을 원하지만 Playwright 코드를 직접 작성하고 싶지 않을 때
• 페이지 열기, 엘리먼트와의 상호작용, 결과 읽기로 구성된 플로우를 자동화할 때

다음과 같은 경우에는 적합하지 않을 수 있습니다.

• infsh CLI나 Bash 계열 도구를 사용할 수 없을 때
• 스킬이 제공하는 범위를 넘어서는 고도로 커스텀된 Playwright 기능이 필요할 때
• 실제 브라우저가 필요 없는, API 기반 사용 사례일 때

브라우저 내부 동작이나 특정 프론트엔드 프레임워크를 매우 세밀하게 제어해야 한다면, 직접 Playwright 스크립트를 작성하는 편이 나을 수 있습니다. 일반적인 에이전트 기반 자동화에는 agent-browser가 더 단순하고 상위 수준의 인터페이스를 제공합니다.

사용 방법

사전 준비 사항

agent-browser를 사용하기 전에 다음을 준비하세요.

• Bash 명령을 실행할 수 있는 환경
• 설치된 inference.sh CLI(infsh)
• CLI에서 로그인 가능한 inference.sh 계정

이 스킬의 Quick Start는 infsh CLI 사용을 명시적으로 요구합니다. 다음 저장소의 공식 CLI 설치 안내를 참고할 수 있습니다.

• CLI 설치 문서: https://raw.githubusercontent.com/inference-sh/skills/refs/heads/main/cli-install.md

infsh를 설치 및 설정한 후에는 터미널이나, infsh 명령을 실행할 수 있는 에이전트 도구에서 agent-browser 스킬을 호출할 수 있습니다.

설치 및 스킬 활성화

agent-browser는 inferen-sh/skills 저장소의 일부로 배포됩니다. 대부분의 inference.sh 기반 환경에서는 별도의 npm 패키지를 설치할 필요가 없으며, 스킬이 사용 가능한지만 확인한 뒤 infsh를 통해 호출하면 됩니다.

일반적인 설정 단계는 다음과 같습니다.

1. inference.sh CLI 설치
   • 저장소의 cli-install.md를 따라 설치합니다.
2. 인증
   • 다음을 실행합니다.

     infsh login
     

   • 안내에 따라 inference.sh 계정으로 인증합니다.
3. 스킬 사용 가능 여부 확인
   • inferen-sh/skills 저장소의 tools/utilities/agent-browser 경로 아래에 있는 agent-browser 앱/스킬에 inference.sh 환경이 접근할 수 있는지 확인합니다.

npx skills add를 지원하는 더 넓은 “skills” 에코시스템과 통합하는 경우, 이 저장소를 소스로 연결할 수도 있습니다. 다만 agent-browser의 정석적인 사용 흐름은 infsh app run을 통한 실행입니다.

핵심 브라우저 자동화 워크플로우

스킬 문서에서는 일관된 4단계 패턴을 설명합니다.

1. Open – 브라우저 세션을 시작하고 지정한 URL로 이동합니다.
2. Interact – 반환된 @e 엘리먼트 참조를 사용해 클릭, 입력, 드래그, 업로드 등의 작업을 수행합니다.
3. Re-snapshot – 내비게이션 또는 DOM 변경 후 새로운 @e 참조를 얻기 위해 스냅샷을 다시 요청합니다.
4. Close – 세션을 종료하고, 설정된 경우 비디오 녹화 파일을 가져옵니다.

이 패턴을 통해 에이전트는 페이지 상태에 대한 “멘탈 모델”을 유지할 수 있습니다. 각 호출은 JSON 입력을 받고 구조화된 JSON 출력을 반환하며, 이를 에이전트의 추론 루프에 다시 공급하는 구조입니다.

빠른 시작 예제

단일 페이지를 열어 agent-browser 동작을 확인하려면, 저장소의 Quick Start 패턴을 따라 실행해 보세요.

infsh login

# 페이지를 열고 상호작용 가능한 엘리먼트 목록을 가져오기
infsh app run agent-browser --function open --input '{"url": "https://example.com"}' --session new

이 명령은 다음을 수행합니다.

• --function open은 agent-browser에 지정한 URL로 새 브라우저 페이지를 열라고 지시합니다.
• --session new는 이후 액션에서 동일한 브라우저 상태를 재사용할 수 있도록 새 세션을 생성합니다.
• 스킬은 보통 엘리먼트 설명과 @e 참조를 포함한 JSON을 반환하며, 에이전트는 후속 interact 호출에서 이를 사용할 수 있습니다.

@e 엘리먼트 참조 다루기

agent-browser의 핵심 기능 중 하나는 @e 참조 사용입니다. CSS selector나 XPath를 요구하는 대신, 이 스킬은 사람이 이해할 수 있는 설명과 함께 @e:button-1 같은 핸들(구체적인 형식은 구현에 따라 다를 수 있습니다)을 반환합니다.

에이전트는 다음과 같이 동작합니다.

1. 사용 가능한 엘리먼트 목록과 각 설명을 읽습니다.
2. 예를 들어 “Search” 라벨이 붙은 버튼에 해당하는 적절한 @e 참조를 선택합니다.
3. 선택한 @e 참조를 사용해 클릭, 입력 등 상호작용 함수를 호출합니다.

이 설계는 에이전트가 저수준 DOM 세부사항이 아닌 설명을 기반으로 추론할 수 있도록 최적화되어 있습니다. 또한, 기저 selector가 변경되더라도 설명이 해석 가능하게 유지되는 한 상호작용을 견고하게 유지하는 데 도움이 됩니다.

예제: open, click, resnapshot

전형적인 다단계 플로우는 다음과 같은 형태를 띱니다(패턴 예시이며, 실제 함수 이름은 스킬 정의를 기준으로 조정하세요).

# 1. 세션을 시작하고 페이지 열기
OPEN_RESULT=$(infsh app run agent-browser \
  --function open \
  --session new \
  --input '{"url": "https://example.com"}')

# 2. 에이전트 로직에서 OPEN_RESULT를 사용해 @e 참조(@e:search-button 등)를 선택
# 3. 해당 엘리먼트와 상호작용
INTERACT_RESULT=$(infsh app run agent-browser \
  --function interact \
  --session "$INF_SH_SESSION" \
  --input '{"action": "click", "element": "@e:search-button"}')

# 4. 클릭 후 DOM 변경을 반영하기 위해 재스냅샷
SNAPSHOT_RESULT=$(infsh app run agent-browser \
  --function snapshot \
  --session "$INF_SH_SESSION" \
  --input '{}')

open 이외 함수들의 이름은 스킬 버전에 따라 달라질 수 있으므로, 항상 최신 SKILL.md 및 tools/utilities/agent-browser 내 관련 문서를 확인해 함수 시그니처와 입력 스키마를 검증하세요.

스크린샷 및 비디오 녹화

agent-browser는 브라우징 세션의 시각 자료를 캡처할 수 있습니다.

• 스크린샷 – 에이전트 동작 디버깅이나 시각적 확인 기록에 유용합니다.
• 비디오 – 녹화가 활성화된 상태에서 세션을 종료하면, 전체 자동화 플로우를 담은 비디오 파일을 반환하거나 링크로 제공할 수 있습니다.

이 기능은 스킬의 입력 옵션을 통해 설정합니다. 녹화를 활성화하고 결과물을 가져오는 방법에 대한 자세한 내용은 저장소의 SKILL.md 정의와 tools/utilities/agent-browser 아래 추가 문서를 참고하세요.

에이전트·워크플로우 통합 팁

agent-browser를 자동화·리서치 워크플로우에 최적화해 활용하려면 다음을 고려하세요.

• --session ID 유지: 여러 액션이 동일 브라우저에서 실행되도록, 호출 간에 세션 식별자를 에이전트가 저장·재사용해야 합니다.
• JSON 출력 안정적으로 파싱: 에이전트 런타임에서 JSON 파싱을 견고하게 구현하세요. 엘리먼트 목록과 메타데이터가 풍부할 수 있습니다.
• 필요 시 상호작용 속도 조절: 페이지가 느리거나 동적이라면, 스킬 설정이 허용하는 범위에서 에이전트가 단계 사이에 대기 시간을 두거나 엘리먼트가 나타날 때까지 기다리도록 하세요.
• 주요 액션 로깅: 에이전트 브라우징 동작을 감사·디버깅해야 할 경우, open, interact, close 호출을 로깅해 두는 것이 좋습니다.

자주 묻는 질문(FAQ)

agent-browser, inference.sh, Playwright는 어떤 관계인가요?

agent-browser는 inference.sh 에코시스템 내부에서 실행되는 스킬입니다. infsh app run으로 호출하면, 내부적으로 Playwright를 브라우저 자동화 엔진으로 사용합니다. 사용자는 Playwright를 직접 호출하지 않고, 더 상위 수준의 스킬 함수와 @e 엘리먼트 참조를 사용해 작업합니다.

agent-browser는 어떻게 설치하나요?

agent-browser를 독립 실행형 바이너리나 npm 패키지로 따로 설치할 필요는 없습니다. 대신 다음과 같이 진행합니다.

1. 공식 cli-install.md 안내에 따라 inference.sh CLI(infsh)를 설치합니다.
2. infsh login으로 로그인합니다.
3. inferen-sh/skills 저장소(경로: tools/utilities/agent-browser)에서 agent-browser 스킬에 환경이 접근 가능한지 확인합니다.

이후 바로 infsh app run agent-browser를 통해 스킬을 실행할 수 있습니다.

agent-browser를 사용하려면 프로그래밍 지식이 꼭 필요할까요?

기본적인 커맨드라인 사용 능력과 JSON에 대한 이해는 강하게 권장됩니다. Playwright 스크립트를 직접 작성할 필요는 없지만, 다음에 익숙해야 합니다.

• infsh 명령 실행
• --input 인자로 JSON 전달
• 에이전트나 스크립트에서 JSON 출력 파싱

조건 분기, 반복, 에러 처리 등 고급 워크플로우를 구성하려면 일반적인 스크립팅 또는 프로그래밍 지식이 도움이 됩니다.

inference.sh 밖에서 agent-browser를 사용할 수 있나요?

이 스킬은 inference.sh용으로 설계되었으며, “Browser automation for AI agents via inference.sh”라는 설명 그대로 infsh CLI를 통해 실행하는 방식이 공식적으로 지원·문서화된 사용법입니다. 독립형 라이브러리가 필요하다면, 사용하는 언어에서 Playwright를 직접 사용하는 편이 더 적합할 수 있습니다.

agent-browser는 대규모 웹 스크래핑에 적합한가요?

agent-browser는 특히 상호작용이나 JavaScript 렌더링이 필요한 페이지를 대상으로 한 타겟 스크래핑에 유용합니다. 다만, 매우 대규모 스크래핑을 계획한다면 다음을 고려해야 합니다.

• inference.sh 계정 제한 및 요금 정책
• 대상 사이트의 이용 약관 및 robots.txt 준수
• 성능, 동시성, 레이트 리밋 전략

에이전트 내부의 소규모·워크플로우 특화 스크래핑에는 agent-browser가 좋은 선택입니다. 다양한 사이트를 대량으로 크롤링해야 한다면, 별도의 전용 스크래핑 스택을 고려하는 것이 더 적합할 수 있습니다.

세션 관리는 어떻게 동작하나요?

세션 관리는 infsh app run 호출 시 --session 플래그를 통해 제어합니다. 일반적인 패턴은 다음과 같습니다.

• 처음 open을 호출할 때 --session new 사용
• 이후 interact, snapshot 호출에서 같은 세션 ID 재사용
• 적절한 close 함수를 호출해 세션을 종료하고, 필요한 경우 비디오를 함께 수집

세션 관리와 관련된 구체적인 옵션·출력 형식은 항상 최신 SKILL.md를 참조해 확인하세요.

함수 및 입력 스펙 전체는 어디에서 확인할 수 있나요?

agent-browser에 대한 공식 레퍼런스는 다음 저장소에 있습니다.

• inferen-sh/skills 저장소 루트의 SKILL.md
• 구현 세부사항, 예제, 추가 문서를 담은 tools/utilities/agent-browser 디렉터리

이 파일들을 열어 현재 제공되는 함수 목록, 예상 JSON 입력, 출력 형식을 확인한 뒤, 에이전트나 스크립트를 해당 정의에 맞춰 설계하세요.