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

# Cookbook

> Runnable browser examples grouped by use case. Each one is self-contained: paste it, run it, read the output.

<Info>
  Every example is a single self-contained file in the [Box SDK
  repo](https://github.com/upstash/box/tree/main/packages/sdk/examples/browser).
  All of them need `UPSTASH_BOX_API_KEY`. Examples marked **AI** use metered
  browser AI (`run`, `act`, `extract`) and need a model provider key on the box
  or account. Everything else runs with the Box key alone.
</Info>

## Agents

Goal-driven browsing with `tab.run()`.

<CardGroup cols={2}>
  <Card title="Search with fallback" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/agents/01-search-with-fallback.ts">
    Constrained search with a fallback category. The agent evaluates results, rejects with reasons, and switches on its own. **AI**
  </Card>

  <Card title="Playwright vs act vs run" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/agents/02-playwright-vs-act-vs-run.ts">
    The same task via Playwright, `act` plus `extract`, and `run`. Pick your autonomy level by token cost. **AI**
  </Card>

  <Card title="Observe, record, audit" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/agents/03-observe-record-audit.ts">
    The search again with live view, session recording, a decision log, and token accounting. **AI**
  </Card>

  <Card title="Multisite feed" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/agents/04-multisite-feed.ts">
    One prompt and one schema across three differently structured sites. **AI**
  </Card>
</CardGroup>

## Automation

Forms, files, and durable sessions.

<CardGroup cols={2}>
  <Card title="Checkout with one AI step" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/automation/01-checkout-with-one-ai-step.ts">
    Script the deterministic steps, delegate the judgment call to a single `act`, and assert the result.
  </Card>

  <Card title="Download and process" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/automation/02-download-and-process.ts">
    A download lands on the box filesystem and is processed in place.
  </Card>

  <Card title="Upload from box" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/automation/03-upload-from-box.ts">
    Upload a box-generated file through a real form over CDP.
  </Card>

  <Card title="Log in once, reuse session" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/automation/04a-login-once-keep-alive.ts">
    Log in once into a keep-alive box, then have any later script reuse the session.
  </Card>
</CardGroup>

## Retrieval

Structured data out of rendered pages.

<CardGroup cols={2}>
  <Card title="Catalog extraction" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/retrieval/01-catalog-extraction.ts">
    One `extract` call, schema-validated typed output, screenshot provenance. **AI**
  </Card>

  <Card title="AI-compiled scraper" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/retrieval/02-ai-compiled-scraper.ts">
    AI compiles selectors once, then every later run scrapes deterministically. **AI (first run only)**
  </Card>

  <Card title="Crawl to dataset" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/retrieval/03-crawl-to-dataset.ts">
    Crawl a client-rendered docs section into chunked JSONL via `tab.content()`.
  </Card>

  <Card title="Evidence pack" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/retrieval/04-evidence-pack.ts">
    Full-page captures plus a hashed manifest, assembled in the box and downloaded as one archive.
  </Card>
</CardGroup>

## Testing

The box as a test environment.

<CardGroup cols={2}>
  <Card title="Playwright migration" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/testing/01-playwright-migration.ts">
    An existing Playwright test where only the launch line changes.
  </Card>

  <Card title="Test your own app" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/testing/02-test-your-own-app.ts">
    The box hosts the app under test and browses it on its own localhost.
  </Card>

  <Card title="AI smoke tests" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/testing/03-ai-smoke-tests.ts">
    Agent-driven smoke flow, cross-checked by deterministic DOM assertions, recorded on video. **AI**
  </Card>

  <Card title="Visual regression" href="https://github.com/upstash/box/blob/main/packages/sdk/examples/browser/testing/04-visual-regression.ts">
    Pixelmatch diffs against baselines stored on the box.
  </Card>
</CardGroup>