Browser agent
Helm Browser Agent
A browser agent that checks whether the task is actually done.
Helm turns an instruction into a plan, runs one browser action at a time, and checks the page before it says the task is done.
The problem
A successful click is not a completed task.
Browser agents can report success after a click or navigation even when the requested result is not on the page. Helm treats login walls, captchas, missing results, and ambiguous pages as distinct outcomes.
What I built
A browser runtime with a validation loop.
I built the planner, Playwright engine, validation layer, recovery loop, risk gates, and FastAPI/WebSocket interface.
How it works
The main path.
- 01
Normalize the instruction into intent, success criteria, and risk level.
- 02
Select one action from the registered browser capability set.
- 03
Apply the confirmation gate and URL policy before execution.
- 04
Execute through Playwright and observe the resulting visible page state.
- 05
Check the page. Complete, recover, block, fail, or stop when the page does not confirm success.
Key engineering decisions
Three decisions that matter.
Validate the outcome, not the click
A successful browser action or page load is not enough to mark the user task completed.
core/task_orchestrator.py · core/validators.pyBound the action and risk model
A central registry defines executable actions, while a separate risk layer pauses final high-impact actions for confirmation.
core/action_registry.py · core/risk.pyMake failure useful
Login walls, captchas, loops, and unverifiable outcomes carry structured context instead of collapsing into one error message.
core/blockers.py · core/task_orchestrator.pyResults
Selected outcomes.
Benchmarks, packages, and checks from the project.
offline WebSocket path
The repository boots the API and exercises the real task pipeline with a deterministic browser implementation.
tests/live_check.py ↗explicit terminal contract
Completed, blocked, unverified, failed, and cancelled are represented as separate runtime outcomes.
core validators and orchestrator ↗navigation guard
Scheme, private-address, loopback, and cloud-metadata checks run before navigation.
core/url_policy.py and tests ↗Interactive demo
Try the main path.
Run three browser tasks through intent parsing, actions, risk checks, blockers, and completion.
Controls
Task runner
Task trace
0 / 4 stages- intent
- navigate
- target
- https://example.com/docs
- 01
Waiting
- 02
Waiting
- 03
Waiting
- 04
Waiting
No page observed
Run the task to execute the fixture.
Scope
Current constraints.
- Live-site reliability has not been benchmarked.
- Running the agent needs a configured Groq, Gemini, or local Ollama provider.
- The current deployment model is local and single-user.