Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
docs: update hooks complex example to work with latest release
Marian Schneiderd827aea29b67
diff --git a/docs/customize/hooks.mdx b/docs/customize/hooks.mdxindex 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 jsonimport base64+import jsonfrom pathlib import Path-from fastapi import FastAPI, Requestimport prettyprinterimport uvicorn+from fastapi import FastAPI, Requestprettyprinter.install_extras()+# Utility function to save screenshotsdef 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 appapp = 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 requestsfrom dotenv import load_dotenvfrom 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