Predicate Runtime Overview

Predicate is an authority and governance layer for AI web agents. At runtime, it combines identity-aware policy checks with deterministic snapshot/assertion enforcement.

Identity → Mandate → Action → Verification → Audit

• Authorize before side effects.
• Use snapshots/assertions as deterministic enforcement evidence.
• Keep your current framework; add policy, revocation, and trace visibility.

The SDK runs standalone with Playwright or embeds under frameworks like browser-use. Gateway API is optional; local execution paths still support authority-aligned enforcement patterns.

Predicate Runtime

The deterministic operating layer for AI agents.

• Perception: Turn noisy DOMs into clean, token-optimized state representations.
• Debugger: Time-travel debugging for agent execution steps.
• Verification: Cryptographic proof of state and action outcomes.

Install:

pip install predicate-runtime
npm install @predicatesystems/runtime

Authority-first execution model

1. Resolve agent principal + task context (tenant/session/intent)
2. Evaluate policy and mandate requirements before action
3. Execute actions with deterministic runtime controls
4. Attach verification signals and emit auditable artifacts

This keeps governance primary while preserving the same developer ergonomics for existing web-agent loops.

How It Works

Predicate operates in two modes:

Not sure which mode to start with? Choose your path →

Mode A: Local (Extension-Only, fastest path)

1. SDK calls the browser extension to collect raw + semantic geometry
2. SDK produces a snapshot prompt (structured text, ~0.6–1.2k tokens)
3. Optional pre-action policy hook authorizes the next action
4. SDK executes via the backend protocol
5. SDK runs assert_ checks and records trace/audit evidence

No server calls required. Works offline and with local LLMs.

Mode B: Gateway (Optional, production boost)

Same flow as above, but between steps 1 and 2:

• Raw elements are sent to the Gateway for heuristic filtering, dominant group detection, and ONNX-based reranking (goal-conditioned)

Gateway is optional — use it for production accuracy boosts, not required for development.

What's in a Semantic Snapshot

Each snapshot contains elements with these key fields:

Compact format example:

ID|role|text|imp|docYq|ord|DG|href
42|button|Add to Cart|95|480|0|true|
43|link|Product Details|70|520|1|true|/products/123
44|button|Buy Now|90|480|2|true|
45|link|Reviews|60|560|3|true|#reviews
46|input|Search|80|100|0|false|

This structured format lets LLMs make deterministic selections without parsing raw HTML.

Token Usage

Semantic snapshots are designed for token efficiency:

• ~0.6–1.2k tokens per step (typical snapshot prompt)
• Compare to vision: 10–50k tokens per screenshot
• Compare to raw DOM: 5–20k tokens

Why it helps:

• Fewer screenshots needed (structured data replaces vision)
• Bounded action space (only actionable elements included)
• No DOM spam (filtered and ranked by importance)

Token savings vary by page complexity, but the bounded format consistently keeps prompts small enough for local LLMs like Qwen 2.5 3B.

Assertions (assert_)

Assertions are machine-verifiable checks over fresh snapshots. They help agents know when they're "done" and prevent drift.

Available assertions:

Additional predicates (by use-case):

• download_completed(...) — verify a file download finished
• is_enabled / is_disabled / is_checked / value_contains — verify form/control state

Example usage:

await runtime.snapshot()
runtime.assert_(exists("role=button"), label="has_buttons")
runtime.assert_(url_contains("checkout"), label="on_checkout")

if runtime.assert_done(exists("text~'Order confirmed'"), label="complete"):
    print("Task finished!")

browser-use Integration

Predicate integrates with browser-use via a backend adapter, enabling:

• Screenshots-off runs (semantic snapshots replace vision)
• Local LLM support (Qwen 2.5 3B works reliably with bounded prompts)
• Full tracing and assertions on top of browser-use actions

Installation:

pip install "predicate-runtime[browser-use]"

Usage:

from browser_use import BrowserSession, BrowserProfile
from predicate import get_extension_dir
from predicate.backends import BrowserUseAdapter
from predicate.agent_runtime import AgentRuntime

# Setup browser-use with Predicate extension
profile = BrowserProfile(args=[f"--load-extension={get_extension_dir()}"])
session = BrowserSession(browser_profile=profile)
await session.start()

# Create backend adapter
adapter = BrowserUseAdapter(session)
backend = await adapter.create_backend()

# Create runtime for assertions
runtime = AgentRuntime(backend=backend, tracer=tracer)
await runtime.snapshot()
runtime.assert_(exists("role=button"), label="ready")

See the browser-use integration guide for full details.

Live demos and examples:

• Multi-step agent with Qwen 2.5 3B + semantic assertions
• Jest-style assertions for agents
• Local LLM (Qwen 2.5 3B) demo in browser-use
• Token usage comparison: Semantic snapshots vs screenshots

Traces and Replay

Every agent run produces a trace containing:

• Snapshots at each step
• Actions executed (click, type, scroll)
• Assertion results (pass/fail with labels)
• Screenshots (optional)

Traces enable:

• Debugging: Step through what the agent saw and did
• Regression testing: Compare traces across runs
• CI validation: Assert expected behavior in automated tests

Traces can be stored locally (JSON/JSONL) or uploaded to Predicate Studio for visual debugging.

Open Source Repositories

• Python SDK — pip install predicate-runtime
• TypeScript SDK — npm install @predicatesystems/runtime

Next Steps

• Installation → — Install Python or TypeScript SDK
• Quick Start → — Get started in 5 minutes
• Agent Runtime → — Jest-style assertions for agents
• Ordinality & Layout → — Position-based selection
• Lifecycle Hooks → — Observe step boundaries (metrics, UI, logging)
• Downloads → — Assert that files were actually downloaded
• Permissions → — Avoid permission bubbles; grant/clear mid-run
• Tool Registry → — Typed, auditable tools (plus filesystem sandbox)
• browser-use Integration → — Use with browser-use