View a markdown version of this page

Tindakan OS Browser - Batuan Dasar Amazon AgentCore
Gambaran umumTindakan yang didukungPertimbangan-pertimbanganFormat permintaan dan responsContoh

Tindakan OS Browser

InvokeBrowser API menyediakan kontrol tingkat sistem operasi langsung atas sesi Amazon Bedrock Browser AgentCore . Sementara titik akhir WebSocket-based otomatisasi menggunakan DevTools Protokol Chrome (CDP) untuk interaksi browser, InvokeBrowser beroperasi pada tingkat OS, memungkinkan tindakan yang tidak dapat ditangani CDP — seperti berinteraksi dengan dialog cetak, pintasan keyboard, menu konteks klik kanan, peringatan, dan menangkap tangkapan layar layar penuh. JavaScript

Gambaran umum

Amazon Bedrock AgentCore Browser menyediakan dua cara untuk berinteraksi dengan sesi browser:

  • WebSocket-based otomatisasi (CDP): Menggunakan DevTools Protokol Chrome melalui WebSocket koneksi. Ini sangat ideal untuk tugas-tugas otomatisasi browser standar seperti menavigasi halaman, mengklik elemen DOM, mengisi formulir, dan mengekstrak konten halaman. Pustaka seperti Playwright dan penggunaan browser terhubung melalui titik akhir ini.

  • OS-level actions (InvokeBrowser): Menggunakan REST API untuk melakukan interaksi tingkat sistem operasi melalui tindakan mouse, keyboard, dan screenshot. Ini melengkapi CDP dengan menangani skenario di mana otomatisasi tingkat browser tidak mencukupi.

Gunakan InvokeBrowser saat agen Anda perlu:

  • Berinteraksi dengan dialog OS asli seperti dialog cetak, upload/download dialog file, atau petunjuk otentikasi yang berada di luar DOM browser

  • Menghentikan JavaScript peringatan, konfirmasi, atau permintaan yang memblokir eksekusi CDP

  • Gunakan pintasan keyboard (misalnya, ctrl+a, ctrl+p) yang memicu perilaku OS-level

  • Berinteraksi dengan menu konteks klik kanan yang diberikan oleh sistem operasi

  • Tangkap tangkapan layar desktop lengkap yang menyertakan konten di luar viewport browser, seperti notifikasi OS atau tata letak multi-jendela

  • Lakukan operasi drag-and-drop yang menjangkau seluruh jendela browser atau antara browser dan desktop

InvokeBrowser mengikuti pola yang sama seperti InvokeCodeInterpreter: operasi terpadu tunggal dengan pengiriman tipe tindakan. Anda mengirim permintaan dengan tepat satu tindakan, dan menerima hasil yang sesuai.

Tindakan yang didukung

InvokeBrowser mendukung jenis tindakan berikut melalui BrowserAction serikat pekerja. Tepat satu anggota tindakan harus ditetapkan per permintaan.

Tindakan mouse

Untuk semua tindakan mouse, nilai koordinat (x,y) harus benar-benar berada dalam batas viewport sesi browser. Rentang yang valid adalah 1 < x < viewport Width-2 dan 1 < y < Height-2 viewport. Ukuran viewport default adalah 1456 × 819 piksel, yang dapat dikonfigurasi saat memulai sesi menggunakan parameter. viewPort

Tindakan Bidang yang diperlukan Bidang opsional Deskripsi

mouseClick

x(Bilangan bulat), y (Bilangan bulat)

button(MouseButton), clickCount (Bilangan bulat)

Klik pada koordinat yang ditentukan. clickCount : 1—10. button : KIRI, KANAN, TENGAH.

mouseMove

x(Bilangan bulat), y (Bilangan bulat)

—

Pindahkan kursor ke koordinat yang ditentukan.

mouseDrag

startX(Integer), startY (Integer), endX (Integer), (Integer) endY

button (MouseButton)

Seret dari posisi awal hingga akhir. buttondefault ke KIRI.

mouseScroll

x(Bilangan bulat), y (Bilangan bulat)

deltaX(Bilangan bulat), deltaY (Bilangan bulat)

Gulir pada posisi yang ditentukan. deltaX/deltaY: -1000 hingga 1000. deltaYGulungan negatif ke bawah.

Tindakan keyboard

Tindakan Bidang yang diperlukan Bidang opsional Deskripsi

keyType

text (String)

—

Ketik string teks. Panjang maksimum: 10.000 karakter.

keyPress

key (String)

presses(Bilangan bulat)

Tekan tombol N kali. presses : 1—100. Default ke 1.

keyShortcut

keys (KeyList)

—

Tekan kombinasi tombol (misalnya,["ctrl", "s"]). Maksimal 5 kunci.

Tindakan tangkapan layar

Tindakan Bidang yang diperlukan Bidang opsional Deskripsi

screenshot

—

format (ScreenshotFormat)

Tangkap desktop OS penuh (bukan hanya viewport browser). Format: PNG saja.

Pertimbangan-pertimbangan

  • ASCII-only masukan teks: keyType Tindakan hanya mendukung karakter ASCII. Non-ASCII karakter (seperti Unicode atau karakter multi-byte) dilewati selama input.

  • Tidak ada validasi nama kunci: keyShortcut Tindakan keyPress dan tidak memvalidasi apakah nama kunci yang ditentukan didukung. Jika Anda memberikan nama kunci yang tidak dikenal, API akan mengembalikan status SUCCESS tanpa melakukan tindakan yang diinginkan. Lihat nama kunci yang didukung yang tercantum di atas.

  • Nama kunci yang didukung: Nama kunci untuk keyPress dan keyShortcut tindakan harus dalam huruf kecil. Kunci yang didukung termasuk karakter tunggal (a0—z, —9), dan kunci bernama sepertienter,tab,space,backspace,delete,escape,ctrl,alt,shift.

Format permintaan dan respons

Permintaan

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

Badan permintaan berisi action bidang dengan tepat satu anggota kumpulan BrowserAction serikat:

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

Respons

sessionIdDikembalikan melalui header x-amzn-browser-session-id respon. Badan respons berisi result bidang dengan hasil tindakan yang sesuai.

Tentang kesuksesan:

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

Pada kegagalan, status bidang diatur ke GAGAL dan error bidang berisi deskripsi kegagalan.

Contoh

Contoh berikut menunjukkan cara menjalankan tindakan browser menggunakan AWS CLI AWS , SDK for Python (Boto3), dan API.

contoh
AWS CLI

  1. Untuk mengklik pada posisi tertentu:

    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}}'

    Untuk mengetik teks:

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

    Untuk menekan pintasan keyboard:

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

    Untuk mengambil tangkapan layar:

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

  1. Untuk mengklik pada posisi tertentu:

    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']}")

    Untuk mengetik teks:

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

    Untuk mengambil tangkapan layar dan menyimpannya:

    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

  1. Untuk mengklik pada posisi tertentu:

    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
        }
    }
  }'

    Untuk mengambil tangkapan layar:

    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"
        }
    }
  }'