actionbook__actionbook/packages/dify-plugin/tools/browser_operator.yaml

identity:
  name: browser_operator
  author: actionbook
  label:
    en_US: Browser Operator
description:
  human:
    en_US: Perform browser page operations (navigate, click, type, snapshot, etc.).
  llm: >
    Browser operator for page interactions. Choose an action and provide its required params.

    ACTIONS:
    - navigate: requires url. Goes to URL; returns page title and URL.
    - click: requires selector. Clicks element (10s timeout). On "not found", use snapshot.
    - type: requires selector, text. Types text key-by-key (appends).
    - fill: requires selector. Optional text (empty="" clears). Clears then fills atomically (preferred for forms).
    - select: requires selector, value. Picks <option> by value attribute.
    - press_key: requires key. Sends key (Enter, Tab, Escape, ArrowDown, etc.).
    - hover: requires selector. Triggers hover on element.
    - snapshot: no params. Returns accessibility tree with [ref=eN] labels for all interactive elements.
    - get_text: optional selector. Visible text of element or body.
    - get_html: optional selector. HTML of element or full page.
    - wait: requires selector. Waits for element in DOM.
    - wait_navigation: optional timeout_ms. Waits for navigation to complete.
    - go_back / go_forward / reload: no params. History navigation or page reload.

    USING REFS (most important — most reliable selectors):
    Snapshot output example:
      - textbox "Email" [ref=e2]
      - button "Sign In" [ref=e3]
    Use [ref=eN] directly as selector: selector="[ref=e3]" to click Sign In,
    selector="[ref=e2]" with text="user@example.com" to fill Email.
    Refs re-walk the DOM so they always match the correct element.

    WHEN TO USE SNAPSHOT:
    After navigating to a new page, when a selector fails ("Element not found"),
    when search_actions has no results, or after page state changes (form submit, modal, navigation).

    OTHER SELECTOR FORMATS (when refs unavailable):
    button:has-text("X"), a:has-text("X"), text="exact", [aria-label="X"], #id, //xpath.
    Avoid .nth(), :nth-match(), :text() — these are invalid.

    FORM TIPS: Use fill with [ref=eN]; submit with press_key Enter (more reliable than clicking submit).

    SESSION CLEANUP (critical): ALWAYS call browser_stop_session when done (success or failure) to release resources.

    TIMEOUTS: click defaults to 10s, navigate to 30s. Override with timeout_ms.

    Pass BOTH session_id and cdp_url on each call for best reliability.
parameters:
  - name: session_id
    type: string
    required: false
    label:
      en_US: Session ID
    human_description:
      en_US: Session ID from browser_create_session. Preferred for multi-step operations — reuses the same CDP connection.
    llm_description: >
      Session ID returned by browser_create_session. Use this for multi-step
      workflows (navigate → fill → click → snapshot) within one session.
      The connection is kept alive between calls. Either session_id or cdp_url
      is required; session_id is preferred.
    form: llm
  - name: cdp_url
    type: string
    required: false
    label:
      en_US: CDP WebSocket URL
    human_description:
      en_US: WebSocket endpoint from browser_create_session (ws_endpoint field). Fallback for one-shot operations.
    llm_description: >
      WebSocket CDP endpoint. Fallback when session_id is not available.
      Each call creates a new connection and closes it after. For multi-step
      workflows, prefer session_id instead.
    form: llm
  - name: action
    type: select
    required: true
    options:
      - value: navigate
        label:
          en_US: navigate
      - value: click
        label:
          en_US: click
      - value: type
        label:
          en_US: type
      - value: fill
        label:
          en_US: fill
      - value: select
        label:
          en_US: select
      - value: press_key
        label:
          en_US: press_key
      - value: hover
        label:
          en_US: hover
      - value: snapshot
        label:
          en_US: snapshot
      - value: get_text
        label:
          en_US: get_text
      - value: get_html
        label:
          en_US: get_html
      - value: wait
        label:
          en_US: wait
      - value: wait_navigation
        label:
          en_US: wait_navigation
      - value: go_back
        label:
          en_US: go_back
      - value: go_forward
        label:
          en_US: go_forward
      - value: reload
        label:
          en_US: reload
    label:
      en_US: Action
    human_description:
      en_US: The browser operation to perform.
    llm_description: >
      Browser action to perform. See tool description for required parameters per action.
    form: llm
  - name: url
    type: string
    required: false
    label:
      en_US: URL
    human_description:
      en_US: Target URL for navigate action (must start with http:// or https://).
    llm_description: >
      Required for action=navigate. Full URL to navigate to (must start with http:// or https://).
    form: llm
  - name: selector
    type: string
    required: false
    label:
      en_US: CSS Selector
    human_description:
      en_US: CSS selector for the target element. Required for click, type, fill, select, hover, wait. Optional for get_text, get_html.
    llm_description: >
      CSS selector for the target element.
      Required for: click, type, fill, select, hover, wait.
      Optional for: get_text (defaults to body text), get_html (defaults to full page HTML).
      Use selectors from search_actions or get_action_by_area_id results.
    form: llm
  - name: text
    type: string
    required: false
    label:
      en_US: Text
    human_description:
      en_US: Text to type or fill. Required for type and fill actions.
    llm_description: >
      Text content to input.
      Required for action=type (appends text key-by-key to existing content).
      For action=fill: sets the field value atomically. Pass empty string "" to clear the field.
    form: llm
  - name: value
    type: string
    required: false
    label:
      en_US: Select Option Value
    human_description:
      en_US: The value attribute of the <option> to select. Required for select action.
    llm_description: >
      Required for action=select. The value attribute of the <option> to choose.
      Example: "US" for <option value="US">United States</option>
    form: llm
  - name: key
    type: string
    required: false
    label:
      en_US: Key
    human_description:
      en_US: Keyboard key to press. Required for press_key action.
    llm_description: >
      Required for action=press_key. Keyboard key name to press.
      Examples: Enter, Tab, Escape, Space, Backspace, Delete,
      ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown.
    form: llm
  - name: timeout_ms
    type: number
    required: false
    default: 30000
    label:
      en_US: Timeout (ms)
    human_description:
      en_US: Operation timeout in milliseconds (default 30000).
    llm_description: >
      Timeout in milliseconds. Only used by these actions:
      navigate (page load timeout, default 30s), click (wait-for-element timeout, default 10s),
      wait (wait-for-selector timeout, default 30s), wait_navigation (load timeout, default 30s).
      Ignored by other actions.
    form: llm
extra:
  python:
    source: tools/browser_operator.py