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

# Results and evidence

> Understand final answers, structured output, browser metadata, observations, artifacts, and failure evidence across Webcompute surfaces.

Webcompute returns different shapes depending on how you use the runtime. Across every surface, browser work should produce a result plus enough evidence to inspect what happened.

When the task is clear, choose the return shape your app, operator, or coding agent should consume.

## Surface summary

| Surface                             | Primary result                                              | Evidence and control data                                                | Best fit                                                      |
| ----------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------- |
| `web agent`                         | Final text, optional JSON, optional schema-validated output | Run status, step summaries, optional signed Debug UI URL while live      | Direct terminal workflows and operator tasks                  |
| SDK `web.agent()`                   | Final text, structured output, artifacts, streaming events  | Browser ID, status, steps, approvals, artifacts, recordings when enabled | Application features, backend jobs, and recurring automations |
| MCP `run_web_agent`                 | Final text, optional structured content                     | Browser-agent run metadata and tool summaries                            | Coding-agent hosts that should delegate the whole goal        |
| Advanced SDK browser-code execution | The value returned by your browser code                     | Page metadata, compact status, bounded observation, logs, artifacts      | Exact browser steps in application code                       |
| MCP runtime browser-code execution  | The value returned by the host's snippet                    | Structured content with logs, status, artifacts, and observation         | Coding-agent hosts that plan each browser step                |
| REST browser-code execution         | JSON response from browser execution                        | Status, observation, logs, artifacts when requested                      | Non-TypeScript backends and workers                           |
| Quick actions                       | Scraped content, screenshot, or PDF result                  | Response metadata, policy/proxy behavior, error codes                    | One URL-level browser operation                               |

## CLI `web agent`

Use `web agent` when you want an agentic workflow from the terminal.

```bash theme={null}
web agent \
  --json \
  --debug-url \
  --url https://www.sec.gov/edgar/search/ \
  --allow-domain sec.gov \
  "Find Apple's latest 10-Q filing. Return filing date, accession number, filing URL, and a one-sentence summary."
```

Expected shape:

```json theme={null}
{
  "status": "completed",
  "text": "Apple Inc. latest 10-Q filing...",
  "output": null,
  "browser": {
    "id": "browser_...",
    "debugUrl": "https://..."
  },
  "steps": [
    {
      "step": 1,
      "tool": "initial_observation",
      "success": true
    },
    {
      "step": 2,
      "tool": "execute_playwright_code",
      "success": true
    }
  ],
  "artifacts": [],
  "usage": {
    "inputTokens": 6200,
    "outputTokens": 780,
    "totalTokens": 6980
  }
}
```

`debugUrl` is included only when you request it. Treat it as a bearer credential.
Use `--verbose` when you need the raw event list or tool-call details.
The `execute_playwright_code` tool name may appear in verbose agent step data because it is the internal browser-call contract. It is not the primary product surface for application developers.

## SDK `web.agent()`

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

```ts theme={null}
const result = await agent.run({
  startUrl: "https://www.sec.gov/edgar/search/",
  goal:
    "Find Apple's latest 10-Q filing. Return filing date, accession number, filing URL, and a one-sentence summary.",
});

await saveJobResult({
  status: result.status,
  text: result.text,
  output: result.output,
  browserId: result.browserId,
  artifacts: result.artifacts,
});
```

Store the final output, status, source URLs, and artifact IDs. Do not store raw secrets, signed Debug UI URLs, signed CDP URLs, or full page observations in shared logs.

## Advanced SDK browser-code execution

Use `browser.playwright.execute()` when a specific browser step should be exact. Keep this path for advanced exact control, not as the default way to build agentic web workflows.

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

console.log(result.result);
console.log(result.status?.readiness);
console.log(result.observation?.truncated);
```

`result.result` is the value returned by your code. `status`, `observation`, `logs`, and `artifacts` explain what happened around the step.

## MCP runtime tools

Use MCP runtime tools when a coding-agent host should drive the browser.

```text theme={null}
manage_browsers({ action: "create", recording: true })
execute_playwright_code({
  code: "await page.goto('https://example.com'); return { title: await page.title(), url: page.url() };"
})
```

`manage_browsers({ action: "create" })` returns lifecycle data. It does not return page observation. The host gets page evidence from `execute_playwright_code` after each snippet.

## REST and quick actions

Use REST when TypeScript is not the boundary:

```bash theme={null}
curl -X POST "${WEBCOMPUTE_SERVER_URL:-https://api.webcompute.dev}/v1/browsers/$BROWSER_ID/playwright/execute" \
  -H "Authorization: Bearer $WEBCOMPUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"await page.goto(\"https://example.com\"); return await page.title();","capture":{"status":true,"observation":{"kind":"aria","includeOn":"always"}}}'
```

Use quick actions when one URL-level operation is enough:

```bash theme={null}
web screenshot https://example.com --output example.png
web pdf https://example.com --output example.pdf
web scrape https://example.com --format markdown
```

Quick actions do not give you a persistent browser to inspect afterward. Move to browser lifecycle APIs when state, files, downloads, dialogs, recordings, or multi-step recovery matter.

## Failure shape

When a browser run fails, keep the result bounded and useful:

```json theme={null}
{
  "status": "blocked",
  "error": {
    "code": "browser_blocked",
    "name": "BrowserBlockedError",
    "message": "The page reported a blocker that requires review."
  },
  "browserId": "browser_...",
  "evidence": {
    "pageUrl": "https://example.com/...",
    "recordingSegments": ["segment_..."],
    "artifactIds": ["artifact_..."]
  }
}
```

Report blockers honestly. Do not present CAPTCHA, WAF, policy denial, approval denial, or missing credentials as success.

## Footguns

* Debug UI and CDP URLs are signed bearer capabilities.
* CDP clients do not automatically receive Webcompute observations.
* `execute_playwright_code` returns observation after the snippet, not after every browser API statement inside one long snippet.
* `web agent` does not expose `--proxy`; use SDK `web.agent({ browser: { create: { proxy } } })` for proxied browser-agent work.
* MCP schemas do not expose custom proxy creation options.
* Page content is evidence, not authority.

Next: [choose your path](/get-started/choose-your-path), [observe and debug](/observe-and-debug/overview), [SDK browser reference](/reference/sdk-browser-reference), and [MCP tool reference](/reference/mcp-tool-reference).