After your first run

Choose the next surface based on how the agentic workflow should run: directly from the CLI, inside software with the SDK, from a coding-agent host, or through an HTTP or protocol integration.

Default recommendation

Situation	Start here
You want to run the workflow directly	Use `web agent` from the quickstart.
The workflow belongs in an application, backend process, or recurring automation	Use SDK `web.agent()`.
Multiple related goals should share one browser	Use SDK `agent.session()`.
The workflow needs files, downloads, recordings, status, validation, or recovery	Use SDK browser resources around `agent.run(...)`.
A coding-agent host needs a browser specialist	Use MCP agent mode.
A non-TypeScript service owns the integration	Use REST.
An existing browser framework must attach directly	Use CDP.
You need one scrape, screenshot, or PDF	Use quick actions.
One browser step must be exact	Use advanced exact browser control.

Use the CLI when a workflow should run directly. Use SDK web.agent() when the workflow needs to integrate with software. Use REST, CDP, or exact browser-code execution when the integration boundary requires them.

CLI and SDK workflow surfaces

Use web agent when you want an agentic workflow from the terminal.

web agent \
  --url https://www.sec.gov/edgar/search/ \
  --allow-domain sec.gov \
  "Find Apple's latest 10-Q filing. Return the filing date, accession number, filing URL, and a one-sentence summary."

When the same workflow belongs in software, move the goal into SDK web.agent().

import { Web } from "@webcompute/sdk";

const web = new Web();

const agent = web.agent({
  model: {
    route: "openrouter",
    model: "openai/gpt-5.4-mini",
    apiKeyEnv: "OPENROUTER_API_KEY",
  },
  browser: {
    create: { recording: true },
    policy: { allowedDomains: ["sec.gov"] },
  },
  approval: "ask",
});

const result = await agent.run({
  startUrl: "https://www.sec.gov/edgar/search/",
  goal:
    "Find Apple's latest 10-Q filing. Return the filing date, accession number, filing URL, and a one-sentence summary.",
});

Use web.agent() when the model should handle browser work inside an application, backend process, or recurring automation. Use SDK resources around it for boundaries, resources, validation, and persistence.

Add SDK runtime controls

Integrated workflows usually look like this:

const workflowAgent = web.agent({
  model: {
    route: "openrouter",
    model: "openai/gpt-5.4-mini",
    apiKeyEnv: "OPENROUTER_API_KEY",
  },
  approval: "ask",
});

const browser = await web.browser.create({
  recording: true,
  policy: { allowedDomains: ["vendor.example"] },
});

try {
  const result = await workflowAgent.run({
    browserId: browser.id,
    startUrl: "https://vendor.example/dashboard",
    goal: "Find the latest paid invoice and download the PDF.",
  });

  if (result.status !== "completed") {
    throw new Error(result.error?.message ?? `Run ended with ${result.status}`);
  }

  const downloads = await browser.downloads.list();
  const [invoice] = downloads.data;
  if (invoice) await browser.downloads.save(invoice.id, "./invoice.pdf");
} finally {
  await browser.close();
}

The SDK makes lifecycle, policy, files, downloads, status, recordings, validation, retries, and recovery explicit around the agent run. When application code creates the browser, put policy on web.browser.create(...), not on the agent config.

Use MCP for coding agents

Use MCP when Codex, Claude Code, Cursor, OpenCode, Devin, OpenClaw, Hermes, or another MCP host should operate a browser.

web model setup --name browsing
web mcp setup claude --surface agent --model browsing --instructions

Agent mode exposes one browser-subagent tool:

Tool	Use it for
`run_web_agent`	Delegate a whole browsing goal to Webcompute’s browser-agent harness.

Use runtime mode when the host should plan each exact browser-code step:

web mcp setup codex --surface runtime

Runtime mode exposes manage_browsers and execute_playwright_code. It remains the technical default for web mcp run.

Use REST, CDP, quick actions, or exact control

Use REST when TypeScript is not the application boundary. The OpenAPI reference covers browser lifecycle, exact browser-code execution, resources, recordings, events, dialogs, permissions, and quick actions. Use CDP when an existing framework must attach directly to the browser. Direct CDP clients do not automatically receive Webcompute post-step observations; use Webcompute browser calls when agent-readable observations matter. Use quick actions when you need one scrape, screenshot, or PDF and do not need a persistent browser session. Use advanced exact browser control when a specific browser step must be deterministic: validating a known page, clicking a known export button, recovering from a known state, or integrating an external browser framework. Keep it bounded and return to agent.run(...) or SDK resource APIs afterward.

Debug UI and CDP URLs are signed bearer capabilities. Treat them like credentials.

Move between paths

Start	Move when	Next path
`web agent`	The workflow needs to run inside software	SDK `web.agent()`
SDK `web.agent()`	Related goals should share one browser	SDK `agent.session()`
SDK `web.agent()`	The workflow needs lifecycle, files, downloads, validation, or recovery	SDK browser resources around `agent.run({ browserId })`
SDK `web.agent()`	One browser step must be exact	Advanced exact browser control
MCP agent mode	The workflow becomes a product feature	SDK `web.agent()` plus browser resources
Quick actions	The job needs state, files, downloads, dialogs, or recordings	Managed browser lifecycle
CDP	You need Webcompute observations or resource APIs	SDK or REST browser calls

Read results and evidence when the output shape is the deciding factor.

Next steps

Run the CLI quickstart

Install Webcompute, configure model access, run a public browser task, and inspect the result.

Build with the SDK

Build agentic workflows into applications, backend services, and recurring automations.

Mix agent and code

Combine agent-driven browser work with explicit SDK resources and product logic.

Connect MCP

Give a coding-agent host a managed browser runtime.

Use exact browser control

Run bounded browser-code steps when a workflow requires exact control.

Get started

Build agent workflows

Observe and debug

Runtime concepts

Examples

Integrations

Production

Reference

API reference

After your first run

Default recommendation

CLI and SDK workflow surfaces

Add SDK runtime controls

Use MCP for coding agents

Use REST, CDP, quick actions, or exact control

Move between paths

Next steps

Run the CLI quickstart

Build with the SDK

Mix agent and code

Connect MCP

Use exact browser control

​Default recommendation

​CLI and SDK workflow surfaces

​Add SDK runtime controls

​Use MCP for coding agents

​Use REST, CDP, quick actions, or exact control

​Move between paths

​Next steps

Run the CLI quickstart

Build with the SDK

Mix agent and code

Connect MCP

Use exact browser control

Default recommendation

CLI and SDK workflow surfaces

Add SDK runtime controls

Use MCP for coding agents

Use REST, CDP, quick actions, or exact control

Move between paths

Next steps