Observations

Observations are bounded page evidence returned after Webcompute browser-code execution steps. They help a coding agent, model-backed agent, or human operator decide what to do next without treating the browser as a black box. In browser-agent runs, observations are captured as part of each browser step. In MCP runtime mode, execute_playwright_code enables a compact observation by default. In SDK browser code, pass capture options when your app needs post-step evidence.

What an observation is

An observation is not a full page archive. It is a bounded snapshot of useful page state, such as:

Page URL and title.
Accessibility or text evidence.
Truncation metadata.
Compact runtime status.
Blocker or CAPTCHA context when detected.
Links to artifacts or activity captured during the step.

Use recordings, artifacts, downloads, screenshots, and Debug UI when you need richer evidence.

MCP default

The MCP runtime surface returns observations from execute_playwright_code so the host can write the next browser-code snippet.

execute_playwright_code({
  code: "await page.goto('https://example.com'); return await page.title();"
})

The returned structured content includes the browser-code return value, runtime status, logs, artifacts, and observation when capture is enabled.

SDK capture

Use capture options when deterministic code needs evidence after execution.

const result = await browser.playwright.execute({
  code: `
    await page.goto("https://example.com");
    return await page.title();
  `,
  capture: {
    status: true,
    observation: {
      kind: "aria",
      includeOn: "always",
      maxChars: 20_000,
    },
  },
});

const statusSummary = result.status
  ? {
      lifecycleStatus: result.status.lifecycleStatus,
      readiness: result.status.readiness,
      blocker: result.status.blocker?.state,
      captcha: result.status.captcha?.state,
    }
  : undefined;

const observationSummary = result.observation
  ? {
      kind: result.observation.kind,
      source: result.observation.source,
      chars: result.observation.chars,
      truncated: result.observation.truncated,
    }
  : undefined;

console.log({
  result: result.result,
  status: statusSummary,
  observation: observationSummary,
});

The same local run that produced the screenshot on the overview returned this observation:

- generic:
  - heading "Example Domain"
  - paragraph: This domain is for use in documentation examples without needing permission.
  - paragraph:
    - link "Learn more"
      - /url: https://iana.org/domains/example

That is enough for the next step to know the page loaded, the heading is visible, and the browser is still inside a harmless documentation page. It is not a substitute for focused extraction when the workflow needs every row or record. Do not log raw observations by default. Observations can include page text, ARIA snapshots, form labels, and other browser-session evidence. Store metadata such as kind, character count, and truncation state, then open recordings, artifacts, Debug UI, or scoped extraction output when an approved reviewer needs the underlying evidence.

How to use observations

Use observations to answer narrow next-step questions:

Did navigation land on the expected page?
Is the expected heading, link, form, or blocker visible?
Did the page ask for confirmation or credentials?
Should the next step continue, retry, ask for approval, or stop?

Do not use observations as proof that every page element was captured. They are intentionally bounded so agents can consume them safely.

When to use richer evidence

Need	Use
Watch the current browser	Live browser sessions
Replay a run after it finishes	Recordings
Retrieve files or generated evidence	Artifacts and downloads
Understand runtime state over time	Status, events, and logs
Handle blocked pages	Blockers and CAPTCHA

Reference: browser control, SDK browser reference, and MCP tool reference.

Get started

Build agent workflows

Observe and debug

Runtime concepts

Examples

Integrations

Production

Reference

API reference

What an observation is

MCP default

SDK capture

How to use observations

When to use richer evidence

​What an observation is

​MCP default

​SDK capture

​How to use observations

​When to use richer evidence

What an observation is

MCP default

SDK capture

How to use observations

When to use richer evidence