docs(a2a): Add VNC support for browser-agent with real-time GUI viewing

examples/a2a/Dockerfile.vnc

@@ -0,0 +1,29 @@
+FROM alpine:latest
+
+# Install x11vnc
+RUN apk add --no-cache x11vnc
+
+# Create a startup script that connects to the shared X display
+COPY <<'EOF' /usr/local/bin/start-vnc.sh
+#!/bin/sh
+set -e
+
+echo "Waiting for X display :99 to be available..."
+echo "Checking /tmp/.X11-unix directory..."
+ls -la /tmp/.X11-unix/ 2>/dev/null || echo "Directory not found or empty"
+
+while true; do
+  if [ -S /tmp/.X11-unix/X99 ]; then
+    echo "X11 socket found, attempting to start x11vnc..."
+    x11vnc -display :99 -forever -shared -passwd password -rfbport 5900 -listen 0.0.0.0 -noshm && break
+  else
+    echo "Waiting for /tmp/.X11-unix/X99 socket... ($(date))"
+    ls -la /tmp/.X11-unix/ 2>/dev/null || echo "Directory still empty"
+  fi
+  sleep 5
+done
+EOF
+
+RUN chmod +x /usr/local/bin/start-vnc.sh
+
+ENTRYPOINT ["/usr/local/bin/start-vnc.sh"]

examples/a2a/README.md

@@ -45,6 +45,36 @@ Now you can enter the Interactive Chat within the cli container and start chatti
 docker compose run --rm cli
 ```
 
+## Viewing Browser Agent GUI
+
+The browser-agent can run in headed mode with VNC support for real-time viewing of browser automation.
+
+**Requirements:**
+
+1. Browser-agent v0.4.0+ with Xvfb support
+2. `BROWSER_HEADLESS: false` environment variable set
+3. Shared X11 socket volume between browser-agent and browser-vnc
+
+**Usage:**
+
+Connect to the VNC server on port 5900:
+
+```bash
+# Using a VNC client (e.g., RealVNC, TigerVNC, or macOS Screen Sharing)
+# Connect to: localhost:5900
+# Password: password
+```
+
+On macOS, you can use the built-in Screen Sharing app:
+
+```bash
+open vnc://localhost:5900
+# When prompted, enter password: password
+```
+
+**Note:** The X11 display is created by Xvfb when the browser-agent container starts. The VNC server will connect
+automatically and you can view browser automation in real-time.
+
 ## Troubleshooting
 
 ```bash

examples/a2a/docker-compose.yaml

@@ -167,6 +167,7 @@ services:
     environment:
       ENVIRONMENT: development
       BROWSER_DATA_DIR: /tmp/playwright
+      BROWSER_HEADLESS: false
       A2A_AGENT_URL: http://browser-agent:8080
       A2A_AGENT_CLIENT_PROVIDER: deepseek
       A2A_AGENT_CLIENT_MODEL: deepseek-chat
@@ -189,6 +190,23 @@ services:
       A2A_ARTIFACTS_RETENTION_CLEANUP_INTERVAL: 24h
     volumes:
       - ./agents/browser-agent:/tmp/artifacts
+      - x11-socket:/tmp/.X11-unix
+    restart: unless-stopped
+    networks:
+      - a2a-network
+
+  browser-vnc:
+    build:
+      context: .
+      dockerfile: Dockerfile.vnc
+    environment:
+      DISPLAY: :99
+    volumes:
+      - x11-socket:/tmp/.X11-unix
+    ports:
+      - "5900:5900"
+    depends_on:
+      - browser-agent
     restart: unless-stopped
     networks:
       - a2a-network
@@ -219,3 +237,4 @@ networks:
 volumes:
   go-modules:
   go-build-cache:
+  x11-socket: