This directory contains examples for integrating Sentience with browser-use.
browser-use is an open-source framework for building AI agents that can interact with web browsers. Sentience enhances browser-use by providing:
- Semantic element detection — Accurate element identification using visual and structural cues
- Token-slashed DOM context — Reduces tokens by ~80% compared to raw DOM dumps
- Importance-ranked elements — Elements sorted by actionability for better LLM targeting
- Ordinal task support — "Click the 3rd item" works reliably with dominant group detection
Install both packages together using the optional dependency:
pip install "predicate-runtime[browser-use]"Or install separately:
pip install predicate-runtime browser-useSentienceContext provides a high-level API for getting compact, ranked DOM context:
frombrowser_useimportBrowserSession, BrowserProfilefrompredicateimportget_extension_dirfrompredicate.backendsimportSentienceContext, TopElementSelector# Setup browser with Sentience extensionprofile=BrowserProfile(
args=[f"--load-extension={get_extension_dir()}"],
)
session=BrowserSession(browser_profile=profile)
awaitsession.start()
# Create context builderctx=SentienceContext(
max_elements=60,
top_element_selector=TopElementSelector(
by_importance=60, # Top N by importance scorefrom_dominant_group=15, # Top N from dominant groupby_position=10, # Top N by page position
),
)
# Build context from browser sessionawaitsession.navigate("https://news.ycombinator.com")
state=awaitctx.build(
session,
goal="Find the first Show HN post",
wait_for_extension_ms=5000,
)
ifstate:
print(f"URL: {state.url}")
print(f"Elements: {len(state.snapshot.elements)}")
print(f"Prompt block:\n{state.prompt_block}")For fine-grained control over snapshots and actions:
frompredicateimportfind, query, get_extension_dirfrompredicate.backendsimportBrowserUseAdapter, snapshot, click, type_text# Create adapter and backendadapter=BrowserUseAdapter(session)
backend=awaitadapter.create_backend()
# Take snapshotsnap=awaitsnapshot(backend)
# Find and interact with elementssearch_box=find(snap, 'role=textbox[name*="Search"]')
ifsearch_box:
awaitclick(backend, search_box.bbox)
awaittype_text(backend, "Sentience AI")| File | Description |
|---|---|
| integration.py | Complete integration example with SentienceContext |
The SentienceContext.build() method returns a SentienceContextState with:
url— Current page URLsnapshot— Full Sentience snapshot with all elementsprompt_block— Compact LLM-ready context block
The prompt block format:
Elements: ID|role|text|imp|is_primary|docYq|ord|DG|href
Rules: ordinal→DG=1 then ord asc; otherwise imp desc. Use click(ID)/input_text(ID,...).
1|link|Show HN: My Project|85|1|2|0|1|ycombinato
2|link|Ask HN: Best practices|80|0|3|1|1|ycombinato
...
Fields:
ID— Element ID for actionsrole— Semantic role (button, link, textbox, etc.)text— Truncated element text (max 30 chars)imp— Importance score (0-100)is_primary— 1 if primary CTA, 0 otherwisedocYq— Quantized Y position (doc_y / 200)ord— Ordinal rank within dominant group, or "-"DG— 1 if in dominant group, 0 otherwisehref— Compressed href token
SentienceContext(
sentience_api_key: str|None=None, # API key for gateway modeuse_api: bool|None=None, # Force API vs extension modemax_elements: int=60, # Max elements to fetchshow_overlay: bool=False, # Show visual overlaytop_element_selector: TopElementSelector|None=None,
)TopElementSelector(
by_importance: int=60, # Top N by importance scorefrom_dominant_group: int=15, # Top N from dominant groupby_position: int=10, # Top N by page position
)awaitctx.build(
browser_session, # browser-use BrowserSessiongoal: str|None=None, # Task description for rerankingwait_for_extension_ms: int=5000, # Extension load timeoutretries: int=2, # Retry attemptsretry_delay_s: float=1.0, # Delay between retries
) ->SentienceContextState|NoneSentience SDK is dual-licensed under MIT and Apache-2.0.
browser-use is licensed under MIT. See THIRD_PARTY_LICENSES.md.