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
Clean up hooks
Magnus Müller1c269fffe710
diff --git a/docs/customize/hooks.mdx b/docs/customize/hooks.mdxindex 62ad87d2a..345e072e0 100644--- a/docs/customize/hooks.mdx+++ b/docs/customize/hooks.mdx@@ -2,7 +2,6 @@title: "Lifecycle Hooks"description: "Customize agent behavior with lifecycle hooks"icon: "Wrench"-author: "Carlos A. Planchón"mode: "wide"---@@ -59,6 +58,7 @@ async def my_step_hook(agent: Agent):# Example: Take a screenshot using the event systemscreenshot_event = agent.browser_session.event_bus.dispatch(ScreenshotEvent(full_page=False))await screenshot_event+ result = await screenshot_event.event_result(raise_if_any=True, raise_if_none=True)# Example: pause agent execution and resume it based on some custom codeif '/finished' in current_url:@@ -112,276 +112,8 @@ When working with agent hooks, you have access to the entire `Agent` instance. H## Tips for Using Hooks-- **Avoid blocking operations**: Since hooks run in the same execution thread as the agent, try to keep them efficient or use asynchronous patterns.-- **Handle exceptions**: Make sure your hook functions handle exceptions gracefully to prevent interrupting the agent's main flow.-- **Use custom actions instead**: hooks are fairly advanced, most things can be implemented with [custom action functions](/customize/custom-functions) instead+- **Avoid blocking operations**: Since hooks run in the same execution thread as the agent, keep them efficient and avoid blocking operations.+- **Use custom tools instead**: hooks are fairly advanced, most things can be implemented with [custom tools](/customize/tools/basics) instead+- **Increase step_timeout**: If your hook is doing something that takes a long time, you can increase the `step_timeout` parameter in the `Agent(...)` constructor.-----## Complex Example: Agent Activity Recording System--This comprehensive example demonstrates a complete implementation for recording and saving Browser-Use agent activity, consisting of both server and client components.--### Setup Instructions--To use this example, you'll need to:--1. Set up the required dependencies:-- ```bash- uv pip install fastapi uvicorn prettyprinter pyobjtojson dotenv browser-use- ```--2. Create two separate Python files:-- - `api.py` - The FastAPI server component- - `client.py` - The Browser-Use agent with recording hook--3. Run both components:- - Start the API server first: `python api.py`- - Then run the client: `python client.py`--### Server Component (api.py)--The server component handles receiving and storing the agent's activity data:--```python-#!/usr/bin/env python3--#-# FastAPI API to record and save Browser-Use activity data.-# Save this code to api.py and run with `python api.py`-#--import base64-import json-from pathlib import Path--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.-- :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')-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)-```--### Client Component (client.py)--The client component runs the Browser-Use agent with a recording hook:--```python-#!/usr/bin/env python3--#-# Client to record and save Browser-Use activity.-# Save this code to client.py and run with `python client.py`-#--import asyncio--import requests-from dotenv import load_dotenv-from pyobjtojson import obj_to_json--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, timeout=10)- 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- 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-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', timeout=5)- 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. Updated by Marian Schneider.--### Working with the Recorded Data--After running the agent, you'll find the recorded data in the `recordings` directory. Here's how you can use this data:--1. **View recorded sessions**: Each JSON file contains a snapshot of agent activity for one step-2. **Extract screenshots**: You can modify the API to save screenshots separately-3. **Analyze agent behavior**: Use the recorded data to study how the agent navigates websites--### Extending the Example--You can extend this recording system in several ways:--1. **Save screenshots separately**: Uncomment the screenshot saving code in the API-2. **Add a web dashboard**: Create a simple web interface to view recorded sessions-3. **Add session IDs**: Modify the API to group steps by agent session-4. **Add filtering**: Implement filters to record only specific types of actions