Sentience Python SDK: browser-use Integration Guide

pip install "sentienceapi[browser-use]"

pip install sentienceapi browser-use

from sentience import get_extension_dir
from sentience.backends import SentienceContext

print(f"Extension path: {get_extension_dir()}")
print("Installation successful!")

import asyncio
from browser_use import BrowserSession, BrowserProfile
from sentience import get_extension_dir
from sentience.backends import SentienceContext

async def main():
  # 1. Setup browser with Sentience extension
  profile = BrowserProfile(
      args=[f"--load-extension={get_extension_dir()}"]
  )
  session = BrowserSession(browser_profile=profile)
  await session.start()

  # 2. Create context builder
  ctx = SentienceContext(max_elements=60)

  # 3. Navigate and build context
  await session.navigate("https://news.ycombinator.com")
  state = await ctx.build(session, goal="Find the first Show HN post")

  if state:
      print(f"Found {len(state.snapshot.elements)} elements")
      print(f"Prompt block:
{state.prompt_block[:500]}...")

  await session.stop()

asyncio.run(main())

from sentience.backends import SentienceContext, TopElementSelector

ctx = SentienceContext(
  sentience_api_key: str | None = None,    # API key for gateway mode
  use_api: bool | None = None,              # Force API vs extension mode
  max_elements: int = 60,                   # Maximum elements to fetch
  show_overlay: bool = False,               # Show visual overlay on elements
  top_element_selector: TopElementSelector | None = None,  # Selection strategy
)

state = await ctx.build(
  browser_session,                      # browser-use BrowserSession
  goal: str | None = None,              # Task description for reranking
  wait_for_extension_ms: int = 5000,    # Extension load timeout
  retries: int = 2,                     # Retry attempts on failure
  retry_delay_s: float = 1.0,           # Delay between retries
) -> SentienceContextState | None

from sentience.backends import TopElementSelector

selector = TopElementSelector(
  by_importance: int = 60,        # Top N by importance score
  from_dominant_group: int = 15,  # Top N from dominant group
  by_position: int = 10,          # Top N by page position (lowest Y)
)

@dataclass
class SentienceContextState:
  url: str                # Current page URL
  snapshot: Snapshot      # Full Sentience snapshot with all elements
  prompt_block: str       # Compact LLM-ready context block

from sentience.backends import BrowserUseAdapter

adapter = BrowserUseAdapter(browser_session)
backend = await adapter.create_backend()

from browser_use import BrowserSession, BrowserProfile
from sentience import get_extension_dir
from sentience.backends import BrowserUseAdapter, snapshot, click

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

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

# Use backend for snapshots and actions
snap = await snapshot(backend)
await click(backend, snap.elements[0].bbox)

from sentience.backends import CachedSnapshot

cache = CachedSnapshot(
  backend,                # Backend instance
  max_age_ms: int = 2000  # Cache TTL in milliseconds
)

cache = CachedSnapshot(backend, max_age_ms=2000)

snap1 = await cache.get()  # Takes fresh snapshot
snap2 = await cache.get()  # Returns cached (if < 2s old)

await click(backend, element.bbox)
cache.invalidate()  # Force refresh after DOM-modifying action

snap3 = await cache.get()  # Takes fresh snapshot

from sentience.backends import snapshot

snap = await snapshot(backend, options=None)

from sentience.backends import click

await click(backend, bbox)

from sentience.backends import type_text

await type_text(backend, text, delay_ms=50)

from sentience.backends import scroll

await scroll(backend, delta_y=500)                    # Scroll down 500px
await scroll(backend, delta_y=-300)                   # Scroll up 300px
await scroll(backend, delta_y=300, target=(400, 500)) # Scroll at position

from sentience import find

element = find(snapshot, 'role=textbox[name*="Search"]')

from sentience import query

links = query(snapshot, 'role=link')
print(f"Found {len(links)} links")

from sentience.backends import (
  SentienceBackendError,
  ExtensionNotLoadedError,
  SnapshotError,
  ActionError,
)

try:
  snap = await snapshot(backend)
except ExtensionNotLoadedError as e:
  print(f"Extension not loaded. Fix: {e}")
except SnapshotError as e:
  print(f"Snapshot failed: {e}")
except ActionError as e:
  print(f"Action failed: {e}")

# overlay to show bounding box with green border on top elements in Snapshot
# highlighted border automatically disappears after 5 seconds
ctx = SentienceContext(show_overlay=True)

cache = CachedSnapshot(backend, max_age_ms=2000)

snap = await cache.get()
await click(backend, button.bbox)  # This may change the DOM
cache.invalidate()                  # Force refresh
snap = await cache.get()           # Fresh snapshot

state = await ctx.build(
  session,
  goal="Click the first search result"  # Helps with ordinal ranking
)

state = await ctx.build(
  session,
  wait_for_extension_ms=5000,  # Wait up to 5 seconds
  retries=3,                    # Retry on failure
)

import asyncio
from browser_use import BrowserSession, BrowserProfile, Agent, ChatBrowserUse
from sentience import get_extension_dir, find
from sentience.backends import (
  SentienceContext,
  TopElementSelector,
  BrowserUseAdapter,
  snapshot,
  click,
  type_text,
)

async def main():
  # Setup browser with Sentience extension
  profile = BrowserProfile(
      args=[
          "--enable-extensions",
          f"--load-extension={get_extension_dir()}",
      ]
  )
  session = BrowserSession(browser_profile=profile)
  await session.start()

  # Navigate to target page
  await session.navigate("https://news.ycombinator.com")

  # Option A: High-level SentienceContext API
  ctx = SentienceContext(
      max_elements=60,
      show_overlay=True,  # Visual debugging
      top_element_selector=TopElementSelector(
          by_importance=60,
          from_dominant_group=15,
          by_position=10,
      ),
  )

  state = await ctx.build(
      session,
      goal="Find the first Show HN post",
      wait_for_extension_ms=5000,
  )

  if state:
      print(f"URL: {state.url}")
      print(f"Elements: {len(state.snapshot.elements)}")
      print(f"
Prompt block:
{state.prompt_block}")

  # Option B: Low-level API for direct control
  adapter = BrowserUseAdapter(session)
  backend = await adapter.create_backend()

  snap = await snapshot(backend)
  search_link = find(snap, 'role=link[name*="Show HN"]')

  if search_link:
      await click(backend, search_link.bbox)
      print(f"Clicked: {search_link.text}")

  await session.stop()

if __name__ == "__main__":
  asyncio.run(main())