Run tasks with web agent

Use web agent when you want to create and run an agentic workflow from the terminal. The command gives the agent a managed browser, applies your model profile and boundaries, and returns an inspectable result. 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. Use SDK web.agent() when the workflow needs to live inside an application, backend process, recurring automation, or custom browser creation path such as proxy.

Configure model access

Save a reusable profile:

web model setup
web model doctor browsing

Or pass model access for one command:

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."

The model chooses browser steps. Webcompute runs those steps in a managed browser and returns observations/status after browser tool calls so the agent can decide what to do next.

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."

Use --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."

Reference: structured output.

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."

The Debug UI URL is useful while the CLI run is active. For persistent recordings, stored artifacts, or post-run browser inspection, use SDK 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	Use SDK `web.agent()` or direct browser control.

Reference: SDK quickstart, policies and approvals, secrets and user input, and production blockers.

Get started

Build agent workflows

Observe and debug

Runtime concepts

Examples

Integrations

Production

Reference

API reference

Run tasks with web agent

Configure model access

Write a bounded task

Choose an approval mode

Return data to another program

Pass secrets safely

Inspect while the run is active

Common failure modes

​Configure model access

​Write a bounded task

​Choose an approval mode

​Return data to another program

​Pass secrets safely

​Inspect while the run is active

​Common failure modes

Configure model access

Write a bounded task

Choose an approval mode

Return data to another program

Pass secrets safely

Inspect while the run is active

Common failure modes