Browser Use Python으로 읽기 전용 에이전트 만들기

Python에서 Browser Use 에이전트를 만들려면 Agent에 모델, 새 Browser 세션, 답을 확인할 수 있는 작업을 전달합니다. 이 예제는 로컬 HTML 페이지에서 제목과 코드를 읽습니다. Pydantic으로 형식을 검사하고 Python 코드에서 두 값을 대조합니다.

이전 버전에서 모델이 만든 동작이 검증을 통과하지 못했다는 GitHub 제보가 있습니다. 아래 코드는 Python 빠른 시작과 출력 형식 문서를 바탕으로 작성했습니다. 공식 문서와 인터페이스를 대조했으며, 예제를 처음부터 끝까지 실행하지는 않았습니다.

핵심 정리

• 세션과 작업, 검증을 앱에서 관리해야 한다면 Browser Use Python 라이브러리를 사용합니다.

• 첫 작업은 로컬 HTML과 계정에 로그인하지 않은 세션으로 시작합니다.

• 브라우저와 모델의 실행 위치는 별개입니다. Chromium이 로컬에 있어도 ChatBrowserUse는 호스팅된 모델을 호출합니다.

• history.is_successful()은 에이전트의 자체 판단입니다. 실제 값은 별도로 확인합니다.

• 첫 테스트 페이지에는 폼, 업로드 기능, 계정을 넣지 않습니다.

브라우저와 모델의 실행 위치 선택하기

모델은 동작을 고르고 브라우저는 실행합니다. Python은 둘을 연결합니다. 이 역할을 구분하면 브라우저 에이전트, 고정 Playwright 스크립트, 웹 검색 중 어떤 방식이 필요한지 판단하기 쉽습니다.

예제는 첫 번째 구성을 사용합니다. 빠른 시작에 따라 BROWSER_USE_API_KEY를 환경 변수나 로컬 .env에 넣습니다. 키를 저장소에 올리지 마세요. uv가 설치된 환경의 새 프로젝트 디렉터리에서 다음 명령을 실행합니다.

uv init --python 3.12
uv add browser-use
uvx browser-use install

마지막 명령은 Chromium을 준비합니다. 같은 환경을 재현하려면 잠금 파일을 보관합니다. 지원 모델 문서에는 ChatOllama도 나옵니다. 모델을 바꾸면 같은 페이지와 기대값을 유지하고, 브라우저 동작과 최종 출력을 모두 확인합니다. Cloud 빠른 시작에는 별도의 인증 및 세션 설정이 있습니다.

한 Reddit QA 게시글은 고객 데이터를 내부에 두기 위해 자체 호스팅 모델을 찾습니다. 같은 요건이라면 로컬 모델을 선택하세요. 이 예제에서는 가상의 테스트 데이터만 모델로 보냅니다.

정답이 정해진 테스트 페이지 만들기

HTML을 fixture/index.html에 저장합니다. 페이지에는 테스트용 텍스트와 가상의 코드만 있습니다. 다른 터미널에서 서버를 실행합니다. 서버는 fixture 디렉터리만 제공합니다.

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Inventory fixture</title>
<main>
  <h1>Inventory Check</h1>
  <p>Reference code: BU-741</p>
</main>
</html>

uv run python -m http.server 8765 --bind 127.0.0.1 --directory fixture

127.0.0.1은 브라우저가 실행 중인 컴퓨터를 가리킵니다. 원격 브라우저는 자기 호스트의 로컬 주소를 엽니다. 이 예제에서는 서버와 브라우저를 같은 컴퓨터에서 실행합니다. 접속 여부를 확인할 때는 페이지를 먼저 직접 열어 보세요.

에이전트를 실행하고 두 필드 확인하기

프로젝트 루트에 check_page.py를 저장합니다. 브라우저 매개변수에서 허용 도메인 설정을, Agent 매개변수에서 출력 스키마를 확인할 수 있습니다. 작업 지시에는 URL을 넣고 기대값은 검증 코드에만 둡니다.

import asyncio
from tempfile import TemporaryDirectory

from browser_use import Agent, Browser, ChatBrowserUse
from pydantic import BaseModel

URL = "http://127.0.0.1:8765/"


class PageCheck(BaseModel):
    heading: str
    reference: str


async def main():
    with TemporaryDirectory(prefix="browser-use-fixture-") as profile:
        browser = Browser(
            headless=True,
            user_data_dir=profile,
            allowed_domains=["127.0.0.1"],
            accept_downloads=False,
        )
        try:
            agent = Agent(
                task=(
                    f"Open {URL} and read its visible heading and reference code. "
                    "Return only those two values. Do not interact with any form."
                ),
                browser=browser,
                llm=ChatBrowserUse(),
                output_model_schema=PageCheck,
            )
            history = await agent.run(max_steps=5)
            result = history.structured_output
            expected = PageCheck(heading="Inventory Check", reference="BU-741")
            if result != expected:
                raise RuntimeError("The output does not match the fixture.")
            print(result.model_dump_json())
        finally:
            await browser.stop()


if __name__ == "__main__":
    asyncio.run(main())

uv run python check_page.py

기대하는 제목은 Inventory Check, 코드는 BU-741입니다. 값이 다르다는 오류가 나오면 단계 제한을 늘리기 전에 기록을 확인합니다. 단계만 늘리면 같은 실패를 반복할 수 있습니다.

방문, 출력, 부수 효과를 따로 확인하기

서버 로그에서 에이전트가 실행되는 동안 / 요청이 들어왔는지 확인합니다. 이어서 history.urls(), history.errors(), 터미널 출력을 대조합니다. 출력 형식 문서는 실행 종료, 에이전트의 성공 판단, 외부에서 확인한 결과를 구분합니다.

테스트 세션과 평소 쓰는 프로필을 분리합니다. 기존 브라우저에 연결하면 에이전트가 접근하는 세션과 쿠키가 달라집니다. 허용 목록은 탐색 범위를 제한합니다. 실제 시스템에서는 테스트 계정을 사용하고 서버에서 읽기 권한을 적용하세요. 자세한 내용은 브라우저 에이전트 보안 위험에서 볼 수 있습니다.

처음 실패한 단계부터 확인하기

다른 원격 CDP 제보에서는 브라우저 프로토콜 호출이 멈췄습니다. 동작 검증과는 다른 단계이며 두 제보 모두 특정 버전에 해당합니다. 현재 실행에서 나온 오류를 기준으로 조사하세요.

레코드 생성이나 메시지 발송이 가능한 작업이 시간 초과되면 재시도 전에 대상 시스템을 확인합니다. 읽기 전용 테스트 페이지는 다시 방문한 뒤 로그를 대조할 수 있습니다.

Python 통합이 필요한 경우

후속 코드가 형식이 정해진 필드를 받아 검사해야 한다면 Python 통합이 적합합니다. URL과 셀렉터, 순서가 고정된 작업에는 브라우저 스크립트를 쓸 수 있습니다. 페이지 문구를 한 번 확인하는 일이라면 직접 열어 보는 것으로 충분합니다. Tabbit과 Browser Use 비교와 에이전트형 브라우저 가이드에서 브라우저 인터페이스와 코드 통합의 차이를 확인할 수 있습니다.

첫 실행은 서버에 요청이 도착하고 두 값이 일치하는지까지 확인하세요. 이후 브라우저, 모델, 대상 페이지를 하나씩 바꿔 같은 검증을 반복합니다.

Secholar.L

Tabbit 그로스 & 콘텐츠

Secholar.L은 AI 브라우저와 에이전트 워크플로우에 대한 실용적인 가이드를 작성하며, 실제 조사와 검증 가능한 출처를 바탕으로 도구를 비교합니다.