feat(adk): make AgentEx client HTTP timeouts configurable by env var

The AgentEx client's timeout comes from the SDK's DEFAULT_TIMEOUT,
Timeout(connect=5.0, read=300, write=300, pool=300). Application code
cannot change it: the ADK constructs its own clients internally at 14
sites (messages, tasks, events, tracing), all through
create_async_agentex_client(), and none accepts a timeout from the caller.
No environment variable controlled it either.

The connect timeout is the one that matters. An AgentEx backend accepts
connections serially, so connect latency grows with the number of
concurrent callers. Measured against a local backend:

  concurrency    1     84 ms
  concurrency   20    423 ms
  concurrency  100    500 ms
  concurrency  200  1,010 ms

An agent running 100 concurrent activities, each making ADK calls, pushes
past the 5s budget and fails with httpcore.ConnectTimeout. One run
produced 197 such failures in a single activity. A 5s connect against a
300s read is also internally inconsistent.

Adds AGENTEX_CLIENT_{CONNECT,READ,WRITE,POOL}_TIMEOUT_SECONDS, following
the existing EnvVarKeys and EnvironmentVariables pattern. Defaults equal
the current DEFAULT_TIMEOUT, so an unconfigured process is unchanged. An
explicit timeout= argument still wins, and a malformed value falls back to
the SDK default with a warning rather than preventing client creation.

Author: chakrris

src/agentex/lib/adk/utils/_modules/client.py

@@ -26,7 +26,35 @@ def auth_flow(self, request):
         yield request
 
 
+def _timeout_from_env() -> httpx.Timeout:
+    """Build the client timeout from environment variables.
+
+    Defaults match the SDK's DEFAULT_TIMEOUT, so an unconfigured process behaves
+    exactly as before. The connect timeout is the one worth raising: an AgentEx
+    backend accepts connections serially, so connect latency grows with the number
+    of callers and the 5s default is reached when a few hundred are in flight.
+    """
+    env_vars = EnvironmentVariables.refresh()
+    return httpx.Timeout(
+        connect=env_vars.AGENTEX_CLIENT_CONNECT_TIMEOUT_SECONDS,
+        read=env_vars.AGENTEX_CLIENT_READ_TIMEOUT_SECONDS,
+        write=env_vars.AGENTEX_CLIENT_WRITE_TIMEOUT_SECONDS,
+        pool=env_vars.AGENTEX_CLIENT_POOL_TIMEOUT_SECONDS,
+    )
+
+
 def create_async_agentex_client(**kwargs) -> AsyncAgentex:
+    """Create an AsyncAgentex client.
+
+    An explicit ``timeout=`` always wins; otherwise the timeout comes from the
+    AGENTEX_CLIENT_*_TIMEOUT_SECONDS environment variables.
+    """
+    if "timeout" not in kwargs:
+        try:
+            kwargs["timeout"] = _timeout_from_env()
+        except Exception as exc:
+            # Never let timeout configuration stop a client being created.
+            logger.warning("Falling back to SDK default timeout: %r", exc)
     client = AsyncAgentex(**kwargs)
     client._client.auth = EnvAuth()
     return client

src/agentex/lib/environment_variables.py

@@ -20,6 +20,11 @@ class EnvVarKeys(str, Enum):
     TEMPORAL_ADDRESS = "TEMPORAL_ADDRESS"
     REDIS_URL = "REDIS_URL"
     AGENTEX_BASE_URL = "AGENTEX_BASE_URL"
+    # AgentEx client HTTP timeouts (seconds)
+    AGENTEX_CLIENT_CONNECT_TIMEOUT_SECONDS = "AGENTEX_CLIENT_CONNECT_TIMEOUT_SECONDS"
+    AGENTEX_CLIENT_READ_TIMEOUT_SECONDS = "AGENTEX_CLIENT_READ_TIMEOUT_SECONDS"
+    AGENTEX_CLIENT_WRITE_TIMEOUT_SECONDS = "AGENTEX_CLIENT_WRITE_TIMEOUT_SECONDS"
+    AGENTEX_CLIENT_POOL_TIMEOUT_SECONDS = "AGENTEX_CLIENT_POOL_TIMEOUT_SECONDS"
     # Agent Identifiers
     AGENT_NAME = "AGENT_NAME"
     AGENT_DESCRIPTION = "AGENT_DESCRIPTION"
@@ -61,6 +66,14 @@ class EnvironmentVariables(BaseModel):
     TEMPORAL_ADDRESS: str | None = "localhost:7233"
     REDIS_URL: str | None = None
     AGENTEX_BASE_URL: str | None = "http://localhost:5003"
+    # HTTP timeouts for the AgentEx client, in seconds. Defaults match the
+    # SDK's DEFAULT_TIMEOUT, so leaving these unset changes nothing.
+    # Raise the connect timeout when many concurrent activities share one
+    # backend: accepts queue, and 5s is reached at a few hundred in flight.
+    AGENTEX_CLIENT_CONNECT_TIMEOUT_SECONDS: float = 5.0
+    AGENTEX_CLIENT_READ_TIMEOUT_SECONDS: float = 300.0
+    AGENTEX_CLIENT_WRITE_TIMEOUT_SECONDS: float = 300.0
+    AGENTEX_CLIENT_POOL_TIMEOUT_SECONDS: float = 300.0
     # Agent Identifiers
     AGENT_NAME: str
     AGENT_DESCRIPTION: str | None = None

tests/lib/test_client_timeout_env.py

@@ -0,0 +1,102 @@
+"""Timeouts for the AgentEx client are configurable by environment variable.
+
+The connect timeout is the one that matters in practice. An AgentEx backend
+accepts connections serially, so connect latency grows with the number of
+concurrent callers, and the 5s default is reached once a few hundred are in
+flight. Before this was configurable, the only way to change it was to pass
+``timeout=`` at every construction site, which application code cannot do for
+the client the ADK builds internally.
+"""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+
+import agentex.lib.environment_variables as env_module
+from agentex.lib.adk.utils._modules.client import (
+    _timeout_from_env,
+    create_async_agentex_client,
+)
+from agentex.lib.environment_variables import EnvironmentVariables
+
+
+@pytest.fixture(autouse=True)
+def _clear_env_cache():
+    """EnvironmentVariables.refresh() memoises into a module global."""
+    env_module.refreshed_environment_variables = None
+    yield
+    env_module.refreshed_environment_variables = None
+
+
+def _set_env(monkeypatch, **overrides: str) -> None:
+    # EnvironmentVariables has required fields; set them so construction succeeds.
+    monkeypatch.setenv("AGENT_NAME", "test-agent")
+    monkeypatch.setenv("ACP_URL", "http://localhost:8000")
+    for key, value in overrides.items():
+        monkeypatch.setenv(key, value)
+
+
+def test_defaults_match_the_sdk_default_timeout(monkeypatch):
+    """An unconfigured process must behave exactly as it did before."""
+    _set_env(monkeypatch)
+    timeout = _timeout_from_env()
+    assert timeout.connect == 5.0
+    assert timeout.read == 300.0
+    assert timeout.write == 300.0
+    assert timeout.pool == 300.0
+
+
+def test_connect_timeout_is_configurable(monkeypatch):
+    _set_env(monkeypatch, AGENTEX_CLIENT_CONNECT_TIMEOUT_SECONDS="30")
+    timeout = _timeout_from_env()
+    assert timeout.connect == 30.0
+    # the others are untouched
+    assert timeout.read == 300.0
+
+
+def test_all_four_are_configurable(monkeypatch):
+    _set_env(
+        monkeypatch,
+        AGENTEX_CLIENT_CONNECT_TIMEOUT_SECONDS="30",
+        AGENTEX_CLIENT_READ_TIMEOUT_SECONDS="120",
+        AGENTEX_CLIENT_WRITE_TIMEOUT_SECONDS="90",
+        AGENTEX_CLIENT_POOL_TIMEOUT_SECONDS="60",
+    )
+    timeout = _timeout_from_env()
+    assert (timeout.connect, timeout.read, timeout.write, timeout.pool) == (
+        30.0,
+        120.0,
+        90.0,
+        60.0,
+    )
+
+
+def test_client_picks_up_the_env_timeout(monkeypatch):
+    _set_env(monkeypatch, AGENTEX_CLIENT_CONNECT_TIMEOUT_SECONDS="30")
+    client = create_async_agentex_client(api_key="test", base_url="http://localhost:5003")
+    assert client.timeout.connect == 30.0
+
+
+def test_explicit_timeout_wins_over_the_environment(monkeypatch):
+    _set_env(monkeypatch, AGENTEX_CLIENT_CONNECT_TIMEOUT_SECONDS="30")
+    client = create_async_agentex_client(
+        api_key="test",
+        base_url="http://localhost:5003",
+        timeout=httpx.Timeout(connect=7.0, read=8.0, write=9.0, pool=10.0),
+    )
+    assert client.timeout.connect == 7.0
+
+
+def test_env_auth_is_still_attached(monkeypatch):
+    """The factory's original job must survive the change."""
+    _set_env(monkeypatch)
+    client = create_async_agentex_client(api_key="test", base_url="http://localhost:5003")
+    assert client._client.auth is not None
+
+
+def test_a_bad_value_does_not_prevent_client_creation(monkeypatch):
+    """Timeout configuration must never be the reason a client fails to build."""
+    _set_env(monkeypatch, AGENTEX_CLIENT_CONNECT_TIMEOUT_SECONDS="not-a-number")
+    client = create_async_agentex_client(api_key="test", base_url="http://localhost:5003")
+    assert client is not None