브라우저 자동화
AI Agent용 안내: 이 페이지의 Markdown 버전은 https://ankole.agentbull.com/ko-KR/docs/browser-automation/index.md, 전체 문서 색인은 https://ankole.agentbull.com/ko-KR/llms.txt에 있습니다.
browser Skill을 사용하면 에이전트가 실제 웹 브라우저 세션을 열어 페이지 이동, 요소 클릭, 입력란 작성, 렌더링된 화면 상태 확인, 스크린샷 캡처, 그리고 라이브 세션 위에서 재현 가능한 Playwright 스크립트 실행까지 수행할 수 있습니다. 이 기능은 기본 내장 도구가 아니라 Agent Library의 Skill로 제공되며, 실행 시 Background Agent Job 안에서 돌아갑니다. 이 문서는 운영자 관점에서 브라우저 자동화 Skill의 구조와 활성화 방법, 그리고 에이전트에 적용되는 실행 제약을 안내합니다.
가장 중요한 원칙은 에이전트 세션당 브라우저 소유자가 오직 하나뿐이며, 그 소유자는 에이전트가 아니라 런타임이라는 점입니다. 에이전트는 워커 이미지에 사전 구성된 ankole-browser CLI를 통해서만 브라우저를 조작해야 합니다. 에이전트가 임의로 Chromium 프로세스를 직접 띄우거나 chromium.connectOverCDP를 호출하면 두 번째 소유자가 생겨 런타임의 세션 복구 경로가 깨지므로 엄격히 금지됩니다.
브라우저 자동화란 무엇인가
Ankole의 브라우저 자동화는 app/library/skills/browser/SKILL.md에 정의된 내장 browser Skill(default_enabled: true)로 제공되며, 백그라운드 Job 런타임 전용(ankole-runtime: background_job)으로 태그되어 있습니다. 에이전트가 이 Skill을 사용하면 메인 대화 turn과 분리된 백그라운드 Job 안에서 런타임이 관리하는 실제 Chromium 세션을 대상으로 작업이 실행됩니다.
모델은 Skill 매니페스트의 description을 읽고 브라우저 사용 여부를 판단합니다. 작업이 클라이언트 측 렌더링 결과, 화면 조작, 스크린샷, 로그인 세션 유지, 또는 반복 가능한 Playwright 워크플로에 의존할 때만 브라우저를 선택하고, 단순 검색이나 본문 텍스트 추출에는 web_search와 web_fetch를 우선 사용합니다.
브라우저를 사용해야 하는 경우
실제 브라우저 구동은 비용이 큰 경로이므로 단순 HTTP 조회만으로 해결되지 않는 상황에만 사용하세요. 대표적인 경우는 다음과 같습니다.
- 렌더링 후 상호작용이 필요한 페이지 — 클라이언트 JavaScript가 실행된 뒤에야 데이터가 나타나거나 클릭, 스크롤, 폼 입력을 거쳐야 원하는 화면에 도달할 수 있는 경우입니다.
- 로그인 세션 유지 — 런타임에 이미 인증된 브라우저 세션이 필요하며 단순 HTTP 요청만으로는 인증 상태를 재현할 수 없는 경우입니다.
- 시각적 스크린샷 확보 — 결과물로 화면 캡처 이미지가 필요하거나 사람이 직접 렌더링 상태를 눈으로 확인해야 하는 경우입니다.
- 재현 가능한 다단계 Playwright 워크플로 — 동일한 다단계 브라우저 조작 절차를 반복해서 실행해야 하는 경우입니다.
단순히 웹 페이지를 검색하거나 정적 본문 텍스트만 읽으면 될 때는 web_search나 web_fetch를 사용하세요. browser Skill 지침에도 명시되어 있듯, 화면 조작이나 로그인 세션, 스크린샷, 브라우저 내부 스크립트 실행이 필요하지 않다면 가벼운 웹 도구를 쓰는 편이 훨씬 빠르고 저렴하며 브라우저 세션 슬롯도 점유하지 않습니다.
활성화 방법
브라우저 자동화는 개별 도구 플래그가 아니라 Skill이므로 Agent Library에서 활성화 여부를 관리합니다. 기본값이 default_enabled: true이므로 별도로 끄지 않는 한 새로 생성한 Agent에서도 바로 사용할 수 있습니다. 제어 계층은 두 단계로 나뉩니다.
- 테넌트 기본값 — 기본 배포 상태(
default_enabled: true)를 유지하면 해당 테넌트의 모든 Agent가 브라우저를 사용할 수 있습니다. - Agent별 재정의 — 브라우저 접근을 막아야 하는 특정 Agent에서만 개별 비활성화하거나, 반대로 테넌트 기본값을 꺼 둔 상태에서 꼭 필요한 Agent에만 선택적으로 켤 수 있습니다.
두 설정 모두 Console API 참조에 안내된 Console의 library-capability 라우트를 통해 제어합니다. 특정 Agent의 library-capabilities를 조회하면 Agent Library의 갱신 규칙에 따라 기본 제공 Skill을 동기화하고 로컬 편집을 보존한 뒤 해당 Agent의 유효 카탈로그 상태를 반환합니다.
runtime이 주입하는 것
에이전트는 브라우저 실행 경로와 연결 구성을 스스로 고르지 않습니다. 브라우저 Job이 시작되기 전에 런타임이 필요한 환경 정보를 모두 준비해 불투명(opaque)한 설정값으로 주입합니다.
- 런타임이 관리하는 브라우저 세션을 가리키는 불투명 라우트(route)
- 에이전트가 바로 조작할 수 있게 준비된 최종 브라우저 세션 정보(browser material)
- CLI가 명령을 주고받는 데몬 소켓 경로
- 스크린샷 및 각종 결과물을 저장할 아티팩트 루트 디렉터리
에이전트는 오직 ankole-browser CLI를 통해서만 이 주입된 자원을 사용합니다. app/agent_computer/src/browser-runtime/index.ts의 BrowserRuntime 클래스가 세션 준비기(materializer), 데몬 슈퍼바이저, 웹 fetch 어댑터를 일괄 관리하므로 브라우저 세션의 전체 수명 주기는 런타임이 책임지고, 에이전트는 CLI 명령만 호출하면 됩니다.
제약: 브라우저 소유자는 하나
다음은 에이전트가 절대 어겨서는 안 되는 핵심 규칙입니다. 브라우저의 유일한 소유자는 런타임이므로 에이전트는 반드시 다음 원칙을 지켜야 합니다.
- 모든 브라우저 작업에 사전 구성된
ankole-browserCLI만 사용해야 합니다(open,snapshot,click,fill,screenshot,batch, 그리고 Playwright 스크립트 실행용run포함). - Chromium 실행 파일을 직접 띄워서는 안 됩니다.
chromium.connectOverCDP를 직접 호출하거나 프로필 이름, 자격 증명, provider 설정, CDP 엔드포인트, 컨트롤 플레인 내부 식별자를 임의로 탐색해서는 안 됩니다.
이렇게 강제하는 이유는 장애 복구와 상태 일관성 때문입니다. 런타임은 데몬 슈퍼바이저와 세션 준비기 및 복구 경로를 직접 통제합니다. 만약 에이전트가 별도로 Chromium을 실행하거나 독자적인 CDP 연결을 열어 두 번째 소유자가 되면 런타임의 관리 범위를 벗어나게 됩니다. 그 상태에서 런타임이 세션을 복구하거나 체크포인트를 남기거나 정리(teardown)하려 할 때 에이전트가 열어 둔 우회 연결을 감지하거나 제어할 수 없어 세션 상태가 깨집니다. 따라서 사전 구성된 ankole-browser CLI만이 유일하게 허용된 진입점입니다.
Agent가 브라우저를 구동하는 방법
ankole-browser CLI는 작업의 복잡도에 맞춰 선택할 수 있는 세 가지 실행 방식을 제공합니다.
- 짧은 단일 CLI 명령 — 화면 구조를 살피거나 한두 단계의 명확한 조작을 수행할 때
open,snapshot -i,click @e2,fill @e4 "value",screenshot등을 개별 실행합니다. batch실행 — 이미 파악된 짧은 연속 동작을 한 번에 처리할 때 따옴표로 감싼 명령 문자열이나argv배열 목록을 표준 입력(stdin)으로 넘겨 개별 명령과 동일한 파서로 일괄 실행합니다.- ESM JavaScript 파일용
run— 반복문, 조건 분기, 다건 데이터 추출, 팝업·다운로드 처리, 정교한 대기 조건, 또는 여러 중간 변수를 메모리에 유지해야 하는 복합 작업에 사용합니다.run은 일반 CLI 명령이 쓰던 것과 동일한 물리적 브라우저 세션에 네이티브 Playwright 객체를 연결해 주므로 단일 스크립트와 개별 CLI 명령이 하나의 세션을 자연스럽게 공유합니다.
특히 run을 실행하더라도 별도의 새 브라우저가 열리지 않고 런타임이 보유한 기존 세션을 그대로 재사용하므로, Playwright 스크립트 내부에서도 단일 소유자 원칙이 온전히 유지됩니다.
운영자가 건드리지 않는 것
ANKOLE_BROWSER_CHROMIUM_EXECUTABLE, ANKOLE_BROWSER_DAEMON_SOCKET, ANKOLE_BROWSER_DAEMON_ENTRY, ANKOLE_BROWSER_RUNNER를 비롯한 브라우저 내부 환경 변수는 워커 이미지와 런타임이 설정합니다. Console의 Environment variables 화면에서 이 예약 변수들을 임의로 덮어쓸 수 없으며, 브라우저 활용 방식 자체를 조정해야 할 때는 Skill 지침을 수정하세요.
다음 단계
- 브라우저 Skill의 카탈로그 구조와 활성화 모델은 Agent Library를 참조하세요.
- 브라우저를 띄우지 않는 가벼운 웹 검색 및 본문 추출 도구는 Web tools를 참조하세요.
- 브라우저 세션이 실행되는 백그라운드 작업 수명 주기는 Background Agent Jobs를 참조하세요.