Skip to content

JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.

Python
5.2 KB
Raw Blame

Browser tools

1. Overview

JiuwenSwarm browser tools drive a real Chrome instance for navigation, form filling, clicks, uploads, and other web tasks.

Chrome is managed by the browser agent. The user configures the Chrome executable and display mode in the web UI, and the agent starts the browser on the first browser task. There is no separate browser service to start from the frontend.

The managed browser can:

  • Open pages and wait for loading
  • Click elements, enter text, and upload files
  • Execute multi-step web tasks
  • Reuse a session and its login state
  • Read page titles, URLs, and page content

2. Quick start

2.1 Install Chrome

Install Google Chrome on the machine that runs JiuwenSwarm. The managed driver normally detects a standard Chrome installation automatically.

If Chrome is installed in a custom location, open chrome://version, copy the Executable Path, and use it in the next step.

2.2 Configure the browser

  1. Open the JiuwenSwarm web UI.
  2. Go to Settings > Browser.
  3. Optionally enter the full Chrome executable path. Leave it empty to use automatic detection.
  4. Enable Show browser when you need to see or manually authenticate in the managed browser. Disable it for headless execution.
  5. Save the settings.

Changing the display mode restarts the browser runtime when necessary so the next task uses the selected mode.

2.3 Run a browser task

Ask the agent to open a page, extract information, fill a form, or continue an authenticated workflow. The browser agent starts and owns Chrome automatically.

In visible mode, the Chrome window appears when the first browser task starts. Complete login, MFA, or other required manual authorization in that window, then continue the task in the conversation.

3. Usage guidance

  • Keep the same agent session for long workflows that depend on login state.
  • Use visible mode for manual login, MFA, QR codes, and authorization prompts.
  • Use headless mode for tasks that do not require manual interaction.
  • Do not start a separate Chrome with a fixed debugging port for normal JiuwenSwarm usage. The managed driver selects and injects the correct CDP endpoint.
  • Keep BROWSER_ALLOW_SHORT_TIMEOUT_OVERRIDE=0 unless short browser task timeouts are explicitly required.

4. Examples

4.1 Extract web information

  1. Ask: "Extract today's headlines and summaries from https://example.com/news."
  2. The agent starts the managed browser, visits the page, and returns the requested information.

4.2 Send email with an attachment

  1. Enable Show browser and save the setting.
  2. Ask the agent to open Gmail.
  3. Sign in in the managed Chrome window if required.
  4. Ask the agent to compose the message and attach the file.

5. Configuration

5.1 config.yaml

Configuration Type Default Description
browser.chrome_path string/map "" Chrome executable. Empty uses automatic detection. A map may provide OS-specific paths.
browser.headless boolean true false shows the managed browser window.

Example:

browser:
  chrome_path:
    windows: "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
    macos: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
    linux: "/usr/bin/google-chrome"
  headless: true

An empty chrome_path clears any previously configured binary and lets openJiuwen detect Chrome from the system. A non-empty path is authoritative: if it does not identify a Chrome executable, browser startup reports an error instead of silently using another installation.

5.2 Advanced environment overrides

Most installations do not need these variables.

Environment variable Default Description
BROWSER_DRIVER managed in JiuwenSwarm Browser driver mode.
BROWSER_MANAGED_BINARY auto-detected Direct openJiuwen runtime override. JiuwenSwarm derives it from browser.chrome_path.
BROWSER_MANAGED_PORT 9333 Port for an unkeyed managed instance. Keyed instances allocate free ports automatically.
BROWSER_MANAGED_USER_DATA_DIR managed profile directory Overrides the managed profile directory.
BROWSER_MANAGED_ARGS derived from display mode Additional Chrome startup arguments.
BROWSER_MANAGED_KILL_EXISTING false Allows the driver to terminate a matching existing Chrome before launch. Use only when profile ownership is understood.

PLAYWRIGHT_CDP_URL is intended for explicit remote-driver setups. It is not required for the normal managed-browser flow.

6. Architecture

The browser lifecycle is:

frontend settings -> agent browser task -> managed Chrome start -> task execution -> session reuse

  • The frontend BrowserPanel only reads and saves Chrome path and display mode.
  • JiuwenSwarm maps those settings to the browser-agent runtime.
  • openJiuwen's BrowserService and ManagedBrowserDriver allocate the endpoint, start Chrome on demand, monitor it, reuse the profile, and stop it with the agent lifecycle.
  • The Playwright MCP endpoint is injected from the managed browser instance; it is not supplied by a frontend-launched browser.

This keeps browser startup, profile ownership, endpoint allocation, and cleanup under one lifecycle owner: the browser agent.