Predicate Runtime Quick Start Guide

Get started with Predicate SDK in 5 minutes. This guide walks you through a complete login automation example.

1 Install the SDK

Install the Predicate SDK for your preferred language:

# Install the Python SDK
pip install predicate-runtime

# Install Chromium browser (required for automation)
playwright install chromium

2 Get Your API Key (Optional)

API key enables smarter filtering and saves LLM token usage

Sign up at predicatesystems.ai to get your API key. You can also test locally without an API key.

export PREDICATE_API_KEY="sk_..."

3 Use Predicate Debugger with Your Existing Agent

If you already have an AI web agent (LangChain, browser-use, your own loop), you can keep it — and attach Predicate Debugger as a verification + tracing sidecar.

Full Example: Agent Loop + PredicateDebugger Verification

Notes:

• page is the Playwright Page owned by your agent/framework.
• Tracer writes a JSONL trace you can inspect in Predicate Studio later.
• If you want to test locally without an API key, set use_api: false in snapshot() options.

import asyncio

from predicate import PredicateDebugger
from predicate.tracing import Tracer, JsonlTraceSink
from predicate.verification import exists, url_contains


class MyAgent:
    """
    Your existing agent/framework.
    It owns the browser and returns a Playwright Page.

4 Run Your Script

python your_script.py

Run the script that contains your agent loop. If you used the examples above, this will open a browser, execute your agent step(s), and then run Predicate verification.

5 Drive the Loop with the Predicate SDK (Optional)

If you don't already have an agent framework, you can also use the Predicate SDK directly to drive the browser with snapshots + actions.

Login Form Example (SDK-driven)

from predicate import PredicateBrowser, snapshot, find, type_text, click, wait_for

# Create browser instance
with PredicateBrowser(api_key="sk_...") as browser:
    # Navigate to login page
    browser.page.

What You Learned

• How to attach Predicate Debugger to an existing Playwright page
• How to create a Tracer to record a run trace (trace.jsonl)
• How to take local-only snapshots with use_api: false (no API key required)
• How to add assertions dynamically after your agent acts
• How to use .once() and .eventually() to make outcomes deterministic
• (Optional) How to drive a browser loop directly with the Predicate SDK

Common Questions

Do I need an API key to test locally?

No! You can use use_api=False to process everything locally. This won't charge credits but also won't include importance ranking.

How do semantic queries work?

Queries use operators like role=button, text~"Submit" (contains), importance>500. See the full reference for all operators.

What if an element isn't found?

Use wait_for() to wait for elements to appear. Check element visibility with element.in_viewport and element.is_occluded.

Next Steps

• Choose your path → - Sidecar Debugger vs SDK-driven loops
• SDK Reference → - Explore all SDK functions
• Examples → - See more real-world use cases
• Attach Predicate Debugger to Your Existing Agent → - Add verification + traces without changing your agent framework
• Playground → - Try demos on GitHub