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
Add OrcaRouter as a named LLM provider
XiaoHuo888d8580caf01e0
diff --git a/.env.example b/.env.exampleindex 1ec212851..04621556a 100644--- a/.env.example+++ b/.env.example@@ -39,6 +39,7 @@ BROWSER_USE_API_KEY=your_bu_api_key_here# DEEPSEEK_API_KEY=# GROK_API_KEY=# NOVITA_API_KEY=+# ORCAROUTER_API_KEY=# AWS Bedrock Configuration (for AWS Bedrock models)# Requires: pip install browser-use[aws]diff --git a/browser_use/__init__.py b/browser_use/__init__.pyindex edd5e9f7b..6fa2a790d 100644--- a/browser_use/__init__.py+++ b/browser_use/__init__.py@@ -67,6 +67,7 @@ if TYPE_CHECKING:from browser_use.llm.ollama.chat import ChatOllamafrom browser_use.llm.openai.chat import ChatOpenAIfrom browser_use.llm.openrouter.chat import ChatOpenRouter+ from browser_use.llm.orcarouter.chat import ChatOrcaRouterfrom browser_use.llm.vercel.chat import ChatVercelfrom browser_use.sandbox import sandboxfrom browser_use.tools.service import Controller, Tools@@ -105,6 +106,7 @@ _LAZY_IMPORTS = {'ChatOCIRaw': ('browser_use.llm.oci_raw.chat', 'ChatOCIRaw'),'ChatOllama': ('browser_use.llm.ollama.chat', 'ChatOllama'),'ChatOpenRouter': ('browser_use.llm.openrouter.chat', 'ChatOpenRouter'),+ 'ChatOrcaRouter': ('browser_use.llm.orcarouter.chat', 'ChatOrcaRouter'),'ChatVercel': ('browser_use.llm.vercel.chat', 'ChatVercel'),# LLM models module'models': ('browser_use.llm.models', None),@@ -162,6 +164,7 @@ __all__ = ['ChatOCIRaw','ChatOllama','ChatOpenRouter',+ 'ChatOrcaRouter','ChatVercel','Tools','Controller',diff --git a/browser_use/llm/__init__.py b/browser_use/llm/__init__.pyindex d6d8464c9..5bba93b1b 100644--- a/browser_use/llm/__init__.py+++ b/browser_use/llm/__init__.py@@ -40,6 +40,7 @@ if TYPE_CHECKING:from browser_use.llm.ollama.chat import ChatOllamafrom browser_use.llm.openai.chat import ChatOpenAIfrom browser_use.llm.openrouter.chat import ChatOpenRouter+ from browser_use.llm.orcarouter.chat import ChatOrcaRouterfrom browser_use.llm.vercel.chat import ChatVercel# Type stubs for model instances - enables IDE autocomplete@@ -93,6 +94,7 @@ _LAZY_IMPORTS = {'ChatOllama': ('browser_use.llm.ollama.chat', 'ChatOllama'),'ChatOpenAI': ('browser_use.llm.openai.chat', 'ChatOpenAI'),'ChatOpenRouter': ('browser_use.llm.openrouter.chat', 'ChatOpenRouter'),+ 'ChatOrcaRouter': ('browser_use.llm.orcarouter.chat', 'ChatOrcaRouter'),'ChatVercel': ('browser_use.llm.vercel.chat', 'ChatVercel'),}@@ -156,6 +158,7 @@ __all__ = ['ChatOCIRaw','ChatOllama','ChatOpenRouter',+ 'ChatOrcaRouter','ChatVercel','ChatCerebras',]diff --git a/browser_use/llm/orcarouter/chat.py b/browser_use/llm/orcarouter/chat.pynew file mode 100644index 000000000..c3d91c9d6--- /dev/null+++ b/browser_use/llm/orcarouter/chat.py@@ -0,0 +1,205 @@+from collections.abc import Mapping+from dataclasses import dataclass+from typing import Any, TypeVar, overload++import httpx+from openai import APIConnectionError, APIStatusError, AsyncOpenAI, RateLimitError+from openai.types.chat.chat_completion import ChatCompletion+from openai.types.shared_params.response_format_json_schema import (+ JSONSchema,+ ResponseFormatJSONSchema,+)+from pydantic import BaseModel++from browser_use.llm.base import BaseChatModel+from browser_use.llm.exceptions import ModelProviderError, ModelRateLimitError+from browser_use.llm.messages import BaseMessage+from browser_use.llm.orcarouter.serializer import OrcaRouterMessageSerializer+from browser_use.llm.schema import SchemaOptimizer+from browser_use.llm.views import ChatInvokeCompletion, ChatInvokeUsage++T = TypeVar('T', bound=BaseModel)+++@dataclass+class ChatOrcaRouter(BaseChatModel):+ """+ A wrapper around OrcaRouter's OpenAI-compatible chat API, which routes to 190+ LLM models+ through a single unified gateway.++ This class implements the BaseChatModel protocol for OrcaRouter's API.+ """++ # Model configuration+ model: str++ # Model params+ temperature: float | None = None+ top_p: float | None = None+ seed: int | None = None++ # Client initialization parameters+ api_key: str | None = None+ base_url: str | httpx.URL = 'https://api.orcarouter.ai/v1'+ timeout: float | httpx.Timeout | None = None+ max_retries: int = 10+ default_headers: Mapping[str, str] | None = None+ default_query: Mapping[str, object] | None = None+ http_client: httpx.AsyncClient | None = None+ _strict_response_validation: bool = False+ extra_body: dict[str, Any] | None = None++ # Static+ @property+ def provider(self) -> str:+ return 'orcarouter'++ def _get_client_params(self) -> dict[str, Any]:+ """Prepare client parameters dictionary."""+ # Define base client params+ base_params = {+ 'api_key': self.api_key,+ 'base_url': self.base_url,+ 'timeout': self.timeout,+ 'max_retries': self.max_retries,+ 'default_headers': self.default_headers,+ 'default_query': self.default_query,+ '_strict_response_validation': self._strict_response_validation,+ 'top_p': self.top_p,+ 'seed': self.seed,+ }++ # Create client_params dict with non-None values+ client_params = {k: v for k, v in base_params.items() if v is not None}++ # Add http_client if provided+ if self.http_client is not None:+ client_params['http_client'] = self.http_client++ return client_params++ def get_client(self) -> AsyncOpenAI:+ """+ Returns an AsyncOpenAI client configured for OrcaRouter.++ Returns:+ AsyncOpenAI: An instance of the AsyncOpenAI client with OrcaRouter base URL.+ """+ if not hasattr(self, '_client'):+ client_params = self._get_client_params()+ self._client = AsyncOpenAI(**client_params)+ return self._client++ @property+ def name(self) -> str:+ return str(self.model)++ def _get_usage(self, response: ChatCompletion) -> ChatInvokeUsage | None:+ """Extract usage information from the OrcaRouter response."""+ if response.usage is None:+ return None++ prompt_details = getattr(response.usage, 'prompt_tokens_details', None)+ cached_tokens = prompt_details.cached_tokens if prompt_details else None++ return ChatInvokeUsage(+ prompt_tokens=response.usage.prompt_tokens,+ prompt_cached_tokens=cached_tokens,+ prompt_cache_creation_tokens=None,+ prompt_image_tokens=None,+ # Completion+ completion_tokens=response.usage.completion_tokens,+ total_tokens=response.usage.total_tokens,+ )++ @overload+ async def ainvoke(+ self, messages: list[BaseMessage], output_format: None = None, **kwargs: Any+ ) -> ChatInvokeCompletion[str]: ...++ @overload+ async def ainvoke(self, messages: list[BaseMessage], output_format: type[T], **kwargs: Any) -> ChatInvokeCompletion[T]: ...++ async def ainvoke(+ self, messages: list[BaseMessage], output_format: type[T] | None = None, **kwargs: Any+ ) -> ChatInvokeCompletion[T] | ChatInvokeCompletion[str]:+ """+ Invoke the model with the given messages through OrcaRouter.++ Args:+ messages: List of chat messages+ output_format: Optional Pydantic model class for structured output++ Returns:+ Either a string response or an instance of output_format+ """+ orcarouter_messages = OrcaRouterMessageSerializer.serialize_messages(messages)++ try:+ if output_format is None:+ # Return string response+ response = await self.get_client().chat.completions.create(+ model=self.model,+ messages=orcarouter_messages,+ temperature=self.temperature,+ top_p=self.top_p,+ seed=self.seed,+ **(self.extra_body or {}),+ )++ usage = self._get_usage(response)+ return ChatInvokeCompletion(+ completion=response.choices[0].message.content or '',+ usage=usage,+ )++ else:+ # Create a JSON schema for structured output+ schema = SchemaOptimizer.create_optimized_json_schema(output_format)++ response_format_schema: JSONSchema = {+ 'name': 'agent_output',+ 'strict': True,+ 'schema': schema,+ }++ # Return structured response+ response = await self.get_client().chat.completions.create(+ model=self.model,+ messages=orcarouter_messages,+ temperature=self.temperature,+ top_p=self.top_p,+ seed=self.seed,+ response_format=ResponseFormatJSONSchema(+ json_schema=response_format_schema,+ type='json_schema',+ ),+ **(self.extra_body or {}),+ )++ if response.choices[0].message.content is None:+ raise ModelProviderError(+ message='Failed to parse structured output from model response',+ status_code=500,+ model=self.name,+ )+ usage = self._get_usage(response)++ parsed = output_format.model_validate_json(response.choices[0].message.content)++ return ChatInvokeCompletion(+ completion=parsed,+ usage=usage,+ )++ except RateLimitError as e:+ raise ModelRateLimitError(message=e.message, model=self.name) from e++ except APIConnectionError as e:+ raise ModelProviderError(message=str(e), model=self.name) from e++ except APIStatusError as e:+ raise ModelProviderError(message=e.message, status_code=e.status_code, model=self.name) from e++ except Exception as e:+ raise ModelProviderError(message=str(e), model=self.name) from ediff --git a/browser_use/llm/orcarouter/serializer.py b/browser_use/llm/orcarouter/serializer.pynew file mode 100644index 000000000..8659e8037--- /dev/null+++ b/browser_use/llm/orcarouter/serializer.py@@ -0,0 +1,26 @@+from openai.types.chat import ChatCompletionMessageParam++from browser_use.llm.messages import BaseMessage+from browser_use.llm.openai.serializer import OpenAIMessageSerializer+++class OrcaRouterMessageSerializer:+ """+ Serializer for converting between custom message types and OrcaRouter message formats.++ OrcaRouter exposes an OpenAI-compatible API, so we can reuse the OpenAI serializer.+ """++ @staticmethod+ def serialize_messages(messages: list[BaseMessage]) -> list[ChatCompletionMessageParam]:+ """+ Serialize a list of browser_use messages to OrcaRouter-compatible messages.++ Args:+ messages: List of browser_use messages++ Returns:+ List of OrcaRouter-compatible messages (identical to OpenAI format)+ """+ # OrcaRouter uses the same message format as OpenAI+ return OpenAIMessageSerializer.serialize_messages(messages)diff --git a/browser_use/tokens/service.py b/browser_use/tokens/service.pyindex 37d9181a6..6395a3837 100644--- a/browser_use/tokens/service.py+++ b/browser_use/tokens/service.py@@ -405,6 +405,9 @@ class TokenCost:if llm.provider == 'openrouter' or base_url == 'https://openrouter.ai/api/v1':if not is_openrouter_pricing_model(model):return f'openrouter/{model}'+ # OrcaRouter is a gateway with its own pricing; never attribute upstream prices to it.+ if llm.provider == 'orcarouter' or base_url == 'https://api.orcarouter.ai/v1':+ return f'orcarouter/{model}'return modeldiff --git a/examples/models/orcarouter.py b/examples/models/orcarouter.pynew file mode 100644index 000000000..6314b2a9e--- /dev/null+++ b/examples/models/orcarouter.py@@ -0,0 +1,33 @@+"""+Simple try of the agent with OrcaRouter.++@dev You need to add ORCAROUTER_API_KEY to your environment variables.+"""++import asyncio+import os++from dotenv import load_dotenv++from browser_use import Agent, ChatOrcaRouter++load_dotenv()++# OrcaRouter is an OpenAI-compatible model gateway routing to 190+ models via one endpoint.+llm = ChatOrcaRouter(+ model='orcarouter/auto',+ base_url='https://api.orcarouter.ai/v1',+ api_key=os.getenv('ORCAROUTER_API_KEY'),+)+agent = Agent(+ task='Find the number of stars of the browser-use repo',+ llm=llm,+ use_vision=False,+)+++async def main():+ await agent.run(max_steps=10)+++asyncio.run(main())diff --git a/tests/ci/test_orcarouter.py b/tests/ci/test_orcarouter.pynew file mode 100644index 000000000..1dcaa9e92--- /dev/null+++ b/tests/ci/test_orcarouter.py@@ -0,0 +1,64 @@+import pytest++from browser_use.llm.messages import ContentPartTextParam, SystemMessage, UserMessage+from browser_use.llm.orcarouter.chat import ChatOrcaRouter+from browser_use.llm.orcarouter.serializer import OrcaRouterMessageSerializer+from browser_use.llm.views import ChatInvokeUsage+from browser_use.tokens.service import TokenCost+++def test_orcarouter_serializer_uses_openai_format() -> None:+ """OrcaRouter speaks the OpenAI wire format, so the serializer must match OpenAI's."""+ messages = [+ SystemMessage(content=[ContentPartTextParam(text='You are a helpful assistant.', type='text')]),+ UserMessage(content='What is the capital of France? Answer in one word.'),+ ]++ serialized = OrcaRouterMessageSerializer.serialize_messages(messages)++ assert serialized == [+ {'role': 'system', 'content': [{'type': 'text', 'text': 'You are a helpful assistant.'}]},+ {'role': 'user', 'content': 'What is the capital of France? Answer in one word.'},+ ]+++def test_orcarouter_chat_defaults() -> None:+ """ChatOrcaRouter must expose the OrcaRouter provider and default gateway base URL."""+ chat = ChatOrcaRouter(model='orcarouter/auto', api_key='test-key')++ assert chat.provider == 'orcarouter'+ assert str(chat.base_url) == 'https://api.orcarouter.ai/v1'+ assert chat.name == 'orcarouter/auto'+++async def test_registered_orcarouter_llm_never_matches_upstream_pricing(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """OrcaRouter is a gateway; upstream model pricing must not be attributed to it."""+ seen_model_names = []++ async def fake_openrouter_pricing(model_name: str):+ seen_model_names.append(model_name)+ return None++ monkeypatch.setattr('browser_use.tokens.service.get_openrouter_model_pricing', fake_openrouter_pricing)++ token_cost = TokenCost(include_cost=True)+ token_cost._initialized = True+ token_cost._pricing_data = {}+ token_cost.register_llm(ChatOrcaRouter(model='openai/gpt-4o-mini', api_key='test-key'))++ cost = await token_cost.calculate_cost(+ 'openai/gpt-4o-mini',+ ChatInvokeUsage(+ prompt_tokens=10,+ prompt_cached_tokens=None,+ prompt_cache_creation_tokens=None,+ prompt_image_tokens=None,+ completion_tokens=5,+ total_tokens=15,+ ),+ )++ assert seen_model_names == ['orcarouter/openai/gpt-4o-mini']+ assert cost is None