View a markdown version of this page

Action du système d'exploitation du navigateur - Amazon Bedrock AgentCore
Présentation deActions prises en chargeConsidérationsFormat de demande et de réponseExemples

Action du système d'exploitation du navigateur

L' InvokeBrowser API fournit un contrôle direct au niveau du système d'exploitation sur les sessions du navigateur Amazon Bedrock AgentCore . Alors que le point de terminaison WebSocket-based d'automatisation utilise le DevTools protocole Chrome (CDP) pour l'interaction avec le navigateur, il InvokeBrowser fonctionne au niveau du système d'exploitation et permet des actions que le CDP ne peut pas gérer, telles que l'interaction avec les boîtes de dialogue d'impression, les raccourcis clavier, les menus contextuels avec le bouton droit de la souris, les JavaScript alertes et la capture de captures d'écran en plein écran.

Présentation de

Le AgentCore navigateur Amazon Bedrock propose deux manières d'interagir avec une session de navigateur :

  • WebSocket-based automatisation (CDP) : utilise le DevTools protocole Chrome sur une WebSocket connexion. C'est idéal pour les tâches d'automatisation de navigateur standard telles que la navigation dans les pages, le clic sur les éléments du DOM, le remplissage de formulaires et l'extraction du contenu des pages. Des bibliothèques telles que Playwright et Browser-Use se connectent via ce point de terminaison.

  • OS-level actions (InvokeBrowser) : utilise une API REST pour effectuer des interactions au niveau du système d'exploitation via des actions de souris, de clavier et de capture d'écran. Cela complète le CDP en gérant les scénarios dans lesquels l'automatisation au niveau du navigateur est insuffisante.

À utiliser InvokeBrowser lorsque votre agent doit :

  • Interagissez avec les boîtes de dialogue natives du système d'exploitation, telles que les boîtes de dialogue d'impression, les upload/download boîtes de dialogue de fichiers ou les invites d'authentification situées en dehors du DOM du navigateur

  • Ignorer les JavaScript alertes, les confirmations ou les invites bloquant l'exécution du CDP

  • Utilisez les raccourcis clavier (par exemple, ctrl+a, ctrl+p) qui déclenchent un comportement OS-level

  • Interagissez avec les menus contextuels affichés par le système d'exploitation avec le bouton droit de la souris

  • Capturez des captures d'écran complètes du bureau qui incluent du contenu en dehors de la fenêtre d'affichage du navigateur, comme les notifications du système d'exploitation ou les mises en page à fenêtres multiples

  • Effectuez des opérations de glisser-déposer qui s'étendent sur plusieurs fenêtres du navigateur ou entre le navigateur et le bureau

InvokeBrowser suit le même schéma que InvokeCodeInterpreter : une seule opération unifiée avec envoi de type action. Vous envoyez une demande avec une seule action et recevez le résultat correspondant.

Actions prises en charge

InvokeBrowser prend en charge les types d'actions suivants par le biais de l'BrowserActionunion. Un seul membre d'action doit être défini par demande.

Actions de la souris

Pour toutes les actions de la souris, les valeurs de coordonnées (x,y) doivent être strictement comprises dans les limites de la fenêtre d'affichage de la session du navigateur. Les plages valides sont 1 < x < fenêtre d'affichage Width-2 et 1 < y < fenêtre d'affichageHeight-2. La taille de la fenêtre d'affichage par défaut est de 1456 × 819 pixels, ce qui peut être configuré lors du démarrage d'une session à l'aide du paramètre. viewPort

Action Champs obligatoires Champs facultatifs Description

mouseClick

x(Entier), y (Entier)

button(MouseButton), clickCount (Entier)

Cliquez sur les coordonnées spécifiées. clickCount : 1 à 10. button : GAUCHE, DROITE, MILIEU.

mouseMove

x(Entier), y (Entier)

—

Déplace le curseur sur les coordonnées spécifiées.

mouseDrag

startX(Entier), startY (Entier), endX (Entier), endY (Entier)

button (MouseButton)

Faites glisser le pointeur de la position initiale à la position finale. buttonla valeur par défaut est LEFT.

mouseScroll

x(Entier), y (Entier)

deltaX(Entier), deltaY (Entier)

Faites défiler la page jusqu'à la position spécifiée. deltaX/deltaY: -1000 à 1000. Le négatif deltaY défile vers le bas.

Actions du clavier

Action Champs obligatoires Champs facultatifs Description

keyType

text (chaîne)

—

Tapez une chaîne de texte. Longueur maximale : 10 000 caractères.

keyPress

key (chaîne)

presses(Entier)

Appuyez N fois sur une touche. presses : 1 à 100. La valeur par défaut est 1.

keyShortcut

keys (KeyList)

—

Appuyez sur une combinaison de touches (par exemple,["ctrl", "s"]). 5 touches maximum.

Action de capture d'écran

Action Champs obligatoires Champs facultatifs Description

screenshot

—

format (ScreenshotFormat)

Capturez l'intégralité du bureau du système d'exploitation (et pas seulement la fenêtre d'affichage du navigateur). Format : PNG uniquement.

Considérations

  • ASCII-only saisie de texte : l'keyTypeaction ne prend en charge que les caractères ASCII. Non-ASCII les caractères (tels que les caractères Unicode ou multi-octets) sont ignorés lors de la saisie.

  • Aucune validation du nom de clé : les keyShortcut actions keyPress et ne permettent pas de vérifier si les noms de clé spécifiés sont pris en charge. Si vous fournissez un nom de clé inconnu, l'API renvoie le statut SUCCESS sans effectuer l'action prévue. Reportez-vous aux noms de clés pris en charge répertoriés ci-dessus.

  • Noms de clé pris en charge : les noms des clés keyPress et keyShortcut des actions doivent être en minuscules. Les touches prises en charge incluent des caractères uniques (a0—z, —9) et des clés nommées telles que enter tabspace,backspace,delete,,escape,ctrl,alt,shift.

Format de demande et de réponse

Demande

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

Le corps de la demande contient un action champ contenant exactement un membre de l'ensemble d'BrowserActionunions :

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

Réponse

Le sessionId est renvoyé via l'en-tête de x-amzn-browser-session-id réponse. Le corps de la réponse contient un result champ avec le résultat de l'action correspondant.

En cas de réussite :

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

En cas d'échec, le status champ est défini sur error FAILED et contient une description de l'échec.

Exemples

Les exemples suivants montrent comment invoquer des actions de navigateur à l'aide de la AWS CLI, du AWS SDK pour Python (Boto3) et de l'API.

Exemple
AWS CLI

  1. Pour cliquer à une position précise :

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

    Pour saisir du texte :

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

    Pour appuyer sur un raccourci clavier :

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

    Pour prendre une capture d'écran :

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

  1. Pour cliquer à une position précise :

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

    Pour saisir du texte :

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

    Pour prendre une capture d'écran et l'enregistrer :

    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. Pour cliquer à une position précise :

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

    Pour prendre une capture d'écran :

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