Use web agent when you want to prove a delegated browser task from the terminal. It is the fastest way to learn whether a prompt, starting URL, domain boundary, and model profile can complete the work.
The CLI agent is a one-shot workflow: it creates a managed browser for the run and closes browsers it created when the command finishes. Move to SDK web.agent() when your application needs session continuity, recording, stored artifacts, or custom browser creation options such as proxy.
Save a reusable profile:
web model setup
web model doctor browsing
web agent \
--route openrouter \
--model openai/gpt-5.4-mini \
--api-key-env OPENROUTER_API_KEY \
--url https://www.sec.gov/edgar/search/ \
--allow-domain sec.gov \
"Find Apple's latest 10-Q filing and return filing metadata."
Write a bounded task
A good CLI agent task names the site, starts from a URL, constrains the domain, and asks for a concrete result.
web agent \
--profile browsing \
--url https://www.sec.gov/edgar/search/ \
--allow-domain sec.gov \
--max-turns 8 \
--max-tool-calls 12 \
--timeout-ms 180000 \
--tool-timeout-ms 30000 \
"Find Apple's latest 10-Q filing. Return filing date, accession number, filing URL, and a one-sentence summary."
Choose an approval mode
| Mode | Use when |
|---|
delegated | The run may continue inside the configured policy boundary. This is the CLI default. |
ask | A human is present and should approve sensitive actions. |
never | The command must not ask for confirmation; sensitive actions should stop or fail. |
web agent \
--approval ask \
--url https://example.com/account \
--allow-domain example.com \
"Open the account page and summarize the billing status. Do not change settings."
Return data to another program
Use --json for machine-readable run output.
web agent \
--json \
--profile browsing \
--url https://www.sec.gov/edgar/search/ \
--allow-domain sec.gov \
"Find Apple's latest 10-Q filing and return filing metadata."
--schema when the final answer must match a JSON schema.
web agent \
--schema ./filings.schema.json \
--url https://www.sec.gov/edgar/search/ \
--allow-domain sec.gov \
"Find Apple's latest 10-Q filing. Return filing date, accession number, filing URL, and filing page URL."
Pass secrets safely
export DEMO_ACCOUNT_EMAIL="person@example.com"
web agent \
--url https://example.com/login \
--allow-domain example.com \
--secret accountEmail=DEMO_ACCOUNT_EMAIL \
--approval ask \
"Open the account page and summarize the billing status. Do not change settings."
--secret name=ENV_VAR reads the value from your environment and exposes it as a sensitive variable. When --allow-domain is present, the CLI scopes the secret to those domains. When no domain is present, the CLI scopes the secret to the start URL hostname when it can.
Do not paste secret values into the goal text.
Inspect while the run is active
Use --debug-url only when you intentionally want the signed live-browser URL in output.
web agent \
--debug-url \
--profile browsing \
--url https://www.sec.gov/edgar/search/ \
--allow-domain sec.gov \
"Find Apple's latest 10-Q filing and return filing metadata."
web.agent() with browser.create.recording: true or direct browser control.
Debug UI URLs are bearer capabilities. Do not log or share them with untrusted users.
Common failure modes
| Symptom | What to do |
|---|
| Model profile missing | Run web model setup, or pass --route, --model, and --api-key-env. |
| Run leaves the intended site | Add or narrow --allow-domain. |
| Needs a high-impact action | Use --approval ask, or change the task so it stops before that action. |
| Output is hard to parse | Add --json or --schema. |
| Site blocks the run | Report the blocker and move to human review instead of retrying blindly. |
| Need proxy, recording, or session continuity | Move the task to SDK web.agent() or direct browser control. |
