Agent interaction patterns

Choose the right surface

Need	Use
Operate the browser the user already authenticated	`unsurf-local-mcp`
Record a browser run for review	`record` / `recordAttachedLocal`
Retry until visual success is proven	`loop`
Ask what happened in a run	`observeVideo`
Reuse a stable hidden HTTP seam	`scout` → `worker` → `heal`

Pattern 1 — Drive the trusted browser

Use local MCP when another nearby agent should act inside the user’s real session:

{
  "mcpServers": {
    "unsurf-local": { "command": "unsurf-local-mcp" }
  }
}

Typical flow:

call unsurf_local_sessions
inspect the attachable tabs
call unsurf_local_execute
optionally record the action plan

This is the right path for authenticated dashboards, enterprise apps, and any work where the browser identity matters.

Pattern 2 — Record for proof

If the task matters enough to review later, record it:

unsurf record ./run.ts --task "dashboard proof" --cdp-port 9222

A proof bundle gives the agent and the human a shared artifact: the browser video, trace, status, and viewer link.

Pattern 3 — Loop until the North Star is met

Use loop() when the success condition is visual or interaction-heavy:

unsurf loop "fill the three visible form fields" \
  --north-star "Did all three fields contain non-empty values?" \
  --max-iter 3 \
  --cdp-port 9222

Good North Stars are yes/no and observable from the recording.

Pattern 4 — Capture a reusable seam

If an operation repeats often and the browser exposes a stable HTTP endpoint, use:

scout once → worker many times → heal on drift

That path is still excellent for search APIs, data loaders, and repeatable CRUD-like flows. It is simply not the only Unsurf workflow.

Agent prompt guidance

Use Unsurf like this:
1. If the task depends on the user's existing login, use the local browser MCP.
2. If the task should be reviewable, record it.
3. If success is visual, prefer loop with a yes/no North Star.
4. If the site exposes a stable API seam worth reusing, scout it and replay it with worker.
5. Heal a broken seam instead of repeatedly retrying the same dead path.

Error posture

Failure	Agent response
No local browser sessions	Ask the user to open/authenticate the browser runtime
Browser action fails	Stop the plan, return the failing action, do not blindly continue
Loop misses North Star	Refine or stop at budget
`worker` path drifts	Call `heal`