Skip to content

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

Clean up hooks

Magnus Müller1c269fffe710
diff --git a/docs/customize/hooks.mdx b/docs/customize/hooks.mdx
index 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 system
screenshot_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 code
if '/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