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

# SDK quickstart

> Build an agentic web workflow with the TypeScript SDK, domain policy, approvals, and result handling.

Use `web.agent()` when an agentic workflow belongs inside an application, backend process, or recurring automation.

## Prerequisites

* Node.js 20 or newer, plus `npm` or another Node package manager.
* A Webcompute API key exported as `WEBCOMPUTE_API_KEY`. The TypeScript SDK reads the key from this environment variable or from `new Web({ apiKey })`.
* A model-provider key for the route you choose. This page uses OpenRouter, so export `OPENROUTER_API_KEY`.
* A target workflow and domain boundary. If you want to run the workflow from the terminal first, start with the [CLI quickstart](/quickstart).

## Install the SDK

```bash theme={null}
npm install https://install.webcompute.dev/sdk/latest.tgz
```

Version metadata is published at `https://install.webcompute.dev/sdk/latest.json` for pinned installs.

Set your Webcompute API key:

```bash theme={null}
export WEBCOMPUTE_API_KEY=wc_key_your_key_here
export OPENROUTER_API_KEY=your_provider_key
```

If you used `web model setup` in the CLI, copy the same route, model, and credential env-var name into SDK code. SDK `web.agent()` requires explicit model config.

## Run an agent workflow

```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 filings. Return filing date, accession number, filing URL, and a one-sentence summary.",
});

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

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

The agent creates a managed browser, stays inside `sec.gov`, records the run, and returns a final result.

One-shot agent runs close browsers they create when the run completes. Use [long-running tasks](/agent-workflows/long-running-tasks) or an explicit browser session when your application needs continuity or post-run live inspection.

Use the SDK reference when you need the full surface: [agent](/reference/sdk-agent-reference), [browser](/reference/sdk-browser-reference), [resources](/reference/sdk-resources-reference), [quick actions](/reference/sdk-quick-actions-reference), [policy](/reference/policy-reference), and [proxy](/reference/proxy-reference).

You can also pass a string when only the goal is needed:

```ts theme={null}
await agent.run("Open the pricing page and summarize enterprise plan differences.");
```

## Read the result

```ts theme={null}
console.log(result.status);
console.log(result.text);
console.log(result.steps.length);
console.log(result.artifacts);
```

Use `result.output` when you provide an output schema. Use `result.steps` and `result.artifacts` when you need evidence for logs, review, or debugging.

<Warning>
  Signed Debug UI and CDP URLs are bearer capabilities. Do not log them or expose them to untrusted users.
</Warning>

## Add browser resources around the agent

Create the browser yourself when the workflow needs explicit lifecycle, recording, downloads, status, or recovery around the agent run.

```ts theme={null}
const resourceAgent = 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 resourceAgent.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();
}
```

Webcompute provides the managed browser runtime. SDK resources make the browser boundary, durable files, status checks, and recovery path explicit around the agent run. When you pass `browserId`, configure policy on `web.browser.create(...)`.

## Run related goals in one browser

Use `agent.session(...)` when multiple related goals should share the same browser.

```ts theme={null}
const session = await agent.session({
  startUrl: "https://www.sec.gov/edgar/search/",
});

try {
  await session.run("Find Apple's latest 10-Q filing.");
  const comparison = await session.run("Compare it with the previous 10-Q filing.");
  console.log(comparison.text);
} finally {
  await session.close();
}
```

Sessions keep the same browser alive across related goals. Write follow-up goals with the context the model needs.

## Next steps

* Add [structured output](/agent-workflows/structured-output).
* Add [policies and approvals](/agent-workflows/policies-and-approvals).
* Add [secrets and user input](/agent-workflows/secrets-and-user-input).
* Learn how to [mix agent steps with deterministic code](/agent-workflows/mixing-agent-and-code).
* Check the [TypeScript SDK reference](/reference/sdk-reference) for exact exported types and error classes.