Skip to main content
Browser-Use provides lifecycle hooks that allow you to execute custom code at specific points during the agent’s execution. Hook functions can be used to read and modify agent state while running, implement custom logic, change configuration, integrate the Agent with external applications.

​
Available Hooks

Currently, Browser-Use provides the following hooks:
HookDescriptionWhen it is called
on_step_startExecuted at the beginning of each agent stepBefore the agent processes the current state and decides on the next action
on_step_endExecuted at the end of each agent stepAfter the agent has executed all the actions for the current step, before it starts the next step
await agent.run(on_step_start=..., on_step_end=...)
Each hook should be an async callable function that accepts the agent instance as its only parameter.

​
Basic Example

import asyncio
from pathlib import Path

from browser_use import Agent, ChatOpenAI
from browser_use.browser.events import ScreenshotEvent


async def my_step_hook(agent: Agent):
	# inside a hook you can access all the state and methods under the Agent object:
	#   agent.settings, agent.state, agent.task
	#   agent.tools, agent.llm, agent.browser_session
	#   agent.pause(), agent.resume(), agent.add_new_task(...), etc.

	# You also have direct access to the browser state
	state = await agent.browser_session.get_browser_state_summary()

	current_url = state.url
	visit_log = agent.history.urls()
	previous_url = visit_log[-2] if len(visit_log) >= 2 else None
	print(f'Agent was last on URL: {previous_url} and is now on {current_url}')
	cdp_session = await agent.browser_session.get_or_create_cdp_session()

	# Example: Get page HTML content
	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
	)
	page_html = html_result['outerHTML']

	# 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:
		agent.pause()
		Path('result.txt').write_text(page_html)
		input('Saved "finished" page content to result.txt, press [Enter] to resume...')
		agent.resume()


async def main():
	agent = Agent(
		task='Search for the latest news about AI',
		llm=ChatOpenAI(model='gpt-5-mini'),
	)

	await agent.run(
		on_step_start=my_step_hook,
		# on_step_end=...
		max_steps=10,
	)


if __name__ == '__main__':
	asyncio.run(main())

​
Data Available in Hooks

When working with agent hooks, you have access to the entire Agent instance. Here are some useful data points you can access:
  • agent.task provides the main task, agent.add_new_task(...) allows you to queue up a new one
  • agent.tools gives access to the Tools() object and Registry() containing the available actions
    • agent.tools.registry.execute_action('click', {'index': 123}, browser_session=agent.browser_session)
  • agent.sensitive_data contains the sensitive data dict, which can be updated in-place to add/remove/modify items
  • agent.settings contains all the configuration options passed to the Agent(...) at init time
  • agent.llm provides direct access to the main LLM object (e.g. ChatOpenAI)
  • agent.state provides access to internal state, including agent thoughts, outputs, actions, and more
  • agent.history gives access to historical data from the agent’s execution:
    • agent.history.model_thoughts(): Reasoning from Browser Use’s model.
    • agent.history.model_outputs(): Raw outputs from the Browser Use’s model.
    • agent.history.model_actions(): Actions taken by the agent
    • agent.history.extracted_content(): Content extracted from web pages
    • agent.history.urls(): URLs visited by the agent
  • agent.browser_session provides direct access to the BrowserSession and CDP interface
    • agent.browser_session.agent_focus_target_id: Get the current target ID the agent is focused on
    • agent.browser_session.get_or_create_cdp_session(): Get the current CDP session for browser interaction
    • agent.browser_session.get_tabs(): Get all tabs currently open
    • agent.browser_session.get_current_page_url(): Get the URL of the current active tab
    • agent.browser_session.get_current_page_title(): Get the title of the current active tab

​
Tips for Using Hooks

  • 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 use cases can be implemented with custom tools 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.