Skip to content

Agent Zero AI framework

Improve Browser Docker runtime recovery

Alessandro27aa2d8550cf
diff --git a/plugins/_browser/helpers/connector_runtime.py b/plugins/_browser/helpers/connector_runtime.py
index 3a03fafb8..80c49a133 100644
--- a/plugins/_browser/helpers/connector_runtime.py
+++ b/plugins/_browser/helpers/connector_runtime.py
@@ -84,6 +84,10 @@ _HOST_BROWSER_REMOTE_DEBUGGING_HELP = (
'enable "Allow remote debugging for this browser instance", run `/browser host on`, '
"and retry."
)
+_DOCKER_BROWSER_RECOVERY_HELP = (
+ "To use Agent Zero's internal Docker browser instead, open Browser settings and set "
+ "Browser location to Internal Docker browser, or run `/browser container` from A0 CLI."
+)
_REMOTE_DEBUGGING_ERROR_TOKENS = (
"remote debugging",
"remote-debugging",
@@ -478,10 +482,19 @@ class ConnectorBrowserRuntime:
message = "Host browser operation failed"
normalized = message.lower()
if "chrome://inspect/#remote-debugging" in normalized:
- return message
+ return _append_docker_browser_recovery(message)
if any(token in normalized for token in _REMOTE_DEBUGGING_ERROR_TOKENS):
- return f"{message}\n\n{_HOST_BROWSER_REMOTE_DEBUGGING_HELP}"
+ return _append_docker_browser_recovery(
+ f"{message}\n\n{_HOST_BROWSER_REMOTE_DEBUGGING_HELP}"
+ )
+ return _append_docker_browser_recovery(message)
+
+
+def _append_docker_browser_recovery(message: str) -> str:
+ normalized = str(message or "").lower()
+ if "internal docker browser" in normalized or "/browser container" in normalized:
return message
+ return f"{message}\n\n{_DOCKER_BROWSER_RECOVERY_HELP}"
@lru_cache(maxsize=1)
diff --git a/plugins/_browser/helpers/selector.py b/plugins/_browser/helpers/selector.py
index 1f348cebb..2333a4f94 100644
--- a/plugins/_browser/helpers/selector.py
+++ b/plugins/_browser/helpers/selector.py
@@ -7,6 +7,13 @@ from plugins._browser.helpers.config import RUNTIME_BACKEND_KEY, get_browser_con
from plugins._browser.helpers.runtime import get_runtime as get_container_runtime
+DOCKER_BROWSER_RECOVERY_HELP = (
+ "To use Agent Zero's internal Docker browser instead, open Browser settings and "
+ "set Browser location to Internal Docker browser, or run `/browser container` "
+ "from A0 CLI."
+)
+
+
async def get_tool_runtime(agent: Any):
context_id = str(agent.context.id)
config = get_browser_config(agent=agent)
@@ -29,7 +36,8 @@ async def get_tool_runtime(agent: Any):
+ (f": {detail}" if detail else ".")
)
raise RepairableException(
- f"{message} Connect A0 CLI to this chat, allow host browser access, and retry."
+ f"{message} Connect A0 CLI to this chat, allow host browser access, and retry. "
+ f"{DOCKER_BROWSER_RECOVERY_HELP}"
)
return await get_container_runtime(context_id)
diff --git a/plugins/_browser/webui/browser-config-store.js b/plugins/_browser/webui/browser-config-store.js
index 9c358f3f7..81fee2e85 100644
--- a/plugins/_browser/webui/browser-config-store.js
+++ b/plugins/_browser/webui/browser-config-store.js
@@ -179,6 +179,17 @@ export const store = createStore("browserConfig", {
return "Connect A0 CLI to use a host browser";
},
+ browserRuntimeStatusLabel() {
+ if (this.config?.runtime_backend !== "host_required") {
+ return "Docker browser runs inside Agent Zero; A0 CLI host-browser status does not affect it.";
+ }
+ const label = this.hostBrowserConnectorLabel();
+ if (label.startsWith("Connect A0 CLI") || label.includes("unavailable")) {
+ return `${label}. Switch Browser location to Internal Docker browser to browse without A0 CLI.`;
+ }
+ return label;
+ },
+
hasPaths() {
return this.pathCount() > 0;
},
diff --git a/plugins/_browser/webui/config.html b/plugins/_browser/webui/config.html
index d372ad529..06a711046 100644
--- a/plugins/_browser/webui/config.html
+++ b/plugins/_browser/webui/config.html
@@ -16,25 +16,39 @@
x-destroy="$store.browserConfig.cleanup()"
>
<div class="browser-config-card">
- <div class="section-title">Host Browser</div>
+ <div class="section-title">Browser Runtime</div>
<div class="section-description">
- Use Chrome, Edge, or Chromium on this computer. Keep A0 CLI connected; the browser opens when the agent first needs it.
+ Choose the internal Docker browser or a browser on the computer running A0 CLI.
</div>
<label class="browser-config-field">
<span class="browser-config-field-label">Browser location</span>
<select x-model="$store.browserConfig.config.runtime_backend">
- <option value="container">Docker browser</option>
- <option value="host_required">Bring Your Own Browser</option>
+ <option value="container">Internal Docker browser</option>
+ <option value="host_required">Host browser through A0 CLI</option>
</select>
+ <span
+ class="browser-config-field-help"
+ x-show="$store.browserConfig.config.runtime_backend !== 'host_required'"
+ >
+ Runs inside Agent Zero's Docker environment. No A0 CLI connection or host browser setup is needed.
+ </span>
<span
class="browser-config-field-help"
x-show="$store.browserConfig.config.runtime_backend === 'host_required'"
>
- Use Google Chrome or a Chromium family browser. Visit chrome://inspect/#remote-debugging and enable "Allow remote debugging".
+ Uses Chrome, Edge, or Chromium on the A0 CLI host. Keep A0 CLI connected; the browser opens when the agent first needs it.
</span>
</label>
+ <div
+ class="browser-config-note browser-config-success"
+ x-show="$store.browserConfig.config.runtime_backend !== 'host_required'"
+ >
+ <span class="material-symbols-outlined">deployed_code</span>
+ <span>Internal Docker browser selected. Host-browser CLI settings are ignored for Browser tool runs.</span>
+ </div>
+
<label
class="browser-config-field"
x-show="$store.browserConfig.config.runtime_backend === 'host_required'"
@@ -63,7 +77,10 @@
</span>
</div>
- <label class="browser-config-field">
+ <label
+ class="browser-config-field"
+ x-show="$store.browserConfig.config.runtime_backend === 'host_required'"
+ >
<span class="browser-config-field-label">Page content access</span>
<select x-model="$store.browserConfig.config.host_browser_privacy_policy">
<option value="enforce_local">Local models only</option>
@@ -75,7 +92,7 @@
<div class="browser-config-note">
<span class="material-symbols-outlined" :class="{ spinning: $store.browserConfig.hostBrowserStatusLoading }" x-text="$store.browserConfig.hostBrowserStatusLoading ? 'progress_activity' : 'captive_portal'"></span>
- <span x-text="$store.browserConfig.hostBrowserConnectorLabel()"></span>
+ <span x-text="$store.browserConfig.browserRuntimeStatusLabel()"></span>
</div>
</div>
diff --git a/tests/test_host_browser_connector.py b/tests/test_host_browser_connector.py
index 28d11cb73..572563ea1 100644
--- a/tests/test_host_browser_connector.py
+++ b/tests/test_host_browser_connector.py
@@ -32,9 +32,13 @@ def test_host_required_runtime_error_is_repairable(monkeypatch):
lambda agent=None: {"runtime_backend": "host_required"},
)
- with pytest.raises(browser_selector.RepairableException, match="Bring Your Own Browser"):
+ with pytest.raises(browser_selector.RepairableException, match="Bring Your Own Browser") as exc_info:
asyncio.run(browser_selector.get_tool_runtime(_agent("ctx-host-required-missing")))
+ message = str(exc_info.value)
+ assert "Internal Docker browser" in message
+ assert "/browser container" in message
+
def test_host_browser_metadata_selection_is_context_scoped():
sid = "sid-host-browser"
@@ -305,11 +309,24 @@ def test_connector_runtime_adds_remote_debugging_help_to_cdp_errors():
assert "chrome://inspect/#remote-debugging" in message
assert "Allow remote debugging for this browser instance" in message
assert "/browser host on" in message
+ assert "Internal Docker browser" in message
+ assert "/browser container" in message
already_helpful = (
"Open chrome://inspect/#remote-debugging and enable "
'"Allow remote debugging for this browser instance".'
)
- assert runtime._host_browser_error_message(already_helpful) == already_helpful
+ already_helpful_message = runtime._host_browser_error_message(already_helpful)
+ assert already_helpful in already_helpful_message
+ assert "/browser container" in already_helpful_message
+
+
+def test_connector_runtime_adds_docker_recovery_to_host_errors():
+ runtime = ConnectorBrowserRuntime("ctx-host", _agent("ctx-host"))
+
+ message = runtime._host_browser_error_message("Host browser operation failed")
+
+ assert "Internal Docker browser" in message
+ assert "/browser container" in message
def test_host_browser_artifacts_materialize_inside_multi_results(monkeypatch, tmp_path):