Exploration Modes

PyBA supports four exploration modes designed for different use cases. This page explains when and how to use each.

Overview

Mode	Use Case	How It Works
Normal	Direct tasks	Execute actions sequentially until done
Step	Interactive control	User feeds instructions one at a time
DFS	Deep investigation	One detailed plan at a time, retry with new plans if stuck
BFS	Wide discovery	Multiple plans executed in parallel

Normal Mode

The default mode. Best for straightforward tasks with clear steps.

from pyba import Engine

engine = Engine(openai_api_key="sk-...")

result = engine.sync_run(
    prompt="Go to Wikipedia and find the population of Tokyo"
)

When to use Normal mode:

• Simple, direct tasks

• When the path to completion is clear

• Form filling, single-page scraping

• Quick lookups

Configuration:

engine = Engine(
    openai_api_key="sk-...",
    max_depth=20   # Maximum actions before stopping
)

Step Mode

Step mode gives you interactive, step-by-step control over a persistent browser session. You feed one instruction at a time, and the browser stays open between calls.

Unlike other modes where a single run() call handles everything, Step mode splits the lifecycle into three methods:

• start() launches the browser

• step() executes one instruction

• stop() tears down the browser

from pyba import Step

step = Step(openai_api_key="sk-...")

await step.start()

await step.step("Go to google.com and search for 'playwright python'")
await step.step("Click the first result")
output = await step.step("Extract the installation instructions")

await step.stop()

How Step Works:

1. start() launches a stealth browser and keeps it alive on the instance

2. Each step() call takes one user instruction and executes up to max_actions_per_step actions to fulfill it

3. The model tracks what it did within a single step() call to avoid repeating actions

4. When the model decides the instruction is complete, it returns an output

5. The DOM is re-extracted after each action so the next call has a fresh view

6. stop() saves the trace and shuts down the browser

When to use Step mode:

• Interactive workflows where you want control between instructions

• Debugging or exploring a site manually with AI assistance

• Building conversational browser agents

• When you want to inspect results between actions

Sync usage:

step = Step(openai_api_key="sk-...")

step.sync_start()
step.sync_step("Go to news.ycombinator.com")
step.sync_step("Click the top story")
output = step.sync_step("Extract the title and top 3 comments")
step.sync_stop()

Configuration:

step = Step(
    openai_api_key="sk-...",
    max_actions_per_step=5,  # Max actions per instruction (default: 5)
    get_output=False         # If True, asks the model for a summary when a step completes (default: False)
)

DFS Mode (Depth-First Search)

DFS mode is designed for deep investigation tasks. It generates one detailed plan at a time and executes it fully before generating a new plan based on what was learned.

from pyba import DFS, Database

database = Database(engine="sqlite", name="/tmp/pyba.db")

dfs = DFS(
    openai_api_key="sk-...",
    database=database,
    max_depth=10,    # Actions per plan
    max_breadth=5    # Number of plans to try
)

result = dfs.sync_run(
    prompt="Investigate this person's digital footprint across social media"
)

How DFS Works:

1. The Planner Agent generates one detailed plan for the task

2. PyBA executes the plan up to max_depth actions

3. If the goal isn’t achieved, it generates a new plan based on:

   • What was accomplished

   • What was discovered

   • What didn’t work

4. This repeats up to max_breadth times

When to use DFS mode:

• OSINT investigations

• Following chains of information

• Tasks requiring reasoning about intermediate results

• When you need to adapt based on what you find

Example: Company Research

from pyba import DFS, Database

db = Database(engine="sqlite", name="/tmp/research.db")
dfs = DFS(openai_api_key="sk-...", database=db)

result = dfs.sync_run(
    prompt="Research Acme Corp: find their leadership team, recent news, and funding history"
)

BFS Mode (Breadth-First Search)

BFS mode explores multiple approaches in parallel. It generates several plans upfront and executes them simultaneously in separate browser windows.

from pyba import BFS, Database

database = Database(engine="sqlite", name="/tmp/pyba.db")

bfs = BFS(
    openai_api_key="sk-...",
    database=database,
    max_depth=10,    # Actions per plan
    max_breadth=5    # Number of parallel plans
)

results = bfs.sync_run(
    prompt="Find all social media accounts linked to username 'targetuser123'"
)

How BFS Works:

1. The Planner Agent generates max_breadth different plans

2. Each plan runs in its own browser instance in parallel

3. Each plan executes up to max_depth actions

4. Results from all plans are collected and returned

When to use BFS mode:

• Casting a wide net

• When multiple approaches might work

• Searching across different platforms simultaneously

• Discovery tasks

Example: Social Media Discovery

from pyba import BFS, Database

db = Database(engine="sqlite", name="/tmp/discovery.db")
bfs = BFS(openai_api_key="sk-...", database=db)

results = bfs.sync_run(
    prompt="Find information about 'john_doe_123' across Twitter, LinkedIn, GitHub, and Instagram"
)

# results is a list with output from each parallel plan
for i, result in enumerate(results):
    print(f"Plan {i+1}: {result}")

Configuration Reference

All modes share these parameters:

# Common parameters
openai_api_key="..."          # Or gemini_api_key, or vertexai_*
model_name=None                # Override default model for the chosen provider
headless=True                  # Browser visibility
use_logger=False               # Console logging
enable_tracing=False           # Trace file generation
trace_save_directory=None      # Where to save traces
database=None                  # Database instance
low_memory=False               # Reduce browser resource usage

# Step-specific
max_actions_per_step=5         # Max actions per instruction

# DFS and BFS-specific
max_depth=10                   # Actions per plan
max_breadth=5                  # DFS: plans to try, BFS: parallel plans

Choosing the Right Mode

Task Type	Recommended Mode
Fill out a form	Normal
Scrape a single page	Normal
Interactive browser exploration	Step
Conversational browser agent	Step
Debugging a workflow step by step	Step
Investigate a person/company	DFS
Follow a chain of links	DFS
Search multiple platforms	BFS
Map out a website	BFS
Find accounts across sites	BFS
Deep research on one topic	DFS

The Planner Agent

In DFS and BFS modes, a Planner Agent generates high-level plans before execution.

DFS Planner Output:

A single detailed plan string that guides the automation.

BFS Planner Output:

A list of plan strings, each executed in parallel.

The planner considers:

• The user’s task

• Previous plans that were tried (DFS only)

• What approaches might work best

You don’t interact with the Planner Agent directly—it’s called automatically when using DFS or BFS modes.

Database Requirement

Note

DFS and BFS modes work best with a database configured. The database stores:

• Action history for plan generation

• Session information across browser instances

• Logs for debugging and code generation

from pyba import DFS, BFS, Database

# Always use a database with DFS/BFS
db = Database(engine="sqlite", name="/tmp/pyba.db")

dfs = DFS(openai_api_key="...", database=db)
bfs = BFS(openai_api_key="...", database=db)