브라우저 OS 작업

InvokeBrowser API는 Amazon Bedrock AgentCore 브라우저 세션에 대한 직접 운영 체제 수준 제어를 제공합니다. WebSocket 기반 자동화 엔드포인트는 브라우저 상호 작용에 Chrome DevTools 프로토콜(CDP)을 사용하지만 InvokeBrowser는 OS 수준에서 작동하여 인쇄 대화 상자, 키보드 바로 가기, 마우스 오른쪽 버튼 클릭 컨텍스트 메뉴, JavaScript 알림, 전체 화면 스크린샷 캡처와 같은 CDP가 처리할 수 없는 작업을 활성화합니다.

개요

Amazon Bedrock AgentCore 브라우저는 브라우저 세션과 상호 작용하는 두 가지 방법을 제공합니다.

WebSocket 기반 자동화(CDP) : WebSocket 연결을 통해 Chrome DevTools 프로토콜을 사용합니다. 이는 페이지 탐색, DOM 요소 클릭, 양식 채우기, 페이지 콘텐츠 추출과 같은 표준 브라우저 자동화 작업에 적합합니다. Playwright 및 브라우저 사용 같은 라이브러리는이 엔드포인트를 통해 연결됩니다.
OS 수준 작업(InvokeBrowser) : REST API를 사용하여 마우스, 키보드 및 스크린샷 작업을 통해 운영 체제 수준 상호 작용을 수행합니다. 이렇게 하면 브라우저 수준 자동화가 충분하지 않은 시나리오를 처리하여 CDP를 보완할 수 있습니다.

에이전트가 다음을 수행해야 하는 경우 InvokeBrowser를 사용합니다.

인쇄 대화 상자, 파일 업로드/다운로드 대화 상자 또는 브라우저 DOM 외부에 있는 인증 프롬프트와 같은 기본 OS 대화 상자와 상호 작용
CDP 실행을 차단하는 JavaScript 알림, 확인 또는 프롬프트 무시
OS 수준 동작을 트리거하는 키보드 바로 가기(예: ctrl+a, ctrl+p) 사용
운영 체제에서 렌더링한 마우스 오른쪽 버튼 클릭 컨텍스트 메뉴와 상호 작용
OS 알림 또는 다중 창 레이아웃과 같이 브라우저 뷰포트 외부의 콘텐츠가 포함된 전체 데스크톱 스크린샷 캡처
브라우저 창 전체 또는 브라우저와 데스크톱 간에 drag-and-drop 작업 수행

InvokeBrowser는 InvokeCodeInterpreter와 동일한 패턴, 즉 작업 유형 디스패치를 사용하는 단일 통합 작업을 따릅니다. 정확히 하나의 작업으로 요청을 전송하고 해당 결과를 수신합니다.

지원되는 작업

InvokeBrowser는 BrowserAction 집합을 통해 다음 작업 유형을 지원합니다. 요청당 정확히 하나의 작업 멤버를 설정해야 합니다.

마우스 작업

모든 마우스 작업에서 좌표 값(x, y )은 브라우저 세션 뷰포트 경계 내에 있어야 합니다. 유효한 범위는 1 < x < viewportWidth-2 및 1 < y < viewportHeight-2입니다. 기본 뷰포트 크기는 1456×819픽셀이며 파라미터를 사용하여 세션을 시작할 때 구성할 수 있습니다viewPort.

작업	필수 필드	선택 필드	설명
`mouseClick`	`x` (정수), `y` (정수)	`button` (MouseButton), `clickCount` (정수)	지정된 좌표를 클릭합니다. `clickCount` : 1~10. `button` : 왼쪽, 오른쪽, 중간.
`mouseMove`	`x` (정수), `y` (정수)	—	커서를 지정된 좌표로 이동합니다.
`mouseDrag`	`startX` (정수), `startY` (정수), `endX` (정수), `endY` (정수)	`button` (MouseButton)	시작 위치에서 종료 위치로 끕니다. `button` 기본값은 왼쪽입니다.
`mouseScroll`	`x` (정수), `y` (정수)	`deltaX` (정수), `deltaY` (정수)	지정된 위치에서 스크롤합니다. `deltaX` /`deltaY`: -1000~1000. 음수는 아래로 `deltaY` 스크롤합니다.

키보드 작업

작업	필수 필드	선택 필드	설명
`keyType`	`text` (문자열)	—	텍스트 문자열을 입력합니다. 최대 길이: 10,000자.
`keyPress`	`key` (문자열)	`presses` (정수)	키를 N번 누릅니다. `presses` : 1~100. 기본값은 1입니다.
`keyShortcut`	`keys` (KeyList)	—	키 조합(예: `["ctrl", "s"]` )을 누릅니다. 최대 5개의 키.

스크린샷 작업

작업	필수 필드	선택 필드	설명
`screenshot`	—	`format` (ScreenshotFormat)	전체 OS 데스크톱(브라우저 뷰포트뿐만 아니라)을 캡처합니다. 형식: PNG 전용.

고려 사항

ASCII 전용 텍스트 입력: keyType 작업은 ASCII 문자만 지원합니다. ASCII가 아닌 문자(예: 유니코드 또는 멀티바이트 문자)는 입력 중에 건너뜁니다.
키 이름 검증 없음: keyPress 및 keyShortcut 작업은 지정된 키 이름이 지원되는지 여부를 검증하지 않습니다. 인식할 수 없는 키 이름을 입력하면 API는 의도한 작업을 수행하지 않고 SUCCESS 상태를 반환합니다. 위에 나열된 지원되는 키 이름을 참조하세요.
지원되는 키 이름: keyPress 및 keyShortcut 작업에 대한 키 이름은 소문자여야 합니다. 지원되는 키에는 단일 문자( a – z , 0 – 9 )와 enter , , tab , space , backspace , escape , ctrl , 등의 delete 명명된 키alt가 포함됩니다shift.

요청 및 응답 형식

요청


POST /browsers/{browserIdentifier}/sessions/invoke HTTP/1.1
x-amzn-browser-session-id: sessionId
Content-type: application/json

요청 본문에는 BrowserAction 조합 세트의 멤버가 정확히 한 명 있는 action 필드가 포함되어 있습니다.


{
    "action": {
        "mouseClick": {
            "x": 100,
            "y": 200,
            "button": "LEFT",
            "clickCount": 1
        }
    }
}

응답

sessionId는 x-amzn-browser-session-id 응답 헤더를 통해 반환됩니다. 응답 본문에는 해당 작업 결과가 있는 result 필드가 포함되어 있습니다.

성공 시:


{
    "result": {
        "mouseClick": {
            "status": "SUCCESS",
            "error": null
        }
    }
}

실패 시 status 필드가 실패로 설정되고 error 필드에 실패에 대한 설명이 포함됩니다.

예제

다음 예제에서는 AWS CLI, Python용 AWS SDK(Boto3) 및 API를 사용하여 브라우저 작업을 호출하는 방법을 보여줍니다.

예

AWS CLI

특정 위치를 클릭하는 방법:


aws bedrock-agentcore invoke-browser \
  --region <Region> \
  --browser-identifier "aws.browser.v1" \
  --session-id "<your-session-id>" \
  --action '{"mouseClick": {"x": 100, "y": 200, "button": "LEFT", "clickCount": 1}}'

텍스트를 입력하려면:


aws bedrock-agentcore invoke-browser \
  --region <Region> \
  --browser-identifier "aws.browser.v1" \
  --session-id "<your-session-id>" \
  --action '{"keyType": {"text": "Hello, world!"}}'

키보드 바로 가기를 누릅니다.


aws bedrock-agentcore invoke-browser \
  --region <Region> \
  --browser-identifier "aws.browser.v1" \
  --session-id "<your-session-id>" \
  --action '{"keyShortcut": {"keys": ["ctrl", "s"]}}'

스크린샷을 찍으려면:


aws bedrock-agentcore invoke-browser \
  --region <Region> \
  --browser-identifier "aws.browser.v1" \
  --session-id "<your-session-id>" \
  --action '{"screenshot": {"format": "PNG"}}'

Boto3

특정 위치를 클릭하는 방법:


response = dp_client.invoke_browser(
    browserIdentifier="aws.browser.v1",
    sessionId="<your-session-id>",
    action={
        "mouseClick": {
            "x": 100,
            "y": 200,
            "button": "LEFT",
            "clickCount": 1
        }
    }
)
print(f"Status: {response['result']['mouseClick']['status']}")

텍스트를 입력하려면:


response = dp_client.invoke_browser(
    browserIdentifier="aws.browser.v1",
    sessionId="<your-session-id>",
    action={
        "keyType": {
            "text": "Hello, world!"
        }
    }
)

스크린샷을 만들고 저장하려면:


import base64

response = dp_client.invoke_browser(
    browserIdentifier="aws.browser.v1",
    sessionId="<your-session-id>",
    action={
        "screenshot": {
            "format": "PNG"
        }
    }
)

if response['result']['screenshot']['status'] == 'SUCCESS':
    image_data = base64.b64decode(response['result']['screenshot']['data'])
    with open("screenshot.png", "wb") as f:
        f.write(image_data)
    print("Screenshot saved as screenshot.png")

API

특정 위치를 클릭하는 방법:


awscurl -X POST \
  "https://bedrock-agentcore.<Region>.amazonaws.com/browsers/aws.browser.v1/sessions/invoke" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-amzn-browser-session-id: <your-session-id>" \
  --service bedrock-agentcore \
  --region <Region> \
  -d '{
    "action": {
        "mouseClick": {
            "x": 100,
            "y": 200,
            "button": "LEFT",
            "clickCount": 1
        }
    }
  }'

스크린샷을 찍으려면:


awscurl -X POST \
  "https://bedrock-agentcore.<Region>.amazonaws.com/browsers/aws.browser.v1/sessions/invoke" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-amzn-browser-session-id: <your-session-id>" \
  --service bedrock-agentcore \
  --region <Region> \
  -d '{
    "action": {
        "screenshot": {
            "format": "PNG"
        }
    }
  }'

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

루트 인증 기관

AgentCore 브라우저 문제 해결