feat: accept a pre-configured client on the labs OpenAI model

Close #4180

Co-authored-by: George Weale <gweale@google.com>
PiperOrigin-RevId: 962427806

Author: GWeale

src/google/adk/labs/openai/README.md

@@ -23,4 +23,22 @@ agent = LlmAgent(
 
 Requires the `openai` Python package and `OPENAI_API_KEY` environment variable.
 
+## OpenAI-Compatible Endpoints
+
+To reach a host that speaks the OpenAI API, or to configure anything else the
+client supports, build an `AsyncOpenAI` yourself and pass it as `client`. Each
+model instance keeps its own client, so one process can talk to several hosts:
+
+```python
+from openai import AsyncOpenAI
+from google.adk.labs.openai import OpenAILlm
+
+openai_model = OpenAILlm(
+    model="my-model",
+    client=AsyncOpenAI(base_url="https://my-host.example/v1", api_key="..."),
+)
+```
+
+`OpenAIResponsesLlm` takes the same `client` field.
+
 > **Tip:** The OpenAI Python client also honors `OPENAI_BASE_URL` for OpenAI-compatible multi-model gateways — for example [DaoXE](https://daoxe.com/?utm_source=github&utm_medium=organic&utm_campaign=adk-python&utm_content=openai-labs) at `https://api.daoxe.com/v1`.

src/google/adk/labs/openai/_openai_llm.py

@@ -326,13 +326,21 @@ def _response_to_llm_response(response: ChatCompletion) -> LlmResponse:
 class OpenAILlm(BaseLlm):
   """Integration with OpenAI models.
 
+  For configuration beyond the defaults (api_key, base_url, organization,
+  timeout, retries, custom headers, ...), pass a pre-configured ``AsyncOpenAI``
+  instance as ``client``. Pointing its ``base_url`` at an OpenAI-compatible
+  host is how this model reaches a non-OpenAI backend.
+
   Attributes:
       model: The name of the OpenAI model.
       max_tokens: The maximum number of tokens to generate.
+      client: A pre-configured OpenAI client. When unset, a default client is
+        constructed, which reads its configuration from the environment.
   """
 
   model: str = "gpt-4o"
   max_tokens: int = 4096
+  client: AsyncOpenAI | None = None
 
   @classmethod
   @override
@@ -493,4 +501,6 @@ async def _generate_content_streaming(
 
   @cached_property
   def _openai_client(self) -> AsyncOpenAI:
+    if self.client is not None:
+      return self.client
     return AsyncOpenAI()

tests/unittests/labs/openai/test_openai_llm.py

@@ -25,6 +25,7 @@
 from google.genai import types
 from google.genai.types import Content
 from google.genai.types import Part
+from openai import AsyncOpenAI
 import pytest
 
 
@@ -465,3 +466,46 @@ async def mock_create(*args, **kwargs):
       ]
 
       assert responses[0].usage_metadata.cached_content_token_count is None
+
+
+@pytest.mark.asyncio
+async def test_generate_content_async_routes_through_provided_client():
+  """Requests reach the pre-configured client, not a default one."""
+  client = AsyncOpenAI(base_url="https://compatible.example/v1", api_key="k")
+  openai_llm = OpenAILlm(model="my-model", client=client)
+  llm_request = LlmRequest(
+      model="my-model",
+      contents=[Content(role="user", parts=[Part.from_text(text="Hello")])],
+  )
+
+  mock_response = mock.MagicMock()
+  mock_choice = mock.MagicMock()
+  mock_message = mock.MagicMock()
+  mock_message.content = "Hello there!"
+  mock_message.tool_calls = None
+  mock_choice.message = mock_message
+  mock_response.choices = [mock_choice]
+  mock_response.usage.prompt_tokens = 10
+  mock_response.usage.completion_tokens = 5
+  mock_response.usage.total_tokens = 15
+  mock_response.usage.prompt_tokens_details = None
+
+  async def mock_create(*args, **kwargs):
+    return mock_response
+
+  with mock.patch.object(
+      client.chat.completions, "create", side_effect=mock_create
+  ) as mock_client_create:
+    with mock.patch(
+        "google.adk.labs.openai._openai_llm.AsyncOpenAI"
+    ) as mock_client_class:
+      responses = [
+          resp
+          async for resp in openai_llm.generate_content_async(
+              llm_request, stream=False
+          )
+      ]
+
+  mock_client_class.assert_not_called()
+  mock_client_create.assert_called_once()
+  assert responses[0].content.parts[0].text == "Hello there!"