agent-learning-kit 0.3.1__tar.gz → 0.3.2__tar.gz

{agent_learning_kit-0.3.1 → agent_learning_kit-0.3.2}/CHANGELOG.md

@@ -36,6 +36,17 @@ Post-rc.1 increments on the release branch. Each one adds gates on top of the
   ringing call so people and slow lines could never answer; the engine now
   waits for `sip.callStatus == "active"` in the room within the answer
   deadline and reports a rejected call's reason (e.g. `user_unavailable`).
+- With `AGENTCC_API_KEY` (and `AGENTCC_BASE_URL`) set, the simulated caller's
+  LLM and the `vertex-gemini` harness backend reach Gemini through Agent
+  Command Center in the Gemini API's own format, as the claude backend already
+  did, so no Vertex credential is needed. `fi.agentcc` is the one place that
+  reads the gateway settings.
+- Simulator model fallbacks: `SIMULATOR_LLM_FALLBACK_MODELS` (ordered,
+  comma-separated) gives the simulated caller models to switch to when an
+  attempt fails or times out before it speaks.
+- The `vertex-gemini` backend no longer fails on its first reply with the locked
+  ADK (2.7.1), which does not re-export `GetSessionConfig` from
+  `google.adk.sessions`.
 
 ## v1.0.0-rc.1 — 2026-06-10
 

{agent_learning_kit-0.3.1 → agent_learning_kit-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-learning-kit
-Version: 0.3.1
+Version: 0.3.2
 Summary: Unified Future AGI SDK for agent learning workflows.
 Project-URL: Homepage, https://futureagi.com
 Project-URL: Documentation, https://docs.futureagi.com
@@ -70,6 +70,8 @@ Requires-Dist: psycopg[binary]>=3.2; extra == 'harness-stores'
 Provides-Extra: harness-ui
 Requires-Dist: fastapi<1,>=0.115; extra == 'harness-ui'
 Requires-Dist: uvicorn<1,>=0.30; extra == 'harness-ui'
+Provides-Extra: hosted-tracing
+Requires-Dist: traceai-claude-agent-sdk>=0.1.0; extra == 'hosted-tracing'
 Provides-Extra: langchain
 Requires-Dist: langchain-core<2,>=1.4.6; extra == 'langchain'
 Requires-Dist: langgraph-checkpoint-sqlite>=3.1.0; extra == 'langchain'

{agent_learning_kit-0.3.1 → agent_learning_kit-0.3.2}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-learning-kit"
-version = "0.3.1"
+version = "0.3.2"
 description = "Unified Future AGI SDK for agent learning workflows."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -109,6 +109,12 @@ harness-ui = [
 harness-stores = [
   "psycopg[binary]>=3.2",
 ]
+# Tracing instrumentors the hosted image installs, declared so uv.lock pins them with everything
+# else. traceai-google-adk is not here: it pins google-genai<2 while google-adk needs >=2.12, so
+# the image installs it separately without dependencies.
+hosted-tracing = [
+  "traceai-claude-agent-sdk>=0.1.0",
+]
 feedback = ["chromadb>=0.4.0"]
 notebook = [
   "ipykernel>=6",                        # kernel for examples/agent_learning_sdk_demo.ipynb

agent_learning_kit-0.3.2/src/fi/agentcc.py

@@ -0,0 +1,62 @@
+"""Agent Command Center (AgentCC): the gateway every model call goes through when configured.
+
+``AGENTCC_API_KEY`` turns it on and ``AGENTCC_BASE_URL`` names the gateway. Each client keeps
+speaking its own vendor's protocol and only changes where it sends it, because the gateway serves
+the Gemini, Anthropic and OpenAI APIs natively: a request is relayed as written instead of being
+translated through a common format that drops what it has no field for (Gemini thinking levels,
+thought signatures).
+
+Only ALK's own clients are pointed here, explicitly. The SDKs' base-URL environment variables are
+left alone, because an agent under test running in the same process reads them too and would
+otherwise send its traffic, on our key, to our gateway.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from google.genai import types
+
+DEFAULT_BASE_URL = "https://gateway.futureagi.com"
+
+
+@dataclass(frozen=True)
+class Gateway:
+    base_url: str
+    api_key: str
+
+    def genai_http_options(self) -> types.HttpOptions:
+        """Point a google-genai client at the gateway's Gemini API routes (``/v1beta/models``).
+
+        The client must also be in Gemini API mode with this key (``vertexai=False``,
+        ``api_key=api_key``); the gateway reaches Vertex itself.
+        """
+        from google.genai import types
+
+        return types.HttpOptions(base_url=self.base_url, api_version="v1beta")
+
+    @property
+    def openai_base_url(self) -> str:
+        """The gateway's OpenAI-compatible root, for clients that append ``/chat/completions``."""
+        return f"{self.base_url}/v1"
+
+
+def gateway() -> Gateway | None:
+    """The configured gateway, or None when model calls go straight to each vendor."""
+    api_key = os.environ.get("AGENTCC_API_KEY", "").strip()
+    if not api_key:
+        return None
+    base_url = os.environ.get("AGENTCC_BASE_URL", "").strip() or DEFAULT_BASE_URL
+    return Gateway(base_url=base_url.rstrip("/"), api_key=api_key)
+
+
+def vendor_model(model: str) -> str:
+    """The vendor's own name for a gateway model: ``vertex_ai/gemini-3.7-flash`` is ``gemini-3.7-flash``.
+
+    The gateway reads the prefix to choose the upstream provider, so it stays on the wire; what a
+    model can do, and a call made straight to the vendor, go by the name without it.
+    """
+    return model.rsplit("/", 1)[-1]

{agent_learning_kit-0.3.1 → agent_learning_kit-0.3.2}/src/fi/alk/harness/backends/README.md

@@ -8,6 +8,8 @@ ALK_HARNESS=claude          # default; Claude Code loop, exactly the pre-seam be
 ALK_HARNESS=vertex-gemini   # Google's ADK against Vertex (location=global)
 ALK_HARNESS_MODEL=...       # optional; unset means the backend's own default
 ALK_VERTEX_LOCATION=...     # vertex-gemini only; defaults to global (Gemini 3.x lives there)
+AGENTCC_API_KEY=...         # both backends then reach their models through Agent Command Center
+AGENTCC_BASE_URL=...        # (fi/agentcc.py)
 ```
 
 ## The seam

{agent_learning_kit-0.3.1 → agent_learning_kit-0.3.2}/src/fi/alk/harness/backends/claude.py

@@ -32,6 +32,8 @@ from claude_agent_sdk import (
     create_sdk_mcp_server,
 )
 
+from fi import agentcc
+
 from .base import (
     ASK_TOOL,
     DELEGATE_TOOL,
@@ -362,22 +364,15 @@ class ClaudeBackend:
 
     def can_drive(self, model: str) -> bool:
         # Agent CC's native Anthropic endpoint accepts the Claude Agent SDK wire format and
-        # translates it for the provider named by the model. Without a gateway, this backend
-        # still only advertises models supported by Claude Code directly.
+        # translates it for any provider configured behind the virtual key. Without a gateway,
+        # this backend only advertises models supported by Claude Code directly.
         named = (model or "").lower()
         if "claude" in named:
             return True
-        if os.environ.get("AGENTCC_API_KEY", "").strip():
-            return True
-        gateway_ready = bool(
-            (
-                os.environ.get("ALK_CLAUDE_GATEWAY_URL", "").strip()
-                and os.environ.get("ALK_CLAUDE_GATEWAY_API_KEY", "").strip()
-            )
-            or os.environ.get("AGENTCC_API_KEY", "").strip()
+        gateway_ready = agentcc.gateway() is not None or bool(
+            os.environ.get("ALK_CLAUDE_GATEWAY_URL", "").strip()
+            and os.environ.get("ALK_CLAUDE_GATEWAY_API_KEY", "").strip()
         )
-        # Agent CC's native Anthropic endpoint accepts the Claude Agent SDK wire format and
-        # translates it for any provider configured behind the virtual key.
         return gateway_ready and bool(named)
 
     def create(self, spec: SessionSpec) -> ClaudeSession:

{agent_learning_kit-0.3.1 → agent_learning_kit-0.3.2}/src/fi/alk/harness/backends/vertex_gemini.py

@@ -8,7 +8,8 @@ event stream is translated into the neutral reply vocabulary. The loop itself is
 
 The Gemini 3.x models this exists for are served from the ``global`` endpoint only, which is
 why ``ALK_VERTEX_LOCATION`` defaults to ``global`` rather than to a region. Regional Vertex
-deployments of older models can point it elsewhere.
+deployments of older models can point it elsewhere. With Agent Command Center configured
+(``AGENTCC_API_KEY``) the same requests go to the gateway instead, which reaches Vertex itself.
 
 Read, Glob and Grep come from files.py when a stage grants them. AskUserQuestion is offered only
 when an attended session supplies an operator callback; unattended authoring keeps the tool absent.
@@ -25,6 +26,8 @@ from collections.abc import AsyncIterator
 from datetime import date
 from typing import Any
 
+from fi import agentcc
+
 from .base import (
     ASK_TOOL,
     FILE_TOOLS,
@@ -214,6 +217,20 @@ def _location() -> str:
     return os.environ.get("ALK_VERTEX_LOCATION", "global").strip() or "global"
 
 
+def _llm(model: str) -> Any:
+    """What an agent runs on: the model name for Vertex, or a Gemini aimed at the gateway."""
+    gateway = agentcc.gateway()
+    if gateway is None:
+        return agentcc.vendor_model(model)
+    from google.adk.models import Gemini
+
+    return Gemini(
+        model=model,
+        base_url=gateway.base_url,
+        client_kwargs={"vertexai": False, "api_key": gateway.api_key},
+    )
+
+
 def _flattened(result: Any) -> str:
     content = result.get("content") if isinstance(result, dict) else None
     if isinstance(content, list):
@@ -472,7 +489,7 @@ class VertexGeminiSession:
                 LlmAgent(
                     name=re.sub(r"[^0-9A-Za-z_]", "_", name),
                     description=worker.description,
-                    model=worker.model or self._model,
+                    model=_llm(worker.model or self._model),
                     mode="single_turn",
                     static_instruction=types.Content(
                         role="user", parts=[types.Part(text=worker.instructions)]
@@ -493,12 +510,13 @@ class VertexGeminiSession:
         from google.adk.sessions import InMemorySessionService
         from google.genai import types
 
-        os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "TRUE"
-        os.environ["GOOGLE_CLOUD_PROJECT"] = _project()
-        os.environ["GOOGLE_CLOUD_LOCATION"] = _location()
+        if agentcc.gateway() is None:
+            os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "TRUE"
+            os.environ["GOOGLE_CLOUD_PROJECT"] = _project()
+            os.environ["GOOGLE_CLOUD_LOCATION"] = _location()
         agent = LlmAgent(
             name=self.session_id.replace("-", "_"),
-            model=self._model,
+            model=_llm(self._model),
             static_instruction=types.Content(
                 role="user", parts=[types.Part(text=self._spec.system_prompt)]
             ),
@@ -575,7 +593,9 @@ class VertexGeminiSession:
 
     async def replies(self) -> AsyncIterator[Any]:
         from google.adk.agents.run_config import RunConfig, StreamingMode
-        from google.adk.sessions import GetSessionConfig
+
+        # google.adk.sessions does not re-export it in the locked ADK (2.7.1).
+        from google.adk.sessions.base_session_service import GetSessionConfig
         from google.genai import types
 
         if self._runner is None or (
@@ -775,7 +795,7 @@ class VertexGeminiBackend:
     default_model = DEFAULT_MODEL
 
     def can_drive(self, model: str) -> bool:
-        return (model or "").lower().startswith("gemini")
+        return agentcc.vendor_model(model or "").lower().startswith("gemini")
 
     def create(self, spec: SessionSpec) -> VertexGeminiSession:
         return VertexGeminiSession(spec, model=spec.model or self.default_model)

{agent_learning_kit-0.3.1 → agent_learning_kit-0.3.2}/src/fi/alk/harness/call_runner.py

@@ -42,7 +42,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Awaitable, Callable, Mapping, Protocol
 
-from fi import simulate
+from fi import agentcc, simulate
 from fi.simulate.runtime import (
     SimulationSpec,
     new_run_id,
@@ -358,7 +358,9 @@ def _check_config(
 
     missing_aliases = [alias for alias in required if not credential(alias)]
 
-    if llm_provider == "google":
+    # Through the gateway the model is reached on the gateway's credentials, not the caller's.
+    direct = agentcc.gateway() is None
+    if direct and llm_provider == "google":
         has_api_key = bool(
             simulator_value(GEMINI_API_KEY_ALIAS)
             or simulator_value(GOOGLE_API_KEY_ALIAS)
@@ -374,7 +376,11 @@ def _check_config(
             missing_aliases.append(
                 f"{GEMINI_API_KEY_ALIAS}_or_{GOOGLE_API_KEY_ALIAS}_or_VERTEX_ADC"
             )
-    elif llm_provider == "openai" and not simulator_value(OPENAI_API_KEY_ALIAS):
+    elif (
+        direct
+        and llm_provider == "openai"
+        and not simulator_value(OPENAI_API_KEY_ALIAS)
+    ):
         missing_aliases.append(OPENAI_API_KEY_ALIAS)
 
     has_livekit_url = bool(

{agent_learning_kit-0.3.1 → agent_learning_kit-0.3.2}/src/fi/alk/harness/config.py

@@ -14,6 +14,8 @@ import os
 from pathlib import Path
 from typing import Any, Iterable
 
+from fi import agentcc
+
 from .backends import SessionSpec, resolve
 
 # The first backend's default, kept importable because callers and tests name it. The model a
@@ -34,10 +36,7 @@ def credentials_hint() -> str:
     which is a legitimate setup and an easy accident. The accident produces a provider auth
     error several layers down, so it is worth saying out loud which one is in play.
     """
-    if (
-        os.environ.get("ALK_CLAUDE_GATEWAY_API_KEY", "").strip()
-        or os.environ.get("AGENTCC_API_KEY", "").strip()
-    ):
+    if os.environ.get("ALK_CLAUDE_GATEWAY_API_KEY", "").strip() or agentcc.gateway():
         return "credentials: Agent Command Center virtual key"
     named = os.environ.get("GOOGLE_APPLICATION_CREDENTIALS")
     if named:
@@ -122,9 +121,7 @@ def refuse_a_model_we_cannot_afford(model: str) -> None:
 
 def behind_gateway(model: str) -> bool:
     """Whether this model is reached through Agent Command Center rather than the CLI's own route."""
-    return bool(os.environ.get("AGENTCC_API_KEY", "").strip()) and "claude" not in (
-        model or ""
-    ).lower()
+    return agentcc.gateway() is not None and "claude" not in (model or "").lower()
 
 
 def gateway_wire_model(model: str) -> str:
@@ -149,18 +146,13 @@ def provider_env(model: str | None = None) -> dict[str, str]:
     chosen = chosen_model(model)
     refuse_a_model_we_cannot_afford(chosen)
     # Agent Command Center speaks Anthropic Messages in front of the model this run chose.
-    agentcc_key = os.environ.get("AGENTCC_API_KEY", "").strip()
-    if agentcc_key and not os.environ.get("ALK_CLAUDE_GATEWAY_URL", "").strip():
-        base_url = (
-            os.environ.get("AGENTCC_BASE_URL", "https://gateway.futureagi.com")
-            .strip()
-            .rstrip("/")
-        )
+    gateway = agentcc.gateway()
+    if gateway is not None and not os.environ.get("ALK_CLAUDE_GATEWAY_URL", "").strip():
         wire = gateway_wire_model(chosen)
         return {
             # Bearer token, which is how a virtual key authenticates (API_KEY would use x-api-key).
-            "ANTHROPIC_AUTH_TOKEN": agentcc_key,
-            "ANTHROPIC_BASE_URL": base_url,
+            "ANTHROPIC_AUTH_TOKEN": gateway.api_key,
+            "ANTHROPIC_BASE_URL": gateway.base_url,
             # ClaudeAgentOptions.env is merged over the parent's, so a parent's Vertex flag must be undone.
             "CLAUDE_CODE_USE_VERTEX": "0",
             # The SDK cannot look up a non-Claude context window, so it is declared.
@@ -212,24 +204,6 @@ def provider_env(model: str | None = None) -> dict[str, str]:
         )
         return env
 
-    agentcc_key = os.environ.get("AGENTCC_API_KEY", "").strip()
-    if agentcc_key:
-        base_url = (
-            os.environ.get("AGENTCC_BASE_URL", "https://gateway.futureagi.com")
-            .strip()
-            .rstrip("/")
-        )
-        env.update(
-            {
-                # AUTH_TOKEN is sent as a Bearer token, which is how AgentCC virtual keys
-                # authenticate. API_KEY would instead use Anthropic's x-api-key header.
-                "ANTHROPIC_AUTH_TOKEN": agentcc_key,
-                "ANTHROPIC_BASE_URL": base_url,
-                "CLAUDE_CODE_USE_VERTEX": "0",
-            }
-        )
-        return env
-
     env["CLAUDE_CODE_USE_VERTEX"] = "1"
     env["CLOUD_ML_REGION"] = os.environ.get("CLOUD_ML_REGION", "us-east5")
     for passthrough in (

{agent_learning_kit-0.3.1 → agent_learning_kit-0.3.2}/src/fi/alk/harness/hosted_entrypoint.py

@@ -217,6 +217,7 @@ _SIMULATOR_SECRET_ALIASES = frozenset(
         "OPENAI_API_KEY",
         "SIMULATOR_LLM_MODEL",
         "SIMULATOR_LLM_PROVIDER",
+        "SIMULATOR_LLM_FALLBACK_MODELS",
         "SIMULATOR_LLM_THINKING",
         "SIMULATOR_STT_MODEL",
         "SIMULATOR_STT_PROVIDER",

{agent_learning_kit-0.3.1 → agent_learning_kit-0.3.2}/src/fi/alk/harness/run/models.py

@@ -26,6 +26,8 @@ from __future__ import annotations
 
 import os
 
+from fi import agentcc
+
 # What the reconstructed agent and the simulated user run on today. Both roles run constantly, so
 # this is the setting worth revisiting first once the target can be handed to ALK.
 AGENT = "claude-sonnet-4-6"
@@ -50,7 +52,7 @@ def for_roles(override: str | None = None) -> dict[str, str]:
     gateway_model = (
         os.environ.get("ALK_HARNESS_MODEL", "").strip()
         if os.environ.get("ALK_HARNESS", "").strip().lower() in {"claude", "claude-code"}
-        and os.environ.get("AGENTCC_API_KEY", "").strip()
+        and agentcc.gateway() is not None
         else ""
     )
     return {

{agent_learning_kit-0.3.1 → agent_learning_kit-0.3.2}/src/fi/alk/harness/simulator_voice.py

@@ -34,12 +34,16 @@ CONNECT_TIMEOUT_SECONDS = 60.0
 READINESS_TIMEOUT_SECONDS = 120.0
 CLEANUP_TIMEOUT_SECONDS = 30.0
 
-# Supported endpoint overrides used by the simulator model adapter.
+# Model routing the simulator's model adapter reads: where calls go, on which key, and what to
+# fall back to. A call worker starts from a closed environment, so each must be listed.
 SIMULATOR_MODEL_ENV = frozenset(
     {
+        "AGENTCC_API_KEY",
+        "AGENTCC_BASE_URL",
         "SIMULATOR_LLM_API_KEY",
         "SIMULATOR_LLM_BASE_URL",
         "SIMULATOR_LLM_API_KEY_HEADER",
+        "SIMULATOR_LLM_FALLBACK_MODELS",
         "SIMULATOR_LLM_THINKING",
         "OPENAI_BASE_URL",
     }

{agent_learning_kit-0.3.1 → agent_learning_kit-0.3.2}/src/fi/simulate/simulation/livekit_models.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import functools
 import logging
 import os
 from collections.abc import Callable
@@ -9,6 +10,7 @@ from types import ModuleType
 import aiohttp
 
 try:
+    from livekit.agents import DEFAULT_API_CONNECT_OPTIONS
     from livekit.agents import llm as livekit_llm
     from livekit.agents import stt as livekit_stt
     from livekit.agents import tts as livekit_tts
@@ -17,6 +19,7 @@ except ImportError as exc:
         "LiveKit model construction requires the 'livekit' optional dependency"
     ) from exc
 
+from fi import agentcc
 from fi.simulate.agent.definition import LLMConfig, STTConfig, TTSConfig
 
 logger = logging.getLogger(__name__)
@@ -57,12 +60,14 @@ def _openai_llm(config: LLMConfig) -> livekit_llm.LLM:
         "model": config.model,
         "temperature": config.temperature,
     }
-    api_key = os.environ.get("SIMULATOR_LLM_API_KEY") or os.environ.get(
-        "OPENAI_API_KEY"
-    )
-    base_url = os.environ.get("SIMULATOR_LLM_BASE_URL") or os.environ.get(
-        "OPENAI_BASE_URL"
-    )
+    api_key = os.environ.get("SIMULATOR_LLM_API_KEY")
+    base_url = os.environ.get("SIMULATOR_LLM_BASE_URL")
+    # An endpoint named for the simulator wins; otherwise the gateway, when there is one.
+    gateway = agentcc.gateway()
+    if not base_url and gateway is not None:
+        base_url, api_key = gateway.openai_base_url, gateway.api_key
+    api_key = api_key or os.environ.get("OPENAI_API_KEY")
+    base_url = base_url or os.environ.get("OPENAI_BASE_URL")
     if api_key:
         kwargs["api_key"] = api_key
     if base_url:
@@ -252,23 +257,52 @@ def _google_speech_credentials_kwargs() -> dict[str, object]:
 
 def _google_llm(config: LLMConfig) -> livekit_llm.LLM:
     google = _import_plugin("google")
-    kwargs = _google_credentials_kwargs()
     model = _provider_model(
         config.model,
         default="gpt-4o",
         replacement="gemini-2.5-flash-lite",
     )
+    # The gateway names a model by the provider serving it: vertex_ai/gemini-3.7-flash is Vertex,
+    # a bare name is the Gemini API. That prefix only routes; everything else uses the bare name.
+    name = agentcc.vendor_model(model)
+    thinking = _simulator_thinking(name)
+    gateway = agentcc.gateway()
+    if gateway is not None:
+        # Gemini API mode with the gateway key; the gateway reaches Vertex on its own credentials.
+        return _gateway_google_llm(google)(
+            model=model,
+            temperature=config.temperature,
+            vertexai=False,
+            api_key=gateway.api_key,
+            http_options=gateway.genai_http_options(),
+            **({"thinking_config": thinking} if thinking is not None else {}),
+        )
+    kwargs = _google_credentials_kwargs()
     if (
         kwargs.get("vertexai") is True
-        and model.startswith("gemini-3")
+        and name.startswith("gemini-3")
         and not os.environ.get("GOOGLE_CLOUD_LOCATION")
         and not os.environ.get("VERTEX_LOCATION")
     ):
         kwargs["location"] = "global"
-    thinking = _simulator_thinking(model)
     if thinking is not None:
         kwargs["thinking_config"] = thinking
-    return google.LLM(model=model, temperature=config.temperature, **kwargs)
+    return google.LLM(model=name, temperature=config.temperature, **kwargs)
+
+
+@functools.cache
+def _gateway_google_llm(google: ModuleType) -> type[livekit_llm.LLM]:
+    """The plugin's LLM, minus a prewarm that would carry the gateway key to Google.
+
+    The plugin applies ``http_options`` per request, but warms up with a client built without
+    them, so its prewarm call would go to Google's Gemini API with the gateway's key.
+    """
+
+    class GatewayGoogleLLM(google.LLM):
+        async def _prewarm_impl(self) -> None:
+            return None
+
+    return GatewayGoogleLLM
 
 
 # Which control a model accepts for deliberation is a provider fact and cannot be inferred from a
@@ -413,7 +447,27 @@ _HTTP_PROVIDERS = {"cartesia", "deepgram", "elevenlabs"}
 def build_livekit_llm(config: LLMConfig) -> livekit_llm.LLM:
     provider = config.provider.lower()
     factory = _factory(_LLM_FACTORIES, provider, "LLM")
-    return factory(config)
+    primary = factory(config)
+    fallback_models = [
+        model.strip()
+        for model in os.environ.get("SIMULATOR_LLM_FALLBACK_MODELS", "").split(",")
+        if model.strip() and model.strip() != config.model
+    ]
+    if not fallback_models:
+        return primary
+    # Each fallback runs on the same provider. LiveKit moves to the next model when an attempt
+    # fails or times out before anything was said, so the caller is not left silent; each attempt
+    # gets the time one LLM gets without fallbacks.
+    return livekit_llm.FallbackAdapter(
+        [
+            primary,
+            *(
+                factory(config.model_copy(update={"model": model}))
+                for model in fallback_models
+            ),
+        ],
+        attempt_timeout=DEFAULT_API_CONNECT_OPTIONS.timeout,
+    )
 
 
 async def build_livekit_models(