View a markdown version of this page

Aktion des Browserbetriebssystems - Amazon Grundgestein AgentCore
-ÜbersichtUnterstützte AktionenÜberlegungenAnforderungs- und AntwortformateBeispiele

Aktion des Browserbetriebssystems

Die InvokeBrowser API bietet direkte Kontrolle über Amazon Bedrock AgentCore Browser-Sitzungen auf Betriebssystemebene. Der WebSocket-based Automatisierungsendpunkt verwendet zwar DevTools das Chrome-Protokoll (CDP) für die Browserinteraktion, InvokeBrowser arbeitet aber auf Betriebssystemebene und ermöglicht Aktionen, die CDP nicht ausführen kann — wie die Interaktion mit Druckdialogen, Tastenkombinationen, Kontextmenüs mit der rechten Maustaste, JavaScript Benachrichtigungen und das Aufnehmen von Screenshots im Vollbildmodus.

-Übersicht

Der Amazon Bedrock AgentCore Browser bietet zwei Möglichkeiten, mit einer Browsersitzung zu interagieren:

  • WebSocket-based Automatisierung (CDP): Verwendet das DevTools Chrome-Protokoll über eine WebSocket Verbindung. Dies ist ideal für Standardaufgaben zur Browserautomatisierung wie das Navigieren auf Seiten, das Klicken auf DOM-Elemente, das Ausfüllen von Formularen und das Extrahieren von Seiteninhalten. Bibliotheken wie Playwright und Browser-Use stellen über diesen Endpunkt eine Verbindung her.

  • OS-level actions (InvokeBrowser): Verwendet eine REST-API, um Interaktionen auf Betriebssystemebene über Maus-, Tastatur- und Screenshot-Aktionen durchzuführen. Dies ergänzt CDP durch die Behandlung von Szenarien, in denen die Automatisierung auf Browserebene unzureichend ist.

Verwenden Sie InvokeBrowser es, wenn Ihr Agent:

  • Interagieren Sie mit systemeigenen Betriebssystemdialogfeldern wie Druckdialogen, upload/download Dateidialogfeldern oder Authentifizierungsaufforderungen, die sich außerhalb des Browser-DOM befinden

  • Verwerfen Sie JavaScript Warnungen, Bestätigungen oder Eingabeaufforderungen, die die CDP-Ausführung blockieren

  • Verwenden Sie Tastenkombinationen (z. B. Strg+A, Strg+P), die ein Verhalten auslösen OS-level

  • Interagieren Sie mit Rechtsklick-Kontextmenüs, die vom Betriebssystem gerendert werden

  • Erfassen Sie vollständige Desktop-Screenshots, die Inhalte außerhalb des Browser-Viewports enthalten, wie z. B. Betriebssystembenachrichtigungen oder Layouts mit mehreren Fenstern

  • Führen Sie Drag-and-Drop-Operationen durch, die sich über Browserfenster oder zwischen Browser und Desktop erstrecken

InvokeBrowser folgt dem gleichen Muster wie InvokeCodeInterpreter: ein einziger einheitlicher Vorgang mit Versand vom Typ Aktion. Sie senden eine Anfrage mit genau einer Aktion und erhalten ein entsprechendes Ergebnis.

Unterstützte Aktionen

InvokeBrowser unterstützt über die BrowserAction Union die folgenden Aktionstypen. Pro Anfrage muss genau ein Aktionsmitglied festgelegt werden.

Aktionen mit der Maus

Bei allen Mausaktionen müssen die Koordinatenwerte (x,y) genau innerhalb der Grenzen des Viewports der Browsersitzung liegen. Gültige Bereiche sind 1 < x < Viewport Width-2 und 1 < y < Viewport. Height-2 Die Standardgröße des Viewports ist 1456×819 Pixel. Sie kann beim Starten einer Sitzung mithilfe des Parameters konfiguriert werden. viewPort

Action Pflichtfelder Optionale Felder Description

mouseClick

x(Ganzzahl), (Ganzzahl) y

button(MouseButton), clickCount (Ganzzahl)

Klicken Sie auf die angegebenen Koordinaten. clickCount : 1—10. button : LINKS, RECHTS, MITTE.

mouseMove

x(Ganzzahl), y (Ganzzahl)

—

Bewegt den Cursor zu den angegebenen Koordinaten.

mouseDrag

startX(Ganzzahl), startY (Ganzzahl), endX (Ganzzahl), endY (Ganzzahl)

button (MouseButton)

Ziehen Sie von der Start- zur Endposition. buttonist standardmäßig LINKS.

mouseScroll

x(Ganzzahl), y (Ganzzahl)

deltaX(Ganzzahl), deltaY (Ganzzahl)

Scrollen Sie an der angegebenen Position. deltaX/deltaY: -1000 bis 1000. Negativ deltaY scrollt nach unten.

Aktionen auf der Tastatur

Action Pflichtfelder Optionale Felder Description

keyType

text (Zeichenfolge)

—

Geben Sie eine Textfolge ein. Maximale Länge: 10.000 Zeichen.

keyPress

key (Zeichenfolge)

presses(Ganzzahl)

Drücken Sie N-mal eine Taste. presses : 1—100. Standardeinstellung: 1.

keyShortcut

keys (KeyList)

—

Drücken Sie eine Tastenkombination (z. B.["ctrl", "s"]). Maximal 5 Tasten.

Screenshot-Aktion

Action Pflichtfelder Optionale Felder Description

screenshot

—

format (ScreenshotFormat)

Erfassen Sie den gesamten Betriebssystem-Desktop (nicht nur den Browser-Viewport). Format: Nur PNG.

Überlegungen

  • ASCII-only Texteingabe: Die keyType Aktion unterstützt nur ASCII-Zeichen. Non-ASCII Zeichen (wie Unicode- oder Multibyte-Zeichen) werden bei der Eingabe übersprungen.

  • Keine Überprüfung von Schlüsselnamen: Die keyShortcut Aktionen keyPress und überprüfen nicht, ob die angegebenen Schlüsselnamen unterstützt werden. Wenn Sie einen unbekannten Schlüsselnamen angeben, gibt die API den Status SUCCESS zurück, ohne die beabsichtigte Aktion auszuführen. Sehen Sie sich die oben aufgeführten unterstützten Schlüsselnamen an.

  • Unterstützte Schlüsselnamen: Die Schlüsselnamen für keyPress und keyShortcut Aktionen müssen in Kleinbuchstaben geschrieben werden. Zu den unterstützten Schlüsseln gehören einzelne Zeichen (a0—z, —9) und benannte Schlüssel wie entertab,,space,backspace,delete,escape, ctrlalt,shift.

Anforderungs- und Antwortformate

Anforderung

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

Der Anfragetext enthält ein action Feld mit genau einem Mitglied des BrowserAction Union-Sets:

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

Antwort

Das sessionId wird über den x-amzn-browser-session-id Antwort-Header zurückgegeben. Der Antworttext enthält ein result Feld mit dem entsprechenden Aktionsergebnis.

Bei Erfolg:

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

Bei einem Fehler wird das status Feld auf FAILED gesetzt und das error Feld enthält eine Beschreibung des Fehlers.

Beispiele

Die folgenden Beispiele zeigen, wie Browseraktionen mithilfe der AWS CLI, des AWS SDK for Python (Boto3) und der API aufgerufen werden.

Beispiel
AWS CLI

  1. Um auf eine bestimmte Position zu klicken:

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

    Um Text einzugeben:

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

    Um eine Tastenkombination zu drücken:

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

    Um einen Screenshot zu machen:

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

  1. Um auf eine bestimmte Position zu klicken:

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

    Um Text einzugeben:

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

    Um einen Screenshot aufzunehmen und zu speichern:

    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. Um auf eine bestimmte Position zu klicken:

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

    Um einen Screenshot zu machen:

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