The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
fix(openrouter): support `default_headers` for custom HTTP header injection (#36582)
Hamza Kyamanywacf08ef0a2905
diff --git a/libs/partners/openrouter/langchain_openrouter/chat_models.py b/libs/partners/openrouter/langchain_openrouter/chat_models.pyindex 3fe32a2812..293c2d0a4c 100644--- a/libs/partners/openrouter/langchain_openrouter/chat_models.py+++ b/libs/partners/openrouter/langchain_openrouter/chat_models.py@@ -140,6 +140,7 @@ class ChatOpenRouter(BaseChatModel):| `app_categories` | `list[str] | None` | Marketplace attribution categories. || `session_id` | `str | None` | Group related requests for observability. || `trace` | `dict[str, Any] | None` | Trace metadata for broadcasts. |+ | `default_headers` | `Mapping[str, str] | None` | Extra request headers. || `max_retries` | `int` | Max retries (default `2`). Set to `0` to disable. |??? info "Instantiate"@@ -313,6 +314,28 @@ class ChatOpenRouter(BaseChatModel):plugins: list[dict[str, Any]] | None = None"""Plugins configuration for OpenRouter."""+ default_headers: Mapping[str, str] | None = Field(default=None, exclude=True)+ """Additional HTTP headers to include on every request to OpenRouter.++ Headers set here become the underlying httpx client's default headers, so+ they are sent on every request to OpenRouter. Useful for upstream provider+ features that require custom headers — for example, xAI's `x-grok-conv-id`+ for sticky-routing prompt cache hits, region routing, A/B test bucketing+ headers, or provider-specific authentication. Whether a given header is+ forwarded to the upstream provider (versus consumed by OpenRouter itself)+ is determined by OpenRouter; consult its docs for which headers propagate.++ Because these headers may contain credentials, they are excluded from+ LangChain serialization.++ Example: `{"x-grok-conv-id": "session-abc123"}`++ Headers set via this field are merged with the OpenRouter app-attribution+ headers (`HTTP-Referer`, `X-Title`, `X-OpenRouter-Categories`); on a+ collision the value from `default_headers` takes precedence, matched+ case-insensitively (HTTP header names are case-insensitive).+ """+session_id: str | None = Field(default_factory=from_env("OPENROUTER_SESSION_ID", default=None),)@@ -321,7 +344,7 @@ class ChatOpenRouter(BaseChatModel):Useful any time multiple requests should share an observabilitygrouping (e.g. a conversation, an agent workflow, a batch job, or a CIrun). Equivalent to setting the `x-session-id` HTTP header on the- underlying request. OpenRouter rejects values longer than 128+ underlying request. OpenRouter rejects values longer than 256characters.Falls back to the `OPENROUTER_SESSION_ID` environment variable when@@ -405,6 +428,19 @@ class ChatOpenRouter(BaseChatModel):extra_headers["X-Title"] = self.app_titleif self.app_categories:extra_headers["X-OpenRouter-Categories"] = ",".join(self.app_categories)+ # User-supplied headers take precedence over the built-in+ # app-attribution headers on collision. HTTP header names are+ # case-insensitive, so drop any built-in whose name case-insensitively+ # matches a user header before merging; a plain dict update would keep+ # both spellings and httpx would then send a doubled header.+ if self.default_headers:+ user_header_names = {name.casefold() for name in self.default_headers}+ extra_headers = {+ name: value+ for name, value in extra_headers.items()+ if name.casefold() not in user_header_names+ }+ extra_headers.update(self.default_headers)if extra_headers:import httpx # noqa: PLC0415diff --git a/libs/partners/openrouter/tests/unit_tests/test_chat_models.py b/libs/partners/openrouter/tests/unit_tests/test_chat_models.pyindex 218a7b2e5e..3d4c6aeaa8 100644--- a/libs/partners/openrouter/tests/unit_tests/test_chat_models.py+++ b/libs/partners/openrouter/tests/unit_tests/test_chat_models.py@@ -508,6 +508,179 @@ class TestChatOpenRouterInstantiation:assert "client" not in call_kwargsassert "async_client" not in call_kwargs+ def test_default_headers_passed_to_client(self) -> None:+ """Test that `default_headers` are forwarded to the httpx clients.++ Before this field existed, setting `default_headers` had no effect on+ the HTTP layer: `build_extra` diverted the unrecognized parameter into+ `model_kwargs` (with a "not default parameter" warning), so the header+ never reached the outbound request.+ """+ with patch("openrouter.OpenRouter") as mock_cls:+ mock_cls.return_value = MagicMock()+ ChatOpenRouter(+ model=MODEL_NAME,+ api_key=SecretStr("test-key"),+ default_headers={"x-grok-conv-id": "session-abc-123"},+ )+ call_kwargs = mock_cls.call_args[1]+ # Custom httpx clients are created and the header is set on both.+ assert "client" in call_kwargs+ assert "async_client" in call_kwargs+ sync_headers = call_kwargs["client"].headers+ assert sync_headers["x-grok-conv-id"] == "session-abc-123"+ async_headers = call_kwargs["async_client"].headers+ assert async_headers["x-grok-conv-id"] == "session-abc-123"++ def test_default_headers_coexist_with_app_attribution(self) -> None:+ """Test that `default_headers` merges with built-in attribution headers."""+ with patch("openrouter.OpenRouter") as mock_cls:+ mock_cls.return_value = MagicMock()+ ChatOpenRouter(+ model=MODEL_NAME,+ api_key=SecretStr("test-key"),+ app_url="https://myapp.com",+ app_title="My App",+ default_headers={+ "x-grok-conv-id": "session-xyz",+ "x-custom-trace-id": "trace-001",+ },+ )+ call_kwargs = mock_cls.call_args[1]+ sync_headers = call_kwargs["client"].headers+ # Built-in attribution preserved+ assert sync_headers["HTTP-Referer"] == "https://myapp.com"+ assert sync_headers["X-Title"] == "My App"+ # User-supplied headers also present+ assert sync_headers["x-grok-conv-id"] == "session-xyz"+ assert sync_headers["x-custom-trace-id"] == "trace-001"++ def test_default_headers_override_app_attribution(self) -> None:+ """Test that `default_headers` takes precedence over colliding built-in keys."""+ with patch("openrouter.OpenRouter") as mock_cls:+ mock_cls.return_value = MagicMock()+ ChatOpenRouter(+ model=MODEL_NAME,+ api_key=SecretStr("test-key"),+ app_title="Default Title",+ default_headers={"X-Title": "Override Title"},+ )+ call_kwargs = mock_cls.call_args[1]+ sync_headers = call_kwargs["client"].headers+ # default_headers wins over the built-in app_title-derived value+ assert sync_headers["X-Title"] == "Override Title"++ def test_default_headers_none_no_custom_headers(self) -> None:+ """Test that `default_headers=None` doesn't interfere with default behavior."""+ with patch("openrouter.OpenRouter") as mock_cls:+ mock_cls.return_value = MagicMock()+ ChatOpenRouter(+ model=MODEL_NAME,+ api_key=SecretStr("test-key"),+ default_headers=None,+ )+ call_kwargs = mock_cls.call_args[1]+ # Default app-attribution headers still present+ sync_headers = call_kwargs["client"].headers+ assert sync_headers["HTTP-Referer"] == "https://docs.langchain.com"+ assert sync_headers["X-Title"] == "LangChain"+ # No spurious extra headers+ assert "x-grok-conv-id" not in sync_headers++ def test_default_headers_sole_source_creates_client(self) -> None:+ """`default_headers` alone (no app attribution) still creates httpx clients.++ Guards against a regression where the `if extra_headers:` check runs+ before `default_headers` is merged in — the header would then be+ dropped and no custom client created.+ """+ with patch("openrouter.OpenRouter") as mock_cls:+ mock_cls.return_value = MagicMock()+ ChatOpenRouter(+ model=MODEL_NAME,+ api_key=SecretStr("test-key"),+ app_url=None,+ app_title=None,+ app_categories=None,+ default_headers={"x-grok-conv-id": "session-solo"},+ )+ call_kwargs = mock_cls.call_args[1]+ assert "client" in call_kwargs+ assert "async_client" in call_kwargs+ assert call_kwargs["client"].headers["x-grok-conv-id"] == "session-solo"+ assert (+ call_kwargs["async_client"].headers["x-grok-conv-id"] == "session-solo"+ )++ def test_default_headers_override_app_categories(self) -> None:+ """`default_headers` can override the built-in `X-OpenRouter-Categories`."""+ with patch("openrouter.OpenRouter") as mock_cls:+ mock_cls.return_value = MagicMock()+ ChatOpenRouter(+ model=MODEL_NAME,+ api_key=SecretStr("test-key"),+ app_categories=["programming", "translation"],+ default_headers={"X-OpenRouter-Categories": "custom-category"},+ )+ call_kwargs = mock_cls.call_args[1]+ sync_headers = call_kwargs["client"].headers+ assert sync_headers["X-OpenRouter-Categories"] == "custom-category"++ def test_default_headers_empty_dict_no_custom_client(self) -> None:+ """An empty `default_headers` dict behaves like `None` (no custom client)."""+ with patch("openrouter.OpenRouter") as mock_cls:+ mock_cls.return_value = MagicMock()+ ChatOpenRouter(+ model=MODEL_NAME,+ api_key=SecretStr("test-key"),+ app_url=None,+ app_title=None,+ app_categories=None,+ default_headers={},+ )+ call_kwargs = mock_cls.call_args[1]+ assert "client" not in call_kwargs+ assert "async_client" not in call_kwargs++ def test_default_headers_override_is_case_insensitive(self) -> None:+ """A case-variant user header overrides the built-in, not doubles it.++ HTTP header names are case-insensitive, so `default_headers` keyed with+ different casing than a built-in attribution header (`http-referer` vs+ `HTTP-Referer`) must replace it rather than send both values.+ """+ with patch("openrouter.OpenRouter") as mock_cls:+ mock_cls.return_value = MagicMock()+ ChatOpenRouter(+ model=MODEL_NAME,+ api_key=SecretStr("test-key"),+ app_url="https://builtin.example",+ default_headers={"http-referer": "https://override.example"},+ )+ sync_headers = mock_cls.call_args[1]["client"].headers+ # httpx headers are case-insensitive: the override value wins under+ # either spelling, with no comma-joined doubling.+ assert sync_headers["HTTP-Referer"] == "https://override.example"+ assert sync_headers["http-referer"] == "https://override.example"+ assert "," not in sync_headers["HTTP-Referer"]++ def test_default_headers_not_swept_into_model_kwargs(self) -> None:+ """`default_headers` is a first-class field, not extra `model_kwargs`.++ Guards the motivating regression: `build_extra` must recognize+ `default_headers`, leave it out of `model_kwargs`, and not emit the+ "not default parameter" warning that unrecognized kwargs trigger.+ """+ with warnings.catch_warnings(record=True) as caught:+ warnings.simplefilter("always")+ model = ChatOpenRouter(+ model=MODEL_NAME,+ api_key=SecretStr("test-key"),+ default_headers={"x-grok-conv-id": "session-abc-123"},+ )+ assert model.model_kwargs == {}+ assert not any("not default parameter" in str(w.message) for w in caught)+def test_reasoning_in_params(self) -> None:"""Test that `reasoning` is included in default params."""model = _make_model(reasoning={"effort": "high"})@@ -577,6 +750,33 @@ class TestSerialization:serialized = dumps(model)assert "super-secret-key" not in serialized+ def test_dumpd_excludes_default_headers(self) -> None:+ """Test that default_headers are excluded from serialized kwargs."""+ model = _make_model(+ default_headers={+ "Authorization": "Bearer provider-token",+ "x-grok-conv-id": "session-abc-123",+ }+ )++ serialized = dumpd(model)++ assert "default_headers" not in serialized["kwargs"]++ def test_dumps_does_not_leak_default_headers(self) -> None:+ """Test that dumps output does not contain default header values."""+ model = _make_model(+ default_headers={+ "Authorization": "Bearer provider-token",+ "x-grok-conv-id": "session-abc-123",+ }+ )++ serialized = dumps(model)++ assert "provider-token" not in serialized+ assert "session-abc-123" not in serialized+# ===========================================================================# Mocked generate / stream tests