WebUI#

Purpose#

The EAA WebUI is a lightweight standalone interface for watching agent progress and sending user input from a browser. It does not run inside the task-manager process. Instead, it communicates through a shared SQLite database.

Launch pattern#

Configure the task manager with the same SQLite file you want the WebUI to use:

task_manager = BaseTaskManager(
    ...,
    session_db_path="session.sqlite",
    use_webui=True,
)

Then start the WebUI process:

from eaa_core.gui.html import run_html_webui

run_html_webui("session.sqlite", host="127.0.0.1", port=8008)

To launch the WebUI without blocking the current Python process, use the subprocess launcher:

from eaa_core.gui.html import launch_html_webui_subprocess

process = launch_html_webui_subprocess(
    "session.sqlite",
    host="127.0.0.1",
    port=8008,
)

# Later, when the UI is no longer needed:
process.terminate()

Communication mechanism#

The browser-facing FastAPI process reads and writes a shared SQLite file. The main tables involved are:

webui_messages

Explicit display messages pushed by the task manager.

webui_inputs

User messages submitted from the browser and consumed by the agent process.

status

WebUI status flags, including whether the agent is currently waiting for user input.

checkpoints and writes

LangGraph checkpoint tables used when checkpointing is enabled.

The WebUI first tries to read explicit display messages. If none are present, it can reconstruct the transcript from the latest checkpointed state.

Brief design introduction#

The current WebUI has a deliberately small design:

  • reusable SQLite relay helpers in eaa_core.gui.relay

  • reusable HTML/JavaScript WebUI class in eaa_core.gui.html

  • polling-based message/status updates

  • clipboard image upload support

  • no tight coupling to a specific task-manager subclass

This design keeps the UI process simple and lets the task manager remain the source of truth for workflow execution.

Extending the WebUI#

Task-specific packages can subclass HTMLWebUIBase and override page_html(), styles(), script(), or build_app() without changing the SQL relay contract:

from eaa_core.gui.html import HTMLWebUIBase


class FocusingWebUI(HTMLWebUIBase):
    def styles(self) -> str:
        return super().styles() + "<style>.eaa-title::after { content: ' focusing'; }</style>"


FocusingWebUI("session.sqlite").run(host="127.0.0.1", port=8008)