브라우저 사용 도구

"browser use tool"(브라우저 사용 도구)은 Claude가 여러분의 애플리케이션이 실행하는 브라우저에서 웹페이지를 탐색하고, 읽고, 상호작용할 수 있게 합니다. 이 도구는 페이지의 구조(접근성 트리, 요소, 폼, 탭)와 픽셀(스크린샷 및 뷰포트 좌표) 양쪽을 통해 페이지를 다루는 반면, 컴퓨터 사용 도구는 스크린샷과 좌표만으로 전체 데스크톱을 다룹니다. 이 도구는 Anthropic이 정의한 클라이언트 도구 세트입니다. tools 배열에 browser_toolset_20260801 항목 하나를 추가하면 Claude에게 기본적으로 navigate, read_page, left_click, screenshot 등 27개의 멤버 도구가 제공되며, 활성화하면 네 개(javascript_exec, file_upload, read_console, read_network)가 추가로 제공됩니다. 여러분의 애플리케이션은 모든 호출을 자체 브라우저 자동화에 대해 실행하며, Anthropic 측에서는 아무것도 실행되지 않습니다. 현재 Claude Managed Agents에서는 사용할 수 없습니다. 이 페이지에서는 Messages API를 호출하는 에이전트 루프를 "여러분의 애플리케이션"이라고 하고, 그중 브라우저를 구동하고 도구 결과를 생성하는 부분을 "여러분의 실행기(executor)"라고 합니다.

작업이 웹페이지 안에 머무를 때는 컴퓨터 사용 대신 브라우저 사용을 선택하세요. Claude는 페이지의 구조를 읽고, 좌표뿐 아니라 참조로도 요소에 대해 동작하고, 폼 값을 직접 설정하고, 여러 탭에 걸쳐 작업할 수 있으며, 여러분은 데스크톱을 실행할 필요가 없습니다. Claude가 여러분이 지정한 페이지를 읽기만 하면 되거나 웹에서 출처를 찾기만 하면 되는 경우에는 웹 가져오기 도구와 웹 검색 도구가 훨씬 가볍습니다. 이들은 운영할 브라우저 없이 API가 대신 실행해 주는 서버 도구이기 때문입니다. 페이지가 JavaScript로 콘텐츠를 구성하거나 작업이 페이지를 읽는 것에 그치지 않고 페이지에 대해 동작하는 것을 의미할 때는 대신 브라우저 사용을 선택하세요.

브라우저 사용에서 Claude는 실제 웹페이지를 읽고 그에 대해 동작하므로, 페이지가 제공하는 모든 것은 신뢰할 수 없는 입력이며 Claude가 취하는 동작은 실제 영향을 미칠 수 있습니다. 배포하기 전에 보안 고려 사항을 참조하세요.



빠른 시작

브라우저 사용 도구는 베타 헤더 없이 Claude API에서 사용할 수 있습니다. Messages API 요청의 tools 배열에 name 없이 browser_toolset_20260801 타입의 항목 하나를 추가하세요.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    tools=[{"type": "browser_toolset_20260801"}],
    messages=[
        {
            "role": "user",
            "content": "Open example.com/docs and tell me how to get started.",
        }
    ],
)
print(response)

Claude의 첫 번째 응답은 stop_reason: "tool_use"로 끝나며 하나 이상의 멤버 tool_use 블록을 담고 있습니다. 각 블록은 name에 멤버 도구 이름을 지정하고 "toolset_name": "browser"를 담고 있습니다.

{
  "id": "msg_01HCDu4XSTLzTAcodEQ58vDo",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5",
  "content": [
    {
      "type": "text",
      "text": "I'll open the documentation and read the page to find the getting-started instructions."
    },
    {
      "type": "tool_use",
      "id": "toolu_01NRLabsLyVHZPKxbKvkfSMn",
      "name": "navigate",
      "toolset_name": "browser",
      "input": { "url": "https://example.com/docs" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01UvHU5cDyTZ2vXKf5wCkPqR",
      "name": "read_page",
      "toolset_name": "browser",
      "input": { "filter": "interactive" }
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null
}

여러분의 실행기는 navigate를 실행한 다음 read_page를 실행하고, 여러분의 애플리케이션은 다음 요청에서 블록당 하나의 tool_result를 반환하며 각각에 toolset_name을 그대로 되돌려 줍니다. navigate 결과는 로드한 탭을 browser_state 블록으로 보고하고, read_page 결과는 모든 요소가 참조를 담고 있는 텍스트입니다.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01NRLabsLyVHZPKxbKvkfSMn",
      "toolset_name": "browser",
      "content": [
        { "type": "text", "text": "Navigated to https://example.com/docs" },
        {
          "type": "browser_state",
          "tabs": [
            {
              "tab_id": "tab-1",
              "title": "Documentation",
              "url": "https://example.com/docs",
              "active": true
            }
          ]
        }
      ]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01UvHU5cDyTZ2vXKf5wCkPqR",
      "toolset_name": "browser",
      "content": [
        {
          "type": "text",
          "text": "link \"Documentation\" [ref_1]\nlink \"Getting started\" [ref_2]\ntextbox \"Search docs\" [ref_3]\nbutton \"Search\" [ref_4]\nlink \"Pricing\" [ref_5]"
        }
      ]
    }
  ]
}

이제 Claude는 동작에 사용할 수 있는 참조를 보유하고 있으므로, 다음 턴에서 먼저 스크린샷에서 링크를 찾을 필요 없이 ref_2를 클릭하여 시작하기 페이지를 열 수 있습니다.



브라우저 사용의 작동 방식

브라우저 사용은 에이전트 루프로 실행됩니다. Claude가 멤버 도구 호출을 반환하고, 여러분의 실행기가 이를 브라우저에 대해 실행하며, Claude가 텍스트로 답할 때까지 여러분이 결과를 반환합니다.

다음은 해당 루프의 도구 호출 단계를 두 부분으로 나눈 골격입니다. 먼저, 스텁 멤버 핸들러가 여러분의 브라우저 자동화를 대신합니다. 다섯 개의 멤버(navigate, read_page, left_click, type, screenshot)는 결과 콘텐츠가 되는 텍스트를, screenshot의 경우 이미지 블록을 반환하며, 디스패처는 구현하지 않은 멤버에 대해 오류를 발생시킵니다.

# 플레이스홀더 이미지 데이터; 실제 실행기는 뷰포트를 캡처하여 PNG 바이트를 반환합니다
PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="


def navigate(url):
    return f"navigated to {url}"


def read_page():
    return 'link "Docs" [ref_1]\nbutton "Search" [ref_2]'


def click(target):
    # 대상은 read_page 또는 find의 요소 참조이거나 뷰포트 좌표입니다
    if target["type"] == "ref":
        return f"clicked {target['ref']}"
    return f"clicked at ({target['x']}, {target['y']})"


def type_text(text):
    return f"typed: {text}"


def capture_screenshot() -> list[ImageBlockParam]:
    # screenshot은 텍스트 대신 이미지 블록으로 응답합니다: 결과 콘텐츠 목록을 반환합니다
    return [
        {
            "type": "image",
            "source": {"type": "base64", "media_type": "image/png", "data": PLACEHOLDER_PNG},
        }
    ]


def handle_browser_action(name, tool_input):
    if name == "navigate":
        return navigate(tool_input["url"])
    elif name == "read_page":
        return read_page()
    elif name == "left_click":
        return click(tool_input["target"])
    elif name == "type":
        return type_text(tool_input["text"])
    elif name == "screenshot":
        return capture_screenshot()
    # 필요에 따라 다른 액션을 처리합니다
    raise ValueError(f"Unknown or unimplemented member: {name}")

두 번째 부분은 배치를 순서대로 실행하고, 각 블록을 해당 핸들러로 디스패치하고, 모든 결과에 toolset_name을 그대로 되돌려 주며, 배치 동작의 중단 규칙을 적용하여 핸들러 오류를 오류 결과로 변환합니다. 이를 호출하는 샘플링 루프는 tools에 브라우저 도구 세트를 넣은 상태로 에이전트 루프 이해하기에 나와 있는 것과 같습니다.

NOT_EXECUTED = "Not executed: an earlier action in this turn failed."


def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
    """
    Run the browser actions in Claude's response in order and answer each
    one. After the first failure the rest are skipped, because Claude planned
    them assuming the earlier actions succeeded.
    """
    tool_results: list[ToolResultBlockParam] = []
    failed = False
    for block in response.content:
        # 브라우저 도구 세트만 선언되어 있습니다; 다른 도구를 추가하는 경우 여기로 라우팅하세요
        if block.type != "tool_use" or block.toolset_name != "browser":
            continue
        result: ToolResultBlockParam = {
            "type": "tool_result",
            "tool_use_id": block.id,
            "toolset_name": "browser",
        }
        if failed:
            result["content"] = NOT_EXECUTED
            result["is_error"] = True
        else:
            try:
                # 문자열 또는 콘텐츠 블록 목록; 실제 실행기는 또한
                # 탐색 및 탭 관리 결과에 browser_state 블록을 추가합니다
                result["content"] = handle_browser_action(block.name, block.input)
            except Exception as err:
                result["content"] = f"Error: {err}"
                result["is_error"] = True
                failed = True
        tool_results.append(result)
    return tool_results

각 블록을 name만이 아니라 (toolset_name, name) 쌍으로 디스패치하세요. 같은 요청의 커스텀 도구가 멤버의 이름을 공유할 수 있기 때문입니다. 클라이언트 도구 세트에서 두 도구 세트가 공유하는 이 계약의 부분을 설명합니다. Claude가 여러분의 실행기가 구현하지 않은 멤버나 여러분이 비활성화한 멤버를 지정하면, 해당 블록을 버리지 말고 오류 결과로 응답하세요.

응답을 스트리밍할 때 각 멤버의 input은 조각이 아니라 하나의 완전한 input_json_delta로 도착하므로, 배치를 실행하기 전에 턴이 끝날 때까지 기다리세요.



배치 동작

여러 멤버 호출이 있는 턴은 배치 동작입니다. 호출을 나타나는 순서대로 실행하고, 첫 번째 실패에서 멈추고, 이후 모든 호출에 is_error: true와 정확히 Not executed: an earlier action in this turn failed.라는 텍스트로 응답하세요. 배치는 병렬 도구 사용과 동일한 응답 형태를 사용하며, 차이점은 블록을 동시에 실행하는 것이 아니라 순서대로 실행한다는 것입니다. 여기서 Claude는 앞서 찾은 검색 상자를 클릭하고, 쿼리를 입력하고, Enter를 누르는 것을 한 턴에 수행합니다.

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
      "name": "left_click",
      "toolset_name": "browser",
      "input": { "target": { "type": "ref", "ref": "ref_3" } }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Ez4kLb1nQ2vXo8sJ9pWm3c",
      "name": "type",
      "toolset_name": "browser",
      "input": { "text": "install" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01FkP8rTz6uYh2mNq4LsXw7v",
      "name": "key",
      "toolset_name": "browser",
      "input": { "text": "Enter" }
    }
  ]
}

여러분의 애플리케이션은 하나의 user 메시지에 세 개의 tool_result 블록을 반환하며, 각각 toolset_name과 Clicked element ref_3.과 같은 짧은 텍스트 확인 응답을 담습니다. Enter를 누르면 결과 페이지가 로드되므로 key 결과는 탭의 업데이트된 URL이 담긴 browser_state 블록도 담습니다(다른 결과의 탭 컨텍스트). 만약 클릭이 실패했다면, 그 결과는 여러분의 오류 텍스트를 담고 나머지 두 결과는 실행기에서 오류 반환에 나와 있는 것처럼 중단 텍스트를 담게 됩니다.

모든 호출 후에 스크린샷을 반환할 필요는 없습니다. Claude는 일반적으로 관찰 호출(screenshot, read_page, 또는 get_page_text)로 배치를 끝내며, 여러분의 애플리케이션도 왕복을 절약하기 위해 새 스크린샷이나 접근성 트리 같은 자체 관찰을 배치의 마지막 결과에 추가 콘텐츠 블록으로 첨부할 수 있습니다. 탭 관리 결과는 정확히 하나의 browser_state 블록이어야 하므로, 탭 관리 호출이 아닌 마지막 결과에 첨부하세요.

여러분의 실행기가 왕복당 하나의 호출만 실행할 수 있다면, tool_choice에서 disable_parallel_tool_use를 true로 설정하세요. 그러면 Claude는 더 많은 왕복을 대가로 턴당 최대 하나의 멤버 호출을 반환합니다(병렬 도구 사용 비활성화). 컴퓨터 사용 도구의 배치 동작에 있는 나머지 계약은 다음 user 메시지에서 모든 tool_use에 대해 하나의 tool_result를 반환하는 것을 포함하여 그대로 적용되지만, 두 가지는 예외입니다. 중단 텍스트와 성공한 결과의 content가 담는 내용입니다. 결과 콘텐츠는 대신 이 페이지의 멤버 도구를 따릅니다. new_tab, switch_tab, close_tab, 또는 list_tabs 결과는 텍스트나 이미지 없이 정확히 하나의 browser_state 블록이며(탭 관리 결과), 다른 멤버의 결과는 텍스트나 이미지에 browser_state 블록을 추가할 수 있습니다(다른 결과의 탭 컨텍스트). 배치 내부의 캐시 중단점이 어디에서 효력을 갖는지는 컴퓨터 사용 도구의 도구 매개변수의 cache_control 행에 설명되어 있습니다.



대상과 좌표

위치에 대해 동작하는 멤버 도구는 target 객체를 받으며, 이는 뷰포트 픽셀 좌표이거나 read_page 또는 find가 반환한 요소에 대한 참조입니다. 멤버 도구 표에서는 두 형태 중 어느 것이든 받는 매개변수를 Target으로 표기합니다.

좌표는 뷰포트 픽셀입니다. 즉, 렌더링된 페이지의 왼쪽 상단을 원점으로 하는 전체 뷰포트 screenshot의 픽셀 공간이며, 주변 데스크톱이나 창 프레임은 없습니다. 도구 세트는 디스플레이 크기를 선언하지 않으며 Claude는 여러분이 반환하는 스크린샷에서 뷰포트 크기를 추론하므로, 스크린샷을 일관된 하나의 크기로 유지하세요. zoom은 프레임을 변경하지 않으므로, 그 region과 Claude가 확대된 이미지를 본 후 내보내는 모든 좌표는 여전히 전체 뷰포트 픽셀입니다.

스크린샷은 이미지 제한에 맞아야 합니다. API는 도구 세트 이미지를 축소하지 않습니다. 모델의 이미지 크기 제한을 초과하거나, 요청에 20개를 초과하는 이미지가 담기면 적용되는 더 엄격한 이미지당 제한을 초과하는 스크린샷이나 확대 이미지는 거부됩니다. 반환하기 전에 크기를 조정하고, 디스패치하기 전에 Claude의 좌표를 여러분의 배율의 역수로 다시 확대하세요(이미지 제한에 맞게 스크린샷 크기 조정).

요소 참조는 read_page와 find에서 나옵니다. 빠른 시작 결과에서처럼 출력의 각 요소는 [ref_2]와 같은 태그를 담고 있습니다.

link "Documentation" [ref_1]
link "Getting started" [ref_2]
textbox "Search docs" [ref_3]
button "Search" [ref_4]
link "Pricing" [ref_5]

Claude는 이후의 클릭, hover, scroll_to, form_input, 또는 file_upload 호출에서 {"type": "ref", "ref": "ref_2"} 대상으로, 또는 하위 트리를 읽기 위해 read_page의 ref 매개변수로 참조를 다시 전달합니다. 여러분의 실행기는 참조를 할당하고, 각 참조에서 기저 노드(접근성 노드 ID, 저장된 선택자, 또는 이에 상응하는 것)로의 매핑을 유지하며, 참조가 돌아오면 해당 노드에 대해 동작합니다.

참조는 이를 생성한 탭으로 범위가 한정되며 해당 탭이 탐색하거나 DOM이 실질적으로 변경될 때까지 유효합니다. API는 오래되었거나 알 수 없는 참조를 감지할 수 없으므로, Claude가 여러분의 실행기가 더 이상 인식하지 못하는 참조를 전달하면 Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references.와 같은 오류 결과를 반환하세요. 그러면 Claude는 페이지를 다시 읽습니다. 탭이 탐색하기 전까지는 해당 탭에 대해 이미 배포한 참조의 번호를 다시 매기지 마세요. 그렇게 하면 Claude가 여전히 보유하고 있는 참조가 조용히 무효화되기 때문입니다.

Claude는 두 가지 대상 지정 방식을 모두 사용하며 페이지가 노출하는 것에 따라 전환합니다. 여러분의 프롬프트와 실행기가 반환하는 것이 선택을 유도합니다.

• 페이지에 사용 가능한 접근성 트리가 있는 곳에서는 참조를 선호하세요. 참조는 픽셀 좌표를 취약하게 만드는 레이아웃 이동과 리플로우를 견디며, Claude가 포인터로 맞추기 어려운 컨트롤에 대해 동작할 수 있게 합니다.
• 트리가 설명하지 않는 콘텐츠에는 좌표로 대체하세요. 캔버스로 렌더링된 인터페이스, 임베드된 비디오나 원격 데스크톱 표면, 고도로 가상화된 목록, 교차 출처 iframe 내부의 요소는 유용한 노드가 없는 경우가 많으므로, Claude는 screenshot과 zoom으로 작업하고 좌표로 클릭합니다. 좌표가 어느 프레임에 떨어지는지는 여러분의 실행기가 해석합니다.
• 읽기 범위를 한정하고, 스크린샷 전에 트리를 읽으세요. 큰 페이지에서는 filter: "interactive" 또는 컨테이너의 ref를 사용한 read_page가 집중된 하위 트리를 반환하며, 일반적인 페이지의 트리 읽기는 스크린샷보다 입력 토큰이 적게 드는 경우가 많으면서도 Claude가 즉시 동작에 사용할 수 있는 참조를 제공합니다. 시각적 레이아웃, 이미지, 또는 렌더링 상태가 중요할 때는 스크린샷이 여전히 올바른 관찰 수단입니다.



보안 고려 사항

브라우저 사용은 표준 API 기능에는 없는 위험을 수반합니다. Claude가 공개 웹의 콘텐츠를 읽고 그에 대해 동작하며, 어떤 페이지든 Claude를 조종하기 위해 작성된 텍스트를 담고 있을 수 있기 때문입니다.

Claude는 때때로 페이지 콘텐츠에서 발견한 지시가 여러분의 지시와 충돌하더라도 이를 따릅니다. "이전 지시를 무시하고 ...로 이동하라"고 말하는 페이지의 텍스트가 Claude를 작업에서 벗어나게 할 수 있습니다. 프롬프트 인젝션이 도달할 수 있는 범위를 제한하기 위해 Claude를 민감한 데이터와 동작으로부터 격리하고, 탈옥 및 프롬프트 인젝션 완화를 검토하고, 작업에서 로그인된 세션을 피할 수 없다면 전용 저권한 계정을 사용하고 계정을 변경하는 동작에 대해 사람의 확인을 유지하세요.

브라우저가 여러분의 환경에서 실행되므로, Claude가 방문하는 사이트는 여러분의 실행기의 네트워크 신원을 보게 되며, 페이지 콘텐츠는 여러분이 반환하는 도구 결과로만 API에 도달합니다. 제품에서 브라우저 사용을 활성화하기 전에 최종 사용자에게 관련 위험을 알리고 동의를 얻으세요.



멤버 도구

browser_toolset_20260801 항목은 31개의 멤버 도구를 선언합니다. 각 호출의 input은 정확히 여기에 나열된 매개변수이며, tab_id는 선택 사항인 경우 활성 탭이 기본값입니다. Target, CoordinateTarget, RefTarget은 대상과 좌표에 설명된 형태입니다. 네 개의 멤버(javascript_exec, file_upload, read_console, read_network)는 기본적으로 비활성화되어 있으며 활성화할 때만 나타납니다. 각 멤버의 행에 명시된 입력 범위와 출력 규칙은 Claude에게 전달되는 것이며 API가 강제하지 않으므로, 여러분의 실행기에서 입력(뷰포트에 대한 좌표 포함)을 검증하고 규칙을 적용하세요.

screenshot과 zoom만 결과에 image 블록이 필요하며, 네 개의 탭 관리 멤버(new_tab, list_tabs, switch_tab, close_tab)는 정확히 하나의 browser_state 블록을 반환합니다(탭 관리 결과 참조). 다른 모든 멤버는 text 블록을 반환합니다. Clicked element ref_2.와 같은 짧은 확인 응답이거나 멤버의 출력입니다. 탭 관리 결과 이외의 모든 결과는 image 블록도 담을 수 있으며, 일반적으로 동작 후에 찍은 스크린샷이므로 Claude는 별도의 screenshot 호출 없이 결과를 볼 수 있습니다. 배치 동작에서 배치 내 어디에 첨부할지 보여 줍니다. 멤버 tool_result는 text, image, browser_state 콘텐츠 블록만 담을 수 있습니다.



탐색 및 캡처



포인터



키보드 및 타이밍



페이지 읽기



폼 및 파일



진단 및 스크립팅



탭 관리

성공 시 이들 각각은 텍스트나 이미지 없이 정확히 하나의 browser_state 블록을 반환합니다. 탭 관리 결과를 참조하세요.



도구 세트 구성

type 외에 도구 세트 항목은 configs, cache_control, allowed_callers를 받습니다. 이 필드들이 컴퓨터 사용 도구 세트와 공유하는 규칙은 클라이언트 도구 세트에 나열되어 있으며, 이 섹션에서는 브라우저 고유의 기본값을 다룹니다. configs는 멤버 이름을 키로 하는 객체이며, 각 멤버의 값은 두 개의 필드를 받습니다.



멤버 도구 활성화 또는 비활성화

configs에는 변경하려는 멤버만 나열하세요. 생략한 모든 멤버는 기본값을 유지합니다. 예를 들어, 콘솔 읽기는 구현하지만 저수준 포인터나 키 유지 제어는 구현하지 않는 실행기는 read_console을 켜고 세 개의 멤버를 제외합니다.

{
  "type": "browser_toolset_20260801",
  "configs": {
    "read_console": { "enabled": true },
    "left_mouse_down": { "enabled": false },
    "left_mouse_up": { "enabled": false },
    "hold_key": { "enabled": false }
  }
}

비활성화된 멤버는 Claude가 보는 정의에서 사라집니다. 그렇다고 Claude가 절대 이를 지정하지 않는다는 보장은 없으므로, 여러분의 실행기는 여전히 그러한 호출에 오류 결과로 응답합니다.



다른 도구와 결합

브라우저 사용 도구를 여러분의 자체 도구 및 다른 Anthropic 제공 도구와 함께 같은 tools 배열에 선언하세요. toolset_name이 Claude의 호출을 구분하므로 커스텀 도구는 멤버의 이름을 공유할 수 있지만(예: 여러분 자체의 navigate), 다른 어떤 항목도 browser라는 이름을 가질 수 없으며, 요청에는 브라우저 도구 세트 항목이 하나만 담길 수 있습니다.

컴퓨터 사용 도구와 함께 선언할 수도 있으며, 도구 세트든 이전 컴퓨터 사용 도구 버전이든 가능합니다. 둘은 각자의 좌표 프레임(여기서는 뷰포트 픽셀, 저기서는 데스크톱 스크린샷 픽셀)에서 독립적으로 작동하며, screenshot이나 key처럼 이름을 공유하는 멤버에 대한 Claude의 호출은 toolset_name으로 구분됩니다.



선택적 멤버 활성화

네 개의 멤버 도구는 기본적으로 비활성화되어 있습니다. javascript_exec와 file_upload는 조종된 페이지가 Claude에게 시킬 수 있는 일의 범위를 넓히기 때문이고, read_console과 read_network는 모든 브라우저 자동화 스택이 해당 로그를 제공할 수 있는 것은 아니며 페이지가 제어하는 콘텐츠가 Claude에게 도달하는 범위를 넓히기 때문입니다. 여러분의 실행기가 이를 구현하고 작업에 필요할 때만 configs로 각각을 활성화하세요(예: "configs": {"file_upload": {"enabled": true}}).



파일 업로드

file_upload는 <input type="file"> 요소에 파일을 직접 설정하며, 이는 네이티브 파일 선택기를 구동하는 것보다 더 안정적입니다. 호출에 요소의 신원이 필요하므로 target은 참조만 가능하며, paths, document_ids, 또는 둘 다를 받습니다.

• paths는 실행기 파일 시스템의 파일 경로로, 실행기가 여러분의 애플리케이션의 파일을 직접 읽을 수 있는 배포용입니다(다운로드의 path를 채우는 것과 동일한 조건).
• document_ids는 여러분의 애플리케이션이 브라우저를 위해 준비한 파일의 식별자로, 그럴 수 없는 배포용입니다. 식별자의 의미는 여러분의 애플리케이션이 정의합니다. paths의 범위를 한정하는 것과 같은 방식으로, 이 작업을 위해 준비된 파일로 해석 범위를 한정하세요.

{
  "type": "tool_use",
  "id": "toolu_01N7gVzFEfZjLjgsYwnrPgrF",
  "name": "file_upload",
  "toolset_name": "browser",
  "input": {
    "target": { "type": "ref", "ref": "ref_12" },
    "paths": ["/home/user/uploads/summary.pdf"],
    "tab_id": "tab-2"
  }
}

Claude는 신뢰할 수 없는 페이지를 읽는 동안 이 경로들을 작성하므로, 제한 없는 구현은 악의적인 페이지가 실행기가 읽을 수 있는 모든 파일을 페이지가 제어하는 사이트로 업로드하도록 지시할 수 있게 합니다. 여러분의 실행기가 각 경로를 해석하고(심볼릭 링크와 .. 세그먼트를 따라가며) 작업용 파일만 담고 있는 전용 허용 목록 업로드 디렉터리 밖의 것은 아무것도 받아들이지 않을 때만 이 멤버를 활성화하세요. 이를 위해 브라우저의 다운로드 디렉터리를 재사용하지 마세요. 그렇게 하면 페이지가 브라우저로 하여금 다운로드하게 만든 모든 파일이 업로드 가능해집니다.



페이지에서 JavaScript 실행

javascript_exec는 Claude가 작성한 표현식을 페이지의 컨텍스트에서 실행하고 마지막 표현식의 값을 텍스트로 반환합니다. Claude는 return 문이 아니라 표현식을 작성합니다. 코드는 쿠키, 스토리지, 동일 출처 요청을 포함한 페이지의 전체 권한으로 실행됩니다. 자격 증명이 없는 세션에서만 이 멤버를 활성화하고, 보안 고려 사항의 도메인 허용 목록을 유지하고, 반환된 값을 신뢰할 수 없는 입력으로 취급하고, Claude가 내보내는 코드를 로깅하세요.



콘솔 및 네트워크 활동 읽기

read_console은 탭의 콘솔 항목을 반환하고 read_network는 네트워크 요청을 반환하며, 각각 해당 탭의 이전 읽기 이후 누적된 항목당 한 줄의 텍스트입니다. 콘솔 줄은 로그, 경고, 또는 오류 항목을 담고, 네트워크 줄은 메서드, URL, 상태, MIME 타입, 타이밍을 담습니다. 항목은 여러분의 브라우저 자동화가 탭에 연결된 순간부터만 존재하므로, 빈 결과가 이미 열려 있던 탭에 트래픽이 없었다는 것을 의미하지는 않습니다.

이 멤버들은 Claude가 반복적인 스크린샷 없이 오작동하는 페이지(스피너 뒤의 실패한 요청, 작동하지 않는 버튼 뒤의 스크립트 오류)를 진단할 수 있게 합니다. 콘솔 및 네트워크 항목은 페이지가 제어하며 요청 URL의 토큰과 같은 비밀을 담고 있는 경우가 많으므로, Claude의 컨텍스트에 넣고 싶지 않은 자격 증명 같은 값은 가리고 매우 긴 항목은 반환하기 전에 잘라내세요.



browser_state로 탭 추적하기

Claude는 tab_id로 탭을 지정하며, 어떤 탭이 존재하는지에 대한 기준 정보(source of truth)는 여러분의 애플리케이션이 가지고 있습니다. 여러분은 그 상태를 browser_state 콘텐츠 블록으로 보고하는데, Claude는 이 블록을 직접 보지 않습니다. 대신 API가 이 블록으로부터 Claude가 읽는 텍스트를 렌더링합니다.

{
  "type": "browser_state",
  "tabs": [
    {
      "tab_id": "tab-1",
      "title": "Documentation",
      "url": "https://example.com/docs",
      "active": true
    },
    { "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" }
  ]
}

• tabs는 호출 이후 열려 있는 탭의 전체 목록이며, 변경분(delta)이 아닙니다. 비어 있을 수 있으며, 비어 있지 않을 때는 정확히 하나의 항목만 "active": true를 가집니다.
• state_changes(여기에는 표시되지 않음)는 호출의 부수 효과를 보고합니다. 호출이 열었고 호출이 끝날 때까지 여전히 열려 있는 각 탭에 대한 tab_opened 항목(이 항목의 tab_id는 tabs에도 나타나야 함)과 다운로드 이벤트가 여기에 해당합니다. 보고할 것이 없으면 이 필드를 생략하세요. 빈 배열은 거부됩니다.
• 이 블록은 브라우저 멤버 호출에 응답하는 결과에만, tool_result당 최대 한 번만 보내고, is_error: true인 결과에는 절대 보내지 마세요. "보고할 탭 상태 없음"은 블록을 생략하는 것으로 표현합니다.
• API는 다음 두 섹션에서 설명하는 대로 tabs를 Claude를 위한 텍스트로 렌더링합니다. state_changes의 다운로드 항목은 검증되지만 렌더링되지는 않습니다.

tab_id 값은 여러분이 할당합니다. 자동화 라이브러리의 페이지 식별자나 자체 카운터 등 안정적인 문자열이면 무엇이든 사용할 수 있습니다. 단, 이전 결과에서 해당 식별자를 가진 탭이 아직 열려 있는 것으로 나열되어 있는 동안에는 그 tab_id를 재사용하지 않아야 합니다. API는 이 블록에 대해 다음 제한을 적용합니다.

• 각 tab_id, title, url은 최대 4,096자이며, tab_id는 비어 있지 않아야 하고, 어느 것도 제어 문자(줄바꿈 포함)나 Unicode 줄 구분자 또는 단락 구분자를 포함할 수 없습니다.
• 하나의 블록은 최대 100개의 탭과 200개의 상태 변경을 나열할 수 있습니다.
• Claude가 switch_tab과 close_tab에 전달하는 tab_id에도 동일한 제한이 적용됩니다. API가 이를 결과 텍스트로 렌더링하기 때문입니다. 따라서 tab_id가 이 제한을 위반하는 호출에는 browser_state 블록 대신 오류 결과로 응답하세요.



탭 관리 결과

new_tab, switch_tab, close_tab, list_tabs의 경우, 성공 결과의 content는 텍스트나 이미지 없이 정확히 하나의 browser_state 블록이며, Claude가 보는 텍스트는 API가 작성합니다. new_tab 결과의 블록은 또한 active: true로 표시된 항목과 tab_id가 일치하는 tab_opened 상태 변경을 정확히 하나 포함해야 합니다.

블록에 두 개의 탭이 나열되고 첫 번째 탭이 활성 상태인 list_tabs 결과는 다음과 같이 렌더링됩니다. 각 줄은 두 칸 들여쓰기되며 활성 탭에만 (current)가 붙습니다.

Available tabs:
  • tab_id tab-1: "Documentation" (https://example.com/docs) (current)
  • tab_id tab-2: "Pricing" (https://example.com/pricing)

이 멤버들 중 하나에 대한 오류 결과는 그 반대입니다. content에 일반 오류 텍스트, is_error: true, 그리고 browser_state 블록 없음입니다.

예를 들어, Claude가 new_tab을 호출하면(input은 비어 있음), 여러분의 실행기(executor)는 탭을 열고 활성화한 다음 tab_opened 항목 하나와 함께 목록을 반환합니다.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01WvHSbQVV9j5nWGvTmk4vNL",
      "toolset_name": "browser",
      "content": [
        {
          "type": "browser_state",
          "tabs": [
            { "tab_id": "tab-1", "title": "Documentation", "url": "https://example.com/docs" },
            { "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" },
            { "tab_id": "tab-3", "title": "", "url": "about:blank", "active": true }
          ],
          "state_changes": [{ "type": "tab_opened", "tab_id": "tab-3" }]
        }
      ]
    }
  ]
}

Claude는 Created new tab with tab_id: tab-3, URL: about:blank. It is now the current tab.을 봅니다. 여기서처럼 탭이 열린 시점의 URL을 보고하고, 나중에 리디렉션된 URL은 보고하지 마세요. 이후 결과에서는 그 시점의 탭 현재 URL을 보고합니다.



다른 결과의 탭 컨텍스트

다른 모든 멤버에서 이 블록은 선택 사항입니다. 열린 탭 집합, 활성 탭, 또는 탭의 제목이나 URL이 변경되었을 때, 혹은 보고할 state_changes가 있을 때 보내고, 항상 전체 tabs 목록을 포함하세요. 결과에 텍스트와 browser_state 블록이 모두 있으면, API는 해당 결과의 텍스트에 Tab Context 푸터를 여러분의 텍스트와 빈 줄로 구분하여 덧붙입니다. 따라서 Claude는 별도의 list_tabs 호출 없이 새 상태를 받습니다.

Tab Context:
- Executed on tab_id: tab-1
- Available tabs:
  • tab_id tab-1: "Documentation" (https://example.com/docs)
  • tab_id tab-2: "Pricing" (https://example.com/pricing)

Executed on은 호출이 실행된 탭을 지정하는데, tab_id 입력이 있으면 그 값이고 없으면 활성 탭입니다. 푸터의 탭 줄에는 (current) 표시가 없습니다. 이 텍스트를 직접 덧붙이지 마세요. 구조화된 블록을 보내고 API가 렌더링하도록 하세요. 푸터는 중복 제거되므로 동일한 탭 상태는 이후 결과에서 다시 렌더링되지 않으며, 블록을 넉넉하게 채워도 비용이 들지 않습니다.

블록이 있어도 푸터가 렌더링되지 않는 세 가지 경우가 있습니다.

• 모든 zoom 결과.
• text 블록이 없는 결과(예: 이미지만 있는 screenshot 결과). 해당 결과에 대해서는 아무것도 렌더링되거나 기억되지 않습니다. 탭 컨텍스트는 텍스트와 browser_state 블록을 모두 가진 다음 결과에 나타나므로, 같은 결과에서 Claude가 탭 변경을 보게 하려면 이미지와 함께 짧은 텍스트 블록을 포함하세요.
• tab_id가 없는 호출에서 tabs 목록이 비어 있는 결과. 지정할 탭이 없기 때문입니다.

예를 들어, 이 세션 앞부분에서 Claude가 "Pricing" 링크(ref_5)를 클릭했을 때, 페이지는 Claude가 요청하지 않은 새 탭에서 이를 열었고, 보고가 없다면 Claude는 이를 발견하기 위해 list_tabs를 호출해야 했을 것입니다. 클릭 확인 응답과 함께, state_changes에 열린 탭을 명시하고 실행기가 활성 상태로 남겨둔 탭을 표시한 블록을 반환하세요.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01EgTXj1FjE2FCTt2zNFWLao",
      "toolset_name": "browser",
      "content": [
        { "type": "text", "text": "Clicked element ref_5." },
        {
          "type": "browser_state",
          "tabs": [
            {
              "tab_id": "tab-1",
              "title": "Documentation",
              "url": "https://example.com/docs",
              "active": true
            },
            { "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" }
          ],
          "state_changes": [{ "type": "tab_opened", "tab_id": "tab-2" }]
        }
      ]
    }
  ]
}

Claude는 Clicked element ref_5. 다음에 앞서 보여준 Tab Context 푸터를 봅니다. 실패한 호출 중에 열린 탭은 tab_opened 항목을 받지 않습니다. 오류 결과에는 browser_state가 없기 때문입니다. 대신 다음 성공 결과의 tabs 목록에 나타납니다. 배치에서는 변경이 발생한 호출의 결과에 블록을 첨부하고, 같은 턴의 이전 결과가 동일한 상태를 보고했더라도 모든 성공한 탭 관리 결과에 각각의 블록을 제공하세요.



다운로드 보고

클릭이나 탐색이 파일 다운로드를 시작하면, 다운로드가 발생한 호출의 결과에서 state_changes로 보고하고, 여러분이 할당한 download_id로 여러 결과에 걸쳐 연관시키세요. 다운로드는 비동기로 실행되며 여러 결과에 걸칠 수 있으므로 세 가지 이벤트 유형이 있습니다.

API는 이 항목들을 검증하지만 Claude가 보는 텍스트로 렌더링하지는 않으므로, Claude가 파일에 대해 조치를 취해야 할 때는 같은 결과의 text 블록에 파일 이름이나 path도 언급하세요.

예를 들어, Pricing 탭에서 "Download price list (CSV)"(ref_8)를 클릭하면 다운로드가 시작되므로, 클릭 결과에는 download_id가 "dl-1"이고 파일 URL이 담긴 download_started 항목이 포함됩니다. 다운로드는 이후 screenshot 호출이 실행되는 동안 완료되므로, 그 결과의 content에는 이미지, Screenshot captured. Download complete: /home/user/downloads/price-list.csv (48,213 bytes).와 같은 텍스트 블록, 그리고 같은 download_id로 완료를 보고하는 다음 browser_state 블록이 담깁니다.

{
  "type": "browser_state",
  "tabs": [
    { "tab_id": "tab-1", "title": "Documentation", "url": "https://example.com/docs" },
    {
      "tab_id": "tab-2",
      "title": "Pricing",
      "url": "https://example.com/pricing",
      "active": true
    }
  ],
  "state_changes": [
    {
      "type": "download_completed",
      "download_id": "dl-1",
      "url": "https://example.com/pricing/price-list.csv",
      "path": "/home/user/downloads/price-list.csv",
      "size_bytes": 48213
    }
  ]
}

다운로드 보고는 다음 규칙을 따릅니다.

• 하나의 블록에서 download_id당 최대 하나의 항목만 허용되므로, 같은 호출 중에 시작되고 완료된 다운로드는 download_completed만 보고합니다.
• is_error: true 결과에는 절대 state_changes를 보내지 마세요. 실패한 호출 중에 발생한 다운로드 이벤트는 다음 성공 결과에서 보고하세요.
• state_changes는 진행 중인 다운로드의 목록이 아닙니다. 각 이벤트는 한 번만 보고하세요.
• 각 항목은 해당 type이 선언한 필드만 가집니다. size_bytes는 음이 아닌 정수이고, download_id는 비어 있지 않으며, download_id, url, path, error는 각각 최대 4,096자이고 제어 문자나 Unicode 줄 구분자 또는 단락 구분자를 포함하지 않습니다. url은 원격 서버에서 오며 리디렉션 이후 서명된 쿼리 문자열 자격 증명을 포함하는 경우가 많으므로, Claude의 컨텍스트에 넣고 싶지 않은 쿼리 매개변수는 제거하고, 보고하거나 파일 시스템 경로에 사용하기 전에 정제하세요.



오류 처리

실패한 호출은 일반 오류 결과로 Claude에게 보고하세요. is_error: true, 무엇이 잘못되었는지 설명하는 텍스트 콘텐츠, 그대로 반영한 toolset_name, 그리고 browser_state 블록 없음입니다.



실행기에서 오류 반환하기

Claude는 오류 텍스트를 읽고 적응하므로 오류 텍스트를 구체적으로 작성하세요. Error: Navigation to https://example.com/status timed out after 30 seconds. The page may be unavailable.은 Claude가 조치할 수 있는 정보를 주지만, 단순한 Error: navigation failed는 그렇지 않습니다. 다른 일반적인 경우는 다음과 같습니다.



요청 오류

API는 툴셋 항목과 대화 내 모든 멤버 tool_use 및 tool_result 블록을 검증합니다. 하나라도 형식이 잘못되면 API는 Claude가 실행되기 전에 invalid_request_error를 반환합니다. 다음 표에서 왼쪽 열은 여러분이 보낸 것을 나타냅니다.



제한 사항

• 플랫폼 가용성: 브라우저 사용은 Claude API에서만 사용할 수 있습니다.
• 전체 입력 스트리밍만 지원: 스트리밍할 때 각 멤버의 input은 하나의 완전한 input_json_delta로 도착합니다(클라이언트 툴셋).
• 요소 참조는 최선 노력(best-effort) 방식: 매우 동적인 페이지(가상화된 목록, 캔버스로 렌더링된 인터페이스, 스크롤 시 다시 렌더링되는 페이지)는 안정적인 참조를 노출하지 않을 수 있으며, 이 경우 Claude는 스크린샷과 좌표 클릭으로 대체합니다.
• read_console과 read_network는 브라우저 자동화에 의존: 브라우저 자동화가 캡처할 수 있는 것만, 그리고 탭에 연결된 시점부터만 보고합니다.
• 일반적인 에이전트 제한 사항 적용: 지연 시간(latency), 비전 정확도, 프롬프트 인젝션 위험은 컴퓨터 사용에서 그대로 이어지며(컴퓨터 사용 도구의 제한 사항 참조), 프롬프팅으로 모델 성능 최적화, 스크린샷 기록 관리, 구현 모범 사례 따르기(작업 지연, 작업 검증, 로깅)의 지침은 브라우저 실행기에도 적용됩니다.



가격 및 데이터 보존

브라우저 사용은 표준 도구 사용 가격을 따릅니다. 브라우저 사용 도구를 사용할 때:

툴셋 정의 오버헤드: 기본 멤버와 함께 browser_toolset_20260801을 선언하면 요청에 약 6,600개의 입력 토큰이 추가됩니다(Claude Fable 5, Claude Mythos 5, Claude Opus 5, Claude Opus 4.8에서는 약 6,610개, Claude Sonnet 5에서는 약 6,670개). 여기에는 멤버 도구 정의와 도구 사용 시스템 프롬프트가 포함됩니다. 네 개의 선택적 멤버를 모두 활성화하면 약 880개의 토큰이 추가되며, configs로 멤버를 비활성화하면 토큰 수가 줄어듭니다. 요청에 대한 정확한 토큰 수는 응답의 usage에 보고되며, 토큰 카운팅 엔드포인트를 사용하여 미리 추정할 수 있습니다.

추가 토큰 소비:

• 도구 결과로 반환되는 스크린샷 및 확대 이미지는 이미지 입력으로 청구됩니다(비전 가격 참조)
• 접근성 트리, 페이지 텍스트, 콘솔 또는 네트워크 항목 등 Claude에 반환되는 텍스트 도구 결과

브라우저 세션, 다운로드, 업로드된 파일은 여러분의 환경에 남습니다. 여러분이 반환하는 스크린샷, 페이지 텍스트, 탭 상태는 API 요청 콘텐츠의 일부이며 표준 보존 정책을 따르거나, ZDR 계약이 있는 경우 해당 계약을 따릅니다. 브라우저 사용 도구는 ZDR 적격입니다. 기능별 보존 기간과 적격 여부는 API 및 데이터 보존을 참조하세요.



다음 단계