View a markdown version of this page

Tindakan OS browser - Batu Dasar Amazon AgentCore
Gambaran umumTindakan yang didukungPertimbangan-pertimbanganFormat permintaan dan tanggapanContoh

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

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 di tingkat OS, memungkinkan tindakan yang tidak dapat ditangani CDP — seperti berinteraksi dengan dialog cetak, pintasan keyboard, menu konteks klik kanan, JavaScript peringatan, dan menangkap tangkapan layar layar penuh.

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 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 tangkapan layar. 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

  • Menutup JavaScript peringatan, konfirmasi, atau perintah yang memblokir eksekusi CDP

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

  • Berinteraksi dengan menu konteks klik kanan yang dirender 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 < view Height-2 port. Ukuran viewport default adalah 1456×819 piksel, yang dapat dikonfigurasi saat memulai sesi menggunakan parameter. viewPort

Tindakan Bidang wajib Bidang opsional Deskripsi

mouseClick

x(Integer), y (Integer)

button(MouseButton), clickCount (Integer)

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

mouseMove

x(Integer), y (Integer)

—

Pindahkan kursor ke koordinat yang ditentukan.

mouseDrag

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

button (MouseButton)

Seret dari posisi awal ke akhir. buttonDefaultnya adalah KIRI.

mouseScroll

x(Integer), y (Integer)

deltaX(Integer), deltaY (Integer)

Gulir pada posisi yang ditentukan. deltaX/deltaY: -1000 hingga 1000. Negatif ber deltaY gulir ke bawah.

Tindakan keyboard

Tindakan Bidang wajib Bidang opsional Deskripsi

keyType

text (String)

—

Ketik string teks. Panjang maksimum: 10.000 karakter.

keyPress

key (String)

presses(Integer)

Tekan tombol N kali. presses : 1—100. Defaultnya 1.

keyShortcut

keys (KeyList)

—

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

Tindakan tangkapan layar

Tindakan Bidang wajib Bidang opsional Deskripsi

screenshot

—

format (ScreenshotFormat)

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

Pertimbangan-pertimbangan

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

  • Tidak ada validasi nama kunci: keyPress T keyShortcut indakan dan tidak memvalidasi apakah nama kunci yang ditentukan didukung. Jika Anda memberikan nama kunci yang tidak dikenali, API mengembalikan status SUKSES 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 tanggapan

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 dari kum BrowserAction pulan serikat:

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

Respons

Ini sessionId dikembalikan melalui header x-amzn-browser-session-id respons. Badan respons berisi result bidang dengan hasil tindakan yang sesuai.

Tentang kesuksesan:

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

Pada kegagalan, status bidang disetel ke FAILED dan error bidang berisi deskripsi kegagalan.

Contoh

Contoh berikut menunjukkan cara memanggil tindakan browser menggunakan AWS CLI, AWS SDK untuk 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"
        }
    }
  }'