Logging & Screen Recording
Relevant source files
The following files were used as context for generating this wiki page:
The Logging & Screen Recording system provides a comprehensive observability suite for AI-driven browser interactions. It captures high-definition video recordings of agent sessions, generates interactive GIFs of task progression, maintains detailed execution logs (including "Deep Thinking" traces from models like DeepSeek), and preserves full agent history and trace files for debugging and auditing purposes.
This system ensures that every action taken by the agent is verifiable, allowing users to review the reasoning behind specific browser interactions and troubleshoot failures through visual and textual evidence.
System Architecture and Data Flow
The system leverages Playwright's native recording capabilities alongside custom Python utilities to manage the lifecycle of logs and media. Data flows from the browser context to specified local directories, which are then surfaced via the Gradio WebUI.
This diagram illustrates how data is captured at the browser and agent layers and subsequently presented to the user.
Sources: webui.py:100-150, src/agent/custom_agent.py:465-500
Screen Recording Implementation
Screen recording is managed at the BrowserContext level. When enabled, Playwright records the browser session and saves it to a user-defined path. The WebUI monitors this directory to provide a "Latest Recording" view and a gallery of past sessions.
Recording Configuration
Recordings are toggled via the enable_recording checkbox in the UI. If active, the save_recording_path is passed to the BrowserContextConfig.
| Parameter | Description | Source |
|---|---|---|
save_recording_path | Directory where MP4 or WebM files are stored. | webui.py:105 |
enable_recording | Boolean flag to trigger video capture. | webui.py:102 |
RESOLUTION | Environment variable (e.g., 1920x1080x24) for recording quality. | docker-compose.yml:41 |
Sources: webui.py:100-115, docker-compose.yml:41-43
GIF Generation
Beyond video, the CustomAgent class includes a create_history_gif method that compiles screenshots taken during each step into an annotated GIF. This GIF includes overlays for the task description and the agent's "thought" process for each frame.
# src/agent/custom_agent.py:465
def create_history_gif(
self,
output_path: str = 'agent_history.gif',
duration: int = 3000,
show_goals: bool = True,
# ... other params
) -> None:
# Captures screenshots from history items and adds overlays
Sources: src/agent/custom_agent.py:465-475
Logging and Tracing
The system captures multiple levels of textual data, from low-level browser traces to high-level AI reasoning.
Agent History and Traces
At the end of an execution, the agent saves a full JSON history containing every state, action, and result. Additionally, Playwright traces (saved as .zip files) can be opened in the Playwright Trace Viewer for step-by-step technical analysis.
This sequence shows the parallel capture of execution logs, traces, and media.
Sources: webui.py:228-245, src/agent/custom_agent.py:315-330
Deep Thinking Logs
For models supporting reasoning (e.g., DeepSeek-R1), the system extracts and logs the reasoning_content specifically. This is logged to the console/standard output and can be seen in the WebUI's "Model Thoughts" section.
# src/agent/custom_agent.py:183
if hasattr(ai_message, "reasoning_content"):
logger.info("🤯 Start Deep Thinking: ")
logger.info(ai_message.reasoning_content)
logger.info("🤯 End Deep Thinking")
Sources: src/agent/custom_agent.py:183-187, src/utils/deep_research.py:155-160
Research Persistence in Deep Research
The "Deep Research" module implements a specialized logging flow where search iterations, plans, and extracted content are saved as individual Markdown files before being compiled into a final_report.md.
- Iteration Logs: Saved as
{search_iteration}-{query_index}.mdin thequery_resultsdirectory. - Recorded Info: All gathered facts are stored in
record_infos.json. - Final Output: A comprehensive report is generated using a specific
writer_system_prompt.
Sources: src/utils/deep_research.py:210-235, src/utils/deep_research.py:310-320
File Management Utilities
The project includes utility functions to manage the generated artifacts.
| Function | Purpose | Location |
|---|---|---|
get_latest_files | Retrieves the most recent .webm and .zip (trace) files. | src/utils/utils.py:165 |
list_recordings | Lists and numbers all video files in the recording directory for the UI gallery. | webui.py:657 |
capture_screenshot | Captures a live JPEG screenshot from the active Playwright page for the live UI stream. | src/utils/utils.py:187 |
Sources: src/utils/utils.py:165-185, webui.py:657-670, src/utils/utils.py:187-210
Conclusion
The Logging & Screen Recording module is essential for the transparency of the WebUI. By combining Playwright's low-level tracing and video capture with the CustomAgent's high-level history and GIF generation, the system provides developers and users with a complete audit trail of AI browser activity.