Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

docs: update hooks complex example to work with latest release

Marian Schneiderd827aea29b67
diff --git a/docs/customize/hooks.mdx b/docs/customize/hooks.mdx
index 697a3efe5..06a8bccbf 100644
--- a/docs/customize/hooks.mdx
+++ b/docs/customize/hooks.mdx
@@ -132,7 +132,7 @@ To use this example, you'll need to:
1. Set up the required dependencies:
```bash
- pip install fastapi uvicorn prettyprinter pyobjtojson dotenv browser-use
+ uv pip install fastapi uvicorn prettyprinter pyobjtojson dotenv browser-use
```
2. Create two separate Python files:
@@ -156,74 +156,77 @@ The server component handles receiving and storing the agent's activity data:
# Save this code to api.py and run with `python api.py`
#
-import json
import base64
+import json
from pathlib import Path
-from fastapi import FastAPI, Request
import prettyprinter
import uvicorn
+from fastapi import FastAPI, Request
prettyprinter.install_extras()
+
# Utility function to save screenshots
def b64_to_png(b64_string: str, output_file):
- """
- Convert a Base64-encoded string to a PNG file.
+ """
+ Convert a Base64-encoded string to a PNG file.
+
+ :param b64_string: A string containing Base64-encoded data
+ :param output_file: The path to the output PNG file
+ """
+ with open(output_file, 'wb') as f:
+ f.write(base64.b64decode(b64_string))
- :param b64_string: A string containing Base64-encoded data
- :param output_file: The path to the output PNG file
- """
- with open(output_file, "wb") as f:
- f.write(base64.b64decode(b64_string))
# Initialize FastAPI app
app = FastAPI()
[email protected]("/post_agent_history_step")
[email protected]('/post_agent_history_step')
async def post_agent_history_step(request: Request):
- data = await request.json()
- prettyprinter.cpprint(data)
-
- # Ensure the "recordings" folder exists using pathlib
- recordings_folder = Path("recordings")
- recordings_folder.mkdir(exist_ok=True)
-
- # Determine the next file number by examining existing .json files
- existing_numbers = []
- for item in recordings_folder.iterdir():
- if item.is_file() and item.suffix == ".json":
- try:
- file_num = int(item.stem)
- existing_numbers.append(file_num)
- except ValueError:
- # In case the file name isn't just a number
- pass
-
- if existing_numbers:
- next_number = max(existing_numbers) + 1
- else:
- next_number = 1
-
- # Construct the file path
- file_path = recordings_folder / f"{next_number}.json"
-
- # Save the JSON data to the file
- with file_path.open("w") as f:
- json.dump(data, f, indent=2)
-
- # Optionally save screenshot if needed
- # if "website_screenshot" in data and data["website_screenshot"]:
- # screenshot_folder = Path("screenshots")
- # screenshot_folder.mkdir(exist_ok=True)
- # b64_to_png(data["website_screenshot"], screenshot_folder / f"{next_number}.png")
-
- return {"status": "ok", "message": f"Saved to {file_path}"}
-
-if __name__ == "__main__":
- print("Starting Browser-Use recording API on http://0.0.0.0:9000")
- uvicorn.run(app, host="0.0.0.0", port=9000)
+ data = await request.json()
+ prettyprinter.cpprint(data)
+
+ # Ensure the "recordings" folder exists using pathlib
+ recordings_folder = Path('recordings')
+ recordings_folder.mkdir(exist_ok=True)
+
+ # Determine the next file number by examining existing .json files
+ existing_numbers = []
+ for item in recordings_folder.iterdir():
+ if item.is_file() and item.suffix == '.json':
+ try:
+ file_num = int(item.stem)
+ existing_numbers.append(file_num)
+ except ValueError:
+ # In case the file name isn't just a number
+ pass
+
+ if existing_numbers:
+ next_number = max(existing_numbers) + 1
+ else:
+ next_number = 1
+
+ # Construct the file path
+ file_path = recordings_folder / f'{next_number}.json'
+
+ # Save the JSON data to the file
+ with file_path.open('w') as f:
+ json.dump(data, f, indent=2)
+
+ # Optionally save screenshot if needed
+ # if "website_screenshot" in data and data["website_screenshot"]:
+ # screenshot_folder = Path("screenshots")
+ # screenshot_folder.mkdir(exist_ok=True)
+ # b64_to_png(data["website_screenshot"], screenshot_folder / f"{next_number}.png")
+
+ return {'status': 'ok', 'message': f'Saved to {file_path}'}
+
+
+if __name__ == '__main__':
+ print('Starting Browser-Use recording API on http://0.0.0.0:9000')
+ uvicorn.run(app, host='0.0.0.0', port=9000)
```
### Client Component (client.py)
@@ -239,140 +242,135 @@ The client component runs the Browser-Use agent with a recording hook:
#
import asyncio
+
import requests
from dotenv import load_dotenv
from pyobjtojson import obj_to_json
-from browser_use.llm import ChatOpenAI
+
from browser_use import Agent
+from browser_use.browser.events import ScreenshotEvent
+from browser_use.llm import ChatOpenAI
# Load environment variables (for API keys)
load_dotenv()
def send_agent_history_step(data):
- """Send the agent step data to the recording API"""
- url = "http://127.0.0.1:9000/post_agent_history_step"
- response = requests.post(url, json=data)
- return response.json()
+ """Send the agent step data to the recording API"""
+ url = 'http://127.0.0.1:9000/post_agent_history_step'
+ response = requests.post(url, json=data)
+ return response.json()
async def record_activity(agent_obj):
- """Hook function that captures and records agent activity at each step"""
- website_html = None
- website_screenshot = None
- urls_json_last_elem = None
- model_thoughts_last_elem = None
- model_outputs_json_last_elem = None
- model_actions_json_last_elem = None
- extracted_content_json_last_elem = None
-
- print('--- ON_STEP_START HOOK ---')
-
- # Capture current page state
- website_html = await agent_obj.browser_session.get_page_html()
- website_screenshot = await agent_obj.browser_session.take_screenshot()
-
- # Make sure we have state history
- if hasattr(agent_obj, "state"):
- history = agent_obj.state.history
- else:
- history = None
- print("Warning: Agent has no state history")
- return
-
- # Process model thoughts
- model_thoughts = obj_to_json(
- obj=history.model_thoughts(),
- check_circular=False
- )
- if len(model_thoughts) > 0:
- model_thoughts_last_elem = model_thoughts[-1]
-
- # Process model outputs
- model_outputs = agent_obj.state.history.model_outputs()
- model_outputs_json = obj_to_json(
- obj=model_outputs,
- check_circular=False
- )
- if len(model_outputs_json) > 0:
- model_outputs_json_last_elem = model_outputs_json[-1]
-
- # Process model actions
- model_actions = agent_obj.state.history.model_actions()
- model_actions_json = obj_to_json(
- obj=model_actions,
- check_circular=False
- )
- if len(model_actions_json) > 0:
- model_actions_json_last_elem = model_actions_json[-1]
-
- # Process extracted content
- extracted_content = agent_obj.state.history.extracted_content()
- extracted_content_json = obj_to_json(
- obj=extracted_content,
- check_circular=False
- )
- if len(extracted_content_json) > 0:
- extracted_content_json_last_elem = extracted_content_json[-1]
-
- # Process URLs
- urls = agent_obj.state.history.urls()
- urls_json = obj_to_json(
- obj=urls,
- check_circular=False
- )
- if len(urls_json) > 0:
- urls_json_last_elem = urls_json[-1]
-
- # Create a summary of all data for this step
- model_step_summary = {
- "website_html": website_html,
- "website_screenshot": website_screenshot,
- "url": urls_json_last_elem,
- "model_thoughts": model_thoughts_last_elem,
- "model_outputs": model_outputs_json_last_elem,
- "model_actions": model_actions_json_last_elem,
- "extracted_content": extracted_content_json_last_elem
- }
-
- print("--- MODEL STEP SUMMARY ---")
- print(f"URL: {urls_json_last_elem}")
-
- # Send data to the API
- result = send_agent_history_step(data=model_step_summary)
- print(f"Recording API response: {result}")
+ """Hook function that captures and records agent activity at each step"""
+ website_html = None
+ website_screenshot = None
+ urls_json_last_elem = None
+ model_thoughts_last_elem = None
+ model_outputs_json_last_elem = None
+ model_actions_json_last_elem = None
+ extracted_content_json_last_elem = None
+
+ print('--- ON_STEP_START HOOK ---')
+
+ # Capture current page state
+ cdp_session = await agent_obj.browser_session.get_or_create_cdp_session()
+ doc = await cdp_session.cdp_client.send.DOM.getDocument(session_id=cdp_session.session_id)
+ html_result = await cdp_session.cdp_client.send.DOM.getOuterHTML(
+ params={'nodeId': doc['root']['nodeId']}, session_id=cdp_session.session_id
+ )
+ website_html = html_result['outerHTML']
+
+ # Get screenshot using event system
+ screenshot_event = agent_obj.browser_session.event_bus.dispatch(ScreenshotEvent(full_page=False))
+ await screenshot_event
+ website_screenshot = await screenshot_event.event_result(raise_if_any=True, raise_if_none=True)
+
+ # Make sure we have agent history
+ if hasattr(agent_obj, 'history'):
+ history = agent_obj.history
+ else:
+ history = None
+ print('Warning: Agent has no history')
+ return
+
+ # Process model thoughts
+ model_thoughts = obj_to_json(obj=history.model_thoughts(), check_circular=False)
+ if len(model_thoughts) > 0:
+ model_thoughts_last_elem = model_thoughts[-1]
+
+ # Process model outputs
+ model_outputs = history.model_outputs()
+ model_outputs_json = obj_to_json(obj=model_outputs, check_circular=False)
+ if len(model_outputs_json) > 0:
+ model_outputs_json_last_elem = model_outputs_json[-1]
+
+ # Process model actions
+ model_actions = history.model_actions()
+ model_actions_json = obj_to_json(obj=model_actions, check_circular=False)
+ if len(model_actions_json) > 0:
+ model_actions_json_last_elem = model_actions_json[-1]
+
+ # Process extracted content
+ extracted_content = history.extracted_content()
+ extracted_content_json = obj_to_json(obj=extracted_content, check_circular=False)
+ if len(extracted_content_json) > 0:
+ extracted_content_json_last_elem = extracted_content_json[-1]
+
+ # Process URLs
+ urls = history.urls()
+ urls_json = obj_to_json(obj=urls, check_circular=False)
+ if len(urls_json) > 0:
+ urls_json_last_elem = urls_json[-1]
+
+ # Create a summary of all data for this step
+ model_step_summary = {
+ 'website_html': website_html,
+ 'website_screenshot': website_screenshot,
+ 'url': urls_json_last_elem,
+ 'model_thoughts': model_thoughts_last_elem,
+ 'model_outputs': model_outputs_json_last_elem,
+ 'model_actions': model_actions_json_last_elem,
+ 'extracted_content': extracted_content_json_last_elem,
+ }
+
+ print('--- MODEL STEP SUMMARY ---')
+ print(f'URL: {urls_json_last_elem}')
+
+ # Send data to the API
+ result = send_agent_history_step(data=model_step_summary)
+ print(f'Recording API response: {result}')
async def run_agent():
- """Run the Browser-Use agent with the recording hook"""
- agent = Agent(
- task="Compare the price of gpt-4o and DeepSeek-V3",
- llm=ChatOpenAI(model="gpt-4.1-mini"),
- )
-
- try:
- print("Starting Browser-Use agent with recording hook")
- await agent.run(
- on_step_start=record_activity,
- max_steps=30
- )
- except Exception as e:
- print(f"Error running agent: {e}")
-
-
-if __name__ == "__main__":
- # Check if API is running
- try:
- requests.get("http://127.0.0.1:9000")
- print("Recording API is available")
- except:
- print("Warning: Recording API may not be running. Start api.py first.")
-
- # Run the agent
- asyncio.run(run_agent())
+ """Run the Browser-Use agent with the recording hook"""
+ agent = Agent(
+ task='Compare the price of gpt-4o and DeepSeek-V3',
+ llm=ChatOpenAI(model='gpt-5-mini'),
+ )
+
+ try:
+ print('Starting Browser-Use agent with recording hook')
+ await agent.run(on_step_start=record_activity, max_steps=30)
+ except Exception as e:
+ print(f'Error running agent: {e}')
+
+
+if __name__ == '__main__':
+ # Check if API is running
+ try:
+ requests.get('http://127.0.0.1:9000')
+ print('Recording API is available')
+ except Exception as e:
+ print('Warning: Recording API may not be running. Start api.py first.')
+ print(f'Error: {e}')
+
+ # Run the agent
+ asyncio.run(run_agent())
```
-Contribution by Carlos A. Planchón.
+Contribution by Carlos A. Planchón. Updated by Marian Schneider.
### Working with the Recorded Data