> ## Documentation Index
> Fetch the complete documentation index at: https://docs-preview.webcompute.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Run tasks with web agent

> Use the web agent CLI for standalone agentic workflows with model profiles, domain boundaries, structured output, secrets, approvals, and live inspection.

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:

```bash theme={null}
web model setup
web model doctor browsing
```

Or pass model access for one command:

```bash theme={null}
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.

```bash theme={null}
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.    |

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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](/agent-workflows/structured-output).

## Pass secrets safely

```bash theme={null}
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.

```bash theme={null}
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.

<Warning>
  Debug UI URLs are bearer capabilities. Do not log or share them with untrusted users.
</Warning>

## 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](/agent-workflows/sdk-quickstart), [policies and approvals](/agent-workflows/policies-and-approvals), [secrets and user input](/agent-workflows/secrets-and-user-input), and [production blockers](/production/blockers-and-captcha).