Headful versus headless browsers for AI agents.
Headless means Chrome runs without visible platform windows. Headful means operators can see the browser window. Modern Chrome shares one implementation across both modes. Mode alone does not prove compatibility.
Choose headless for unattended, observable production runs. Choose headful for live inspection and intervention. Capture artifacts in either mode. Test the exact agent workflow before standardizing.
The short version
Visibility is an operating choice, not magic compatibility.
Start with the modern definition.
Headless Chrome runs without visible platform windows. Headful Chrome displays those windows. That visible difference remains operationally important. The underlying browser story has changed.
Chrome unified its headless and headful implementations. Since Chrome 112, headless creates undisplayed platform windows. Chrome states other browser functions remain available. Old compatibility assumptions deserve retesting.
Puppeteer still launches headless by default. Playwright does the same for normal execution. Both frameworks can switch into headed operation. Their debugging tools make that switch useful.
For agents, mode is only one dimension. Perception arrives through DOM, accessibility, screenshots, or video. Actions arrive through automation interfaces. Human oversight uses separate controls.
Compare operating models, not folklore.
The best mode follows the operating model. Production agents need evidence and control. Developers need fast diagnosis. Reviewers need understandable intervention paths.
No row declares a universal winner. Both modes can capture screenshots. Both can expose page structure. Both can fail differently across environments. Controlled tests settle specific questions.
| Factor | Headful | Headless |
|---|---|---|
| Displayed window | Browser windows remain visible to a nearby operator | Platform windows exist but are not displayed |
| Live debugging | Natural fit for inspectors, stepping, and direct observation | Usually reviewed through logs, traces, screenshots, and recorded artifacts |
| Agent perception | Can use DOM, accessibility, screenshots, or visual streams | Can use DOM, accessibility, screenshots, or visual streams |
| Human takeover | Local visible browser can support direct operator interaction | Requires a separate remote viewing or intervention surface |
| Unattended infrastructure | May require display infrastructure on server operating systems | Designed for unattended execution without visible user interfaces |
| Compatibility conclusion | Must be tested against the exact workflow and browser build | Must be tested against the exact workflow and browser build |
This matrix uses current official browser-framework behavior. It does not predict every website.
SourcesChrome for DevelopersPlaywrightPlaywrightPlaywrightPuppeteerPlaywright
Agent perception is a separate decision.
A visible browser does not automatically provide vision. The agent still needs observations. Those observations may be structural or visual. Each representation loses different information.
DOM and accessibility data expose semantic structure. Screenshots expose layout and rendered pixels. Network events expose requests. Console logs expose application messages.
Headless browsers can capture screenshots. Playwright and Puppeteer both document screenshot APIs. Therefore visual agents do not inherently require headful mode. They require reliable visual observations.
Headful mode helps nearby humans observe live behavior. That can speed development. It can also support manual intervention. Production still needs recorded evidence afterward.
| Factor | Best evidence | Blind spot to manage |
|---|---|---|
| DOM or accessibility snapshot | Names, roles, text, hierarchy, and programmatic element references | Canvas content, visual overlap, styling, and spatial emphasis |
| Screenshot | Rendered layout, charts, canvas content, and visual confirmation | Hidden state, network behavior, semantics, and transient timing |
| Trace | Actions, snapshots, logs, network requests, and historical sequence | Missing instrumentation, retained secrets, and external side effects |
| Live headful view | Immediate operator observation and direct visual troubleshooting | Poor reproducibility without separate recordings and structured logs |
Select observation channels independently from browser display mode.
Development favors visible intervention.
Agents fail for many ordinary reasons. Selectors can become ambiguous. Navigation can race page state. Authentication can expire. Dialogs can block progress.
Playwright's debug mode launches headed browsers. Its inspector can step through actions. Developers can inspect locators and logs. This shortens the feedback loop.
Headful development does not require headful production. Reproduce the failure visibly first. Then retain a trace or screenshot. Finally retest the production mode.
Some failures disappear during slow observation. Timing changes can hide races. Keep normal-speed replay in the loop. Compare artifacts across both executions.
- 01
Capture the failure.
Save logs, screenshots, traces, inputs, and browser versions. Remove sensitive values.
- 02
Replay it visibly.
Use headed debugging and action stepping. Observe the earliest divergence.
- 03
Fix the cause.
Prefer stable state checks and resilient locators. Avoid timing guesses.
- 04
Retest production mode.
Run normal speed and normal infrastructure. Compare retained evidence.
- 05
Test the fallback.
Trigger escalation deliberately. Verify operator context and authority.
SourcesPlaywrightPlaywright
Production favors evidence and control.
Unattended agents need bounded authority. Browser mode does not supply that boundary. Tools, credentials, destinations, and approvals determine reachable actions. Logs show what happened later.
Headless mode fits unattended infrastructure naturally. Chrome requires no visible interface there. Playwright's normal mode follows this pattern. Puppeteer also defaults to headless.
Headful production can still make sense. Remote operators may need live viewing. Some workflows require direct intervention. The surrounding platform must expose that control safely.
Either mode needs lifecycle management. Create scoped sessions. Limit accessible credentials. Close resources after work. Preserve only required evidence.
- Record browser and framework versions.
- Capture failures with bounded artifacts.
- Redact secrets before artifact retention.
- Separate observation from action authority.
- Require approval for consequential actions.
- Destroy sessions after completed tasks.
Retire four weak assumptions.
First, headless does not mean text-only. Modern Chrome still renders pages. Frameworks can capture visual output. Agents can receive those pixels.
Second, headful does not mean human-like. Automation interfaces still control the browser. Websites may observe many environmental signals. A visible window proves nothing alone.
Third, headless does not guarantee efficiency. Resource use depends upon workload and configuration. Measure representative sessions. Include rendering, media, traces, and concurrency.
Fourth, headful does not guarantee compatibility. Browser version and launch settings still matter. Extensions and policies can alter behavior. Exact workflows require controlled tests.
Run a representative selection test.
Do not benchmark a toy page. Select a representative workflow. Include authentication and navigation. Include the hardest interactive step. Include the required evidence path.
Run both modes with matching versions. Keep network conditions comparable. Record success and intervention rates. Record resource use and completion time.
Review failures by root cause. Separate page changes from mode differences. Separate agent planning failures from browser failures. Separate infrastructure failures from workflow policy.
Then choose the simplest operating model. Keep a documented debugging path. Keep a separate fallback path. Recheck after major browser upgrades.
| Factor | Measure | Why it matters |
|---|---|---|
| Task completion | Successful runs under the defined acceptance criteria | Captures practical outcome without hiding partial or unsafe completion |
| Human interventions | Count, timing, trigger, context provided, and operator action | Shows whether live visibility creates measurable operational value |
| Diagnostic evidence | Logs, screenshots, traces, network records, and reproducibility | Determines whether failures can be understood and corrected |
| Resource cost | Memory, processor time, storage, bandwidth, and display infrastructure | Supports capacity planning without assuming mode-specific savings |
| Boundary compliance | Allowed destinations, credentials, exports, approvals, and teardown behavior | Prevents a successful task from becoming an unsafe task |
Record these fields for every evaluated workflow. Avoid one-number winner claims.
SourcesPlaywrightPlaywright
SourcesChrome for Developers
Where the Legba skill fits.
Legba describes a ready skill for agents. It provides routing and isolated browser sessions. Sessions run on Legba's infrastructure. Each task receives separate session scope.
The public description does not promise mode selection. It does not specify Playwright compatibility. It does not specify Puppeteer compatibility. This page adds none of those claims.
Evaluate the skill by required agent jobs. List observations, actions, and intervention needs. Confirm every required interface directly. Test consequential workflows before production use.
The focused value remains browser separation. Agent machines need not host the session. Routing is available on demand. Infrastructure ownership stays with Legba.
SourcesLegba
FAQs.
References
- 01Chrome Headless modeChrome for Developers
- 02What is PuppeteerPuppeteer
- 03Debugging Playwright testsPlaywright
- 04Playwright screenshotsPlaywright
- 05Puppeteer screenshotsPuppeteer
- 06Playwright Trace ViewerPlaywright
- 07Playwright Page APIPlaywright
- 08Playwright continuous integration guidePlaywright
- 09Legba agent skillLegba