View a markdown version of this page

Azione del sistema operativo del browser - Amazon Bedrock AgentCore
Panoramica diAzioni supportateConsiderazioniFormati di richieste e risposteEsempi

Azione del sistema operativo del browser

L' InvokeBrowser API fornisce il controllo diretto a livello di sistema operativo sulle sessioni del browser Amazon Bedrock AgentCore . Sebbene l'endpoint di WebSocket-based automazione utilizzi il DevTools protocollo Chrome (CDP) per l'interazione con il browser, InvokeBrowser opera a livello di sistema operativo, abilitando azioni che CDP non è in grado di gestire, come l'interazione con le finestre di dialogo di stampa, le scorciatoie da tastiera, i menu contestuali con il pulsante destro del mouse, gli avvisi e l'acquisizione di schermate a schermo intero. JavaScript

Panoramica di

Amazon Bedrock AgentCore Browser offre due modi per interagire con una sessione del browser:

  • WebSocket-based automazione (CDP): utilizza il DevTools protocollo Chrome tramite una WebSocket connessione. È ideale per le attività standard di automazione del browser, come la navigazione tra le pagine, il clic sugli elementi DOM, la compilazione di moduli e l'estrazione del contenuto della pagina. Librerie come Playwright e Browser-use si connettono tramite questo endpoint.

  • OS-level actions (InvokeBrowser): utilizza un'API REST per eseguire interazioni a livello di sistema operativo tramite mouse, tastiera e azioni di screenshot. Ciò integra CDP gestendo scenari in cui l'automazione a livello di browser è insufficiente.

Utilizzalo InvokeBrowser quando il tuo agente deve:

  • Interagisci con le finestre di dialogo native del sistema operativo, come le finestre di dialogo di stampa, le finestre di upload/download dialogo dei file o le richieste di autenticazione esterne al DOM del browser

  • Ignora gli JavaScript avvisi, le conferme o i prompt che bloccano l'esecuzione di CDP

  • Utilizzate le scorciatoie da tastiera (ad esempio, ctrl+a, ctrl+p) che attivano il comportamento OS-level

  • Interagisci con i menu contestuali visualizzati con il pulsante destro del mouse dal sistema operativo

  • Cattura schermate complete del desktop che includono contenuti esterni alla finestra del browser, come notifiche del sistema operativo o layout a più finestre

  • Esegui operazioni di trascinamento che si estendono su più finestre del browser o tra il browser e il desktop

InvokeBrowser segue lo stesso schema di InvokeCodeInterpreter: una singola operazione unificata con invio di tipo di azione. Invii una richiesta con esattamente un'azione e ricevi un risultato corrispondente.

Azioni supportate

InvokeBrowser supporta i seguenti tipi di azioni tramite l'BrowserActionunione. È necessario impostare esattamente un membro dell'azione per richiesta.

Azioni del mouse

Per tutte le azioni del mouse, i valori delle coordinate (x,y) devono rientrare rigorosamente nei limiti della finestra della sessione del browser. Gli intervalli validi sono 1 < x < viewport Width-2 e 1 < y < viewport. Height-2 La dimensione predefinita del viewport è 1456×819 pixel, che può essere configurata all'avvio di una sessione utilizzando il parametro. viewPort

Azione Campi obbligatori Campi facoltativi Description

mouseClick

x(Numero intero), (Numero intero) y

button(MouseButton), (Numero interoclickCount)

Fate clic sulle coordinate specificate. clickCount : 1—10. button : SINISTRA, DESTRA, CENTRALE.

mouseMove

x(Numero intero), y (Numero intero)

—

Sposta il cursore sulle coordinate specificate.

mouseDrag

startX(Intero), startY (Intero), (Intero), endX (Intero) endY

button (MouseButton)

Trascina dalla posizione iniziale a quella finale. buttonil valore predefinito è SINISTRA.

mouseScroll

x(Numero intero), y (Numero intero)

deltaX(Numero intero), deltaY (Numero intero)

Scorri fino alla posizione specificata. deltaX/deltaY: da -1000 a 1000. Il negativo deltaY scorre verso il basso.

Azioni da tastiera

Azione Campi obbligatori Campi facoltativi Description

keyType

text (stringa)

—

Digita una stringa di testo. Lunghezza massima: 10.000 caratteri.

keyPress

key (stringa)

presses(Numero intero)

Premere un tasto N volte. presses : 1—100. L'impostazione predefinita è 2.

keyShortcut

keys (KeyList)

—

Premere una combinazione di tasti (ad esempio,["ctrl", "s"]). Massimo 5 tasti.

Azione screenshot

Azione Campi obbligatori Campi facoltativi Description

screenshot

—

format (ScreenshotFormat)

Cattura l'intero desktop del sistema operativo (non solo la finestra del browser). Formato: solo PNG.

Considerazioni

  • ASCII-only immissione di testo: l'keyTypeazione supporta solo caratteri ASCII. Non-ASCII i caratteri (come i caratteri Unicode o multibyte) vengono ignorati durante l'immissione.

  • Nessuna convalida dei nomi di chiave: le keyShortcut azioni keyPress and non convalidano se i nomi di chiave specificati sono supportati. Se fornite un nome di chiave non riconosciuto, l'API restituisce lo stato SUCCESS senza eseguire l'azione prevista. Fate riferimento ai nomi chiave supportati elencati sopra.

  • Nomi chiave supportati: i nomi delle chiavi keyPress e le keyShortcut azioni devono essere in minuscolo. Le chiavi supportate includono caratteri singoli (a—z, 0 —9) e chiavi denominate comeenter,,tab,space,,backspace,delete, escapectrl,alt. shift

Formati di richieste e risposte

Richiesta

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

Il corpo della richiesta contiene un action campo con esattamente un membro dell'BrowserActionunion set:

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

Risposta

sessionIdViene restituito tramite l'intestazione della x-amzn-browser-session-id risposta. Il corpo della risposta contiene un result campo con il risultato dell'azione corrispondente.

In caso di successo:

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

In caso di errore, il status campo è impostato su FAILED e contiene una descrizione dell'errore. error

Esempi

Gli esempi seguenti mostrano come richiamare le azioni del browser utilizzando la AWS CLI AWS , SDK for Python (Boto3) e l'API.

Esempio
AWS CLI

  1. Per fare clic in una posizione specifica:

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

    Per digitare il testo:

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

    Per premere una scorciatoia da tastiera:

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

    Per fare uno screenshot:

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

  1. Per fare clic in una posizione specifica:

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

    Per digitare il testo:

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

    Per fare uno screenshot e salvarlo:

    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. Per fare clic in una posizione specifica:

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

    Per fare uno screenshot:

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