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

# Agent workflows

> Build agentic workflows for real web applications with the CLI, SDK, managed browsers, and production controls.

Use the CLI for agentic workflows you want to run directly. Use the SDK when a workflow should become an application feature, backend process, or recurring automation.

SDK `web.agent()` takes explicit model config. CLI model profiles are useful for direct runs and operator workflows, but SDK code should pass the route, model, and credential env-var values it needs.

```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: {
    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 filings and return filing metadata.",
});

console.log(result.text);
```

## Choose the right workflow surface

The CLI and SDK use the same managed browser runtime, but they fit different workflow boundaries:

* Use the CLI for workflows you run directly from a terminal, script, or operator process.
* Use the SDK when the workflow needs application context, user authorization, queues, schedules, product UI, or persistence.
* Use SDK browser resources when the workflow needs explicit browser lifecycle, files, downloads, recordings, status, or recovery.
* Use MCP when a coding-agent host should operate the browser.
* Use REST, CDP, quick actions, or exact browser control when those integration boundaries are the right fit.

## Build the workflow around the agent

Most integrated workflows use SDK resources around the agent:

```ts theme={null}
const workflowAgent = web.agent({
  model,
  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 browser lifecycle, policy, files, downloads, recordings, validation, retries, and recovery explicit around the agent run. For existing-browser runs, configure policy on the browser you create.

## Workflow shape

Most integrated workflows have four parts:

1. Deterministic setup: read database state, build a safe query, choose policy, and set budgets.
2. Agent browsing: let the agent operate the web application inside the managed browser.
3. Deterministic validation: check schema, business rules, and source URLs.
4. Evidence and failure handling: store artifacts, inspect status, and return blockers clearly.

## Where deterministic browser control fits

Use deterministic browser control when a step must be exact: checking an expected page, downloading a known file, validating a selector, replaying a recovery path, or attaching another browser framework. It is an advanced workflow tool, not the fastest first run.

When deterministic work needs browser metadata or resources, create or fetch a browser handle and pass its `browserId` into the agent run.

<Columns cols={2}>
  <Card title="Run tasks with web agent" icon="terminal" href="/agent-workflows/cli-agent">
    Run standalone agentic workflows from the terminal with model profiles, boundaries, schemas, and inspection.
  </Card>

  <Card title="SDK quickstart" icon="code" href="/agent-workflows/sdk-quickstart">
    Run your first `web.agent()` workflow in TypeScript.
  </Card>

  <Card title="Structured output" icon="braces" href="/agent-workflows/structured-output">
    Return data your product can validate and store.
  </Card>

  <Card title="Policies and approvals" icon="shield-check" href="/agent-workflows/policies-and-approvals">
    Constrain domains and handle high-impact actions.
  </Card>

  <Card title="Mix agent and code" icon="workflow" href="/agent-workflows/mixing-agent-and-code">
    Combine agent-driven browser work with explicit SDK resources and product logic.
  </Card>
</Columns>