Custom Agent Integration (Playwright + BrowserBackend)

Updated 2026-02-14 — Attach Predicate verification to a home-made agent loop.

This guide is for anyone with a “generic” web agent:

• a planner/executor loop you wrote yourself
• tools that call Playwright actions
• a CDP-based driver or remote browser service

You don’t need to change your agent architecture. The integration pattern is:

act → snapshot → verify → (retry/branch)

Predicate provides two integration surfaces:

• PredicateDebugger (recommended): a sidecar verifier that attaches to an existing Playwright page
• AgentRuntime: a lower-level runtime verification loop that can run against Playwright or any backend that implements the small BrowserBackend protocol

1) Option A (easiest): attach PredicateDebugger to Playwright (sidecar)

Use this when your agent already owns Playwright (you have a page) and you just want deterministic checks + traces.

from predicate import PredicateDebugger, create_tracer
from predicate.verification import exists, url_contains

# page is a Playwright Page owned by your agent/framework
tracer = create_tracer(run_id="run-123", upload_trace=False)  # local JSONL by default
dbg = PredicateDebugger

2) Option B: use AgentRuntime directly (verification loop API)

Use this when you want a slightly lower-level API than Debugger, or you want to mix verification with runtime helpers (like scroll verification).

from predicate.agent_runtime import AgentRuntime
from predicate.tracing import Tracer, JsonlTraceSink
from predicate.verification import exists

tracer = Tracer(run_id="run-123", sink=JsonlTraceSink("trace.jsonl"))

3) Scroll verification: detect “scroll no-op drift”

A common failure mode is: the agent “scrolls” but the UI does not actually move (overlays, nested scroll containers, focus issues). Predicate includes a runtime helper that scrolls and verifies the scroll had effect via before/after scrollTop.

ok = await runtime.scroll_by(
    600,
    verify=True,
    min_delta_px=50,
    label="scroll_effective",
    required=True,
    timeout_s=5.0,

See also: Verifications.

4) Portability path: implement the BrowserBackend protocol

If you don’t want to couple your verification layer to Playwright, Predicate exposes a small backend protocol:

• Python: sdk-python/predicate/backends/protocol.py
• TypeScript: sdk-ts/src/backends/protocol.ts

As long as your driver implements it (eval/call, wheel, click, screenshot, waitReadyState, etc.), you can run the same verification logic against:

• custom CDP drivers
• remote browser services
• unit-test doubles / fakes

Additional resources

• Predicate Debugger integration
• Verifications (expanded .eventually() + scroll verification)
• Tracing & Debugging