Panoramica di Azioni supportate Considerazioni Formati di richieste e risposte Esempi

Azione del sistema operativo del browser

L' InvokeBrowser API fornisce il controllo diretto a livello di sistema operativo sulle sessioni di Amazon Bedrock AgentCore Browser. 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 cliccati con il pulsante destro del mouse, gli avvisi e l'acquisizione di schermate a schermo intero. JavaScript

Panoramica di

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

WebSocket-based automazione (CDP): utilizza il DevTools protocollo Chrome su una WebSocket connessione. È ideale per le attività standard di automazione del browser come la navigazione delle pagine, il clic sugli elementi DOM, la compilazione di moduli e l'estrazione del contenuto delle pagine. 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 il 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, ad esempio le finestre di dialogo di stampa, le finestre di dialogo dei file o le upload/download richieste di autenticazione che si trovano all'esterno del DOM del browser
Ignora JavaScript avvisi, conferme o prompt che bloccano l'esecuzione del CDP
Usa 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
Acquisisci schermate complete del desktop che includono contenuti al di fuori della finestra del browser, ad esempio notifiche del sistema operativo o layout con più finestre
Esegui operazioni di trascinamento che si estendono su tutte le 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 azione. Invii una richiesta con esattamente un'azione e ricevi un risultato corrispondente.

Azioni supportate

InvokeBrowser supporta i seguenti tipi di azione 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 della finestra è di 1456×819 pixel, che può essere configurata all'avvio di una sessione utilizzando il parametro. viewPort

Azione	Campi obbligatori	Campi facoltativi	Description
`mouseClick`	`x`(Intero), (Intero) `y`	`button`(MouseButton), (Numero intero`clickCount`)	Fate clic sulle coordinate specificate. `clickCount` : da 1 a 10. `button` : SINISTRA, DESTRA, CENTRALE.
`mouseMove`	`x`(Intero), `y` (Intero)	—	Sposta il cursore sulle coordinate specificate.
`mouseDrag`	`startX`(Intero), `startY` (Intero), (Intero), `endX` (Intero) `endY`	`button` (MouseButton)	Trascinate dalla posizione iniziale a quella finale. `button`il valore predefinito è LEFT.
`mouseScroll`	`x`(Intero), (Intero`y`)	`deltaX`(Intero), (Intero`deltaY`)	Scorri nella posizione specificata. `deltaX`/`deltaY`: da -1000 a 1000. Il valore 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` : da 1 a 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 saltati durante l'immissione.
Nessuna convalida del nome chiave: le keyShortcut azioni keyPress e non convalidano se i nomi di chiave specificati sono supportati. Se si fornisce un nome di chiave non riconosciuto, l'API restituisce lo stato RIUSCITO senza eseguire l'azione prevista. Fai riferimento ai nomi di chiave supportati elencati sopra.
Nomi delle chiavi supportati: i nomi delle chiavi keyPress e keyShortcut delle 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 del set di BrowserAction unione:


{
    "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 viene 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, l' AWS SDK for Python (Boto3) e l'API.

Esempio

AWS CLI

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 del 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

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 del 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

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

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Autorità di certificazione principale

Configurazioni del file system