Skip to content

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

feat: add custom headres support + add example

reformedotde659f9768de
diff --git a/browser_use/browser/session.py b/browser_use/browser/session.py
index 7977cf517..8e7c5a6d0 100644
--- a/browser_use/browser/session.py
+++ b/browser_use/browser/session.py
@@ -1297,6 +1297,29 @@ class BrowserSession(BaseModel):
return session
+ async def set_extra_headers(self, headers: dict[str, str], target_id: TargetID | None = None) -> None:
+ """Set extra HTTP headers using CDP Network.setExtraHTTPHeaders.
+
+ These headers will be sent with every HTTP request made by the target.
+ Network domain must be enabled first (done automatically for page targets
+ in SessionManager._enable_page_monitoring).
+
+ Args:
+ headers: Dictionary of header name -> value pairs to inject into every request.
+ target_id: Target to set headers on. Defaults to the current agent focus target.
+ """
+ if target_id is None:
+ if not self.agent_focus_target_id:
+ return
+ target_id = self.agent_focus_target_id
+
+ cdp_session = await self.get_or_create_cdp_session(target_id, focus=False)
+ # Ensure Network domain is enabled (idempotent - safe to call multiple times)
+ await cdp_session.cdp_client.send.Network.enable(session_id=cdp_session.session_id)
+ await cdp_session.cdp_client.send.Network.setExtraHTTPHeaders(
+ params={'headers': cast(Any, headers)}, session_id=cdp_session.session_id
+ )
+
# endregion - ========== CDP-based ... ==========
# region - ========== Helper Methods ==========
@@ -2895,15 +2918,6 @@ class BrowserSession(BaseModel):
cdp_session = await self.get_or_create_cdp_session()
await cdp_session.cdp_client.send.Storage.clearCookies(session_id=cdp_session.session_id)
- async def _cdp_set_extra_headers(self, headers: dict[str, str]) -> None:
- """Set extra HTTP headers using CDP Network.setExtraHTTPHeaders."""
- if not self.agent_focus_target_id:
- return
-
- cdp_session = await self.get_or_create_cdp_session()
- # await cdp_session.cdp_client.send.Network.setExtraHTTPHeaders(params={'headers': headers}, session_id=cdp_session.session_id)
- raise NotImplementedError('Not implemented yet')
-
async def _cdp_grant_permissions(self, permissions: list[str], origin: str | None = None) -> None:
"""Grant permissions using CDP Browser.grantPermissions."""
params = {'permissions': permissions}
diff --git a/examples/browser/custom_headers.py b/examples/browser/custom_headers.py
new file mode 100644
index 000000000..ec7dc9d19
--- /dev/null
+++ b/examples/browser/custom_headers.py
@@ -0,0 +1,90 @@
+"""
+Custom HTTP Headers via CDP Events.
+
+Registers a CDP Target.attachedToTarget listener that injects custom
+headers on every newly created target (tab / iframe). The listener only
+fires for targets created after registration, so we also apply the headers
+to the already-existing focused target with browser.set_extra_headers().
+
+Note: Network.setExtraHTTPHeaders is a full replacement (not additive).
+
+Verified by navigating to https://httpbin.org/headers.
+"""
+
+import asyncio
+import os
+import sys
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from browser_use import Agent, Browser, ChatBrowserUse
+
+CUSTOM_HEADERS = {
+ 'X-Custom-Auth': 'Bearer my-secret-token',
+ 'X-Request-Source': 'browser-use-agent',
+ 'X-Trace-Id': 'example-trace-12345',
+}
+
+
+async def main():
+ browser = Browser(headless=False)
+ await browser.start()
+
+ # 1. Register a CDP listener so every NEW target gets custom headers.
+ # Same pattern as _setup_proxy_auth() which uses Target.attachedToTarget
+ # to call Fetch.enable on freshly-attached sessions.
+ def on_target_attached(event, session_id=None):
+ sid = event.get('sessionId') or event.get('session_id') or session_id
+ if not sid:
+ return
+
+ async def _apply():
+ try:
+ assert browser._cdp_client_root is not None
+ await browser._cdp_client_root.send.Network.enable(session_id=sid)
+ await browser._cdp_client_root.send.Network.setExtraHTTPHeaders(
+ params={'headers': CUSTOM_HEADERS}, # type: ignore[arg-type]
+ session_id=sid,
+ )
+ except Exception:
+ pass # short-lived targets (workers, temp iframes) may detach
+
+ asyncio.create_task(_apply())
+
+ browser.cdp_client.register.Target.attachedToTarget(on_target_attached)
+
+ # 2. The listener above only fires for future targets, so apply headers
+ # to the already-existing focused target too.
+ await browser.set_extra_headers(CUSTOM_HEADERS)
+
+ # You can also call set_extra_headers() at any point to change the
+ # headers on a specific target without a listener:
+ #
+ # await browser.set_extra_headers({'Authorization': 'Bearer xyz'})
+ # await browser.set_extra_headers({'Authorization': 'Bearer xyz'}, target_id=some_target_id)
+ #
+ # Keep in mind that setExtraHTTPHeaders is a full replacement – each
+ # call overwrites all previously set extra headers on that target.
+
+ # 3. Run the agent – httpbin.org/headers echoes all received HTTP headers
+ agent = Agent(
+ task=(
+ 'Go to https://httpbin.org/headers and extract the full JSON response shown on the page. '
+ 'Look for the custom headers X-Custom-Auth, X-Request-Source, and X-Trace-Id in the output.'
+ ),
+ llm=ChatBrowserUse(),
+ browser=browser,
+ )
+
+ result = await agent.run()
+ print(result.final_result())
+
+ await browser.kill()
+
+
+if __name__ == '__main__':
+ asyncio.run(main())