fix(models): cache the Gemini client per event loop so reused agents survive loop teardown

[AtulJoshi1206]

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Closes: RuntimeError: Event loop is closed caused by Gemini.api_client @cached_property #5538
• Related: fix: prevent RuntimeError: Event loop is closed for Gemini.api_client (#5538) #5543 (earlier attempt, closed on 2026-09-16 because its tests were red; @GWeale asked for a fresh PR off current main and confirmed the loop-keyed approach was sound)

Problem:

Gemini.api_client and Gemini._live_api_client are functools.cached_property, so one google.genai.Client is built per Gemini instance and kept for the life of the process. A google.genai.Client binds its async HTTP connection pool to the event loop that first drives it. Deployments such as Vertex AI Agent Engine serve every request on a fresh OS thread with a fresh asyncio.run() loop while reusing the same agent (and therefore the same Gemini instance), so from the second request on the cached client is driven on a loop other than the one it is bound to and fails with:

RuntimeError: Event loop is closed

Users have been shipping an UncachedGemini subclass workaround for five months (see the issue thread). ApigeeLlm overrides api_client with the same cached_property and has the same defect.

Reproduced on current main with a local fake Gemini endpoint and one thread + one asyncio.run() per request (three requests through one Gemini instance):

transport	request 1	request 2	request 3
aiohttp (google-genai ≥ 2.11 keys its aiohttp sessions per loop)	ok	ok	ok
httpx (default when aiohttp is not installed; it is only in the mcp/all extras)	ok	RuntimeError: Event loop is closed	ok

The intermittent pattern (a request fails, the next one succeeds once the dead pooled connection is evicted) matches the "after 3-5 requests" in the report.

Solution:

Cache the client per event loop instead of per instance.

• google_llm.py: a module-level _client_for_running_loop(clients, build) keys clients by asyncio.get_running_loop() (None when no loop is running), builds outside the lock (construction may resolve credentials), and prunes entries whose loop is_closed() so the cache stays bounded by the number of live loops. A threading.Lock guards the dict because loops on different OS threads read and prune it concurrently.
• Gemini.api_client / Gemini._live_api_client become plain @propertys backed by two pydantic PrivateAttr dicts. Construction moves into _build_api_client() / _build_live_api_client(). A caller-supplied client= is still returned as-is; its lifecycle stays with the caller.
• ApigeeLlm now overrides _build_api_client() instead of api_client, so it inherits the per-loop caching for free (13-line diff).
• The Gemini class docstring example no longer tells users to override with cached_property; it explains why that is unsafe across loops.

Why this shape and not the alternatives:

• A plain uncached @property (the workaround in the thread) fixes the crash but opens a new TCP+TLS connection on every access, losing connection pooling within a request.
• A single (loop, client) slot (the shape of fix: prevent RuntimeError: Event loop is closed for Gemini.api_client (#5538) #5543) thrashes when several request loops are alive at once on Agent Engine, rebuilding a client on nearly every access. A dict keyed by loop reuses each loop's client for the loop's whole lifetime.

Behaviour unchanged: a Gemini accessed from one loop still gets exactly one client, so existing pooling and _api_backend detection are untouched.

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

New tests (tests/unittests/models/test_google_llm.py, test_apigee_llm.py), all through the public interface:

• client reused within one event loop
• client rebuilt for a new asyncio.run() loop
• client rebuilt per thread running its own loop (the Agent Engine pattern)
• client of a closed loop is released (weakref dies after GC; no accumulation)
• injected client= shared across loops as-is
• live client reused within a loop and rebuilt for a new one
• request and live clients cached independently
• ApigeeLlm client rebuilt per loop (constructor called twice)

Test migration: the 44 existing sites that did mock.patch.object(gemini_llm, "api_client" | "_live_api_client") relied on cached_property being settable. They now patch the public client field, which both properties honour, so the tests exercise the supported injection path and no longer depend on the caching mechanism. This is what broke CI on #5543.

$ pytest tests/unittests/models/test_google_llm.py tests/unittests/models/test_apigee_llm.py tests/unittests/models/test_custom_client.py -q
186 passed, 3 warnings

$ pytest tests/unittests -n auto -q
15160 passed, 86 skipped, 27 xfailed, 2 xpassed in 388.53s (0:06:28)

$ pre-commit run --files <changed files>   # all hooks Passed
$ mypy src/google/adk/models/google_llm.py src/google/adk/models/apigee_llm.py
# one pre-existing error at the `aclosing(...)` call, identical on main; no new errors

Manual End-to-End (E2E) Tests:

Script mimicking Agent Engine (one Gemini instance, each request on a new thread with its own asyncio.run(), against a local fake endpoint returning a fixed generateContent response), run with the httpx transport forced:

before (main):      request 1: ok | request 2: RuntimeError: Event loop is closed | request 3: ok
after (this PR):    request 1: ok | request 2: ok                                 | request 3: ok

One thing reviewers will see in that log after the fix: when a stale client is garbage-collected, google.genai's BaseApiClient.__del__ schedules aclose() on whatever loop is currently running, and closing connections that belong to the finished loop logs Task exception was never retrieved ... Event loop is closed. That is SDK teardown noise, not a request failure, and it is identical to what the documented UncachedGemini workaround produces today. Fixing it belongs in google-genai (its destructor would need to skip connections from a foreign loop).

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules. (none)

Additional context

Public API impact: Gemini.api_client stays a read-only attribute returning a google.genai.Client. The only observable change is for code that assigned to gemini.api_client (possible with cached_property, not with a property); the supported path for that is the client= field, which is what the migrated tests use.

🤖 Generated with Claude Code

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.