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

# Observations

> Understand bounded page evidence returned after Webcompute browser-code execution steps.

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.

```text theme={null}
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.

```ts theme={null}
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:

```yaml theme={null}
- 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](/observe-and-debug/live-browser-sessions)     |
| Replay a run after it finishes       | [Recordings](/observe-and-debug/recordings)                           |
| Retrieve files or generated evidence | [Artifacts and downloads](/observe-and-debug/artifacts-and-downloads) |
| Understand runtime state over time   | [Status, events, and logs](/observe-and-debug/status-events-and-logs) |
| Handle blocked pages                 | [Blockers and CAPTCHA](/observe-and-debug/blockers-and-captcha)       |

Reference: [browser control](/runtime-concepts/browser-control), [SDK browser reference](/reference/sdk-browser-reference), and [MCP tool reference](/reference/mcp-tool-reference).