> ## 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.
# After your first run
> Choose the right Webcompute surface for direct workflows, application features, recurring automations, coding-agent hosts, or exact browser control.
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](/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.
```bash theme={null}
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()`.
```ts theme={null}
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:
```ts theme={null}
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.
```bash theme={null}
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:
```bash theme={null}
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](/observe-and-debug/results-and-evidence) when the output shape is the deciding factor.
## Next steps
Install Webcompute, configure model access, run a public browser task, and inspect the result.
Build agentic workflows into applications, backend services, and recurring automations.
Combine agent-driven browser work with explicit SDK resources and product logic.
Give a coding-agent host a managed browser runtime.
Run bounded browser-code steps when a workflow requires exact control.