Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

fix(helm): route every agent API path to switch-core

amaudruzf58470776d60
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d85e4834c..130eb554d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -44,6 +44,18 @@ version of their own to them without also giving them a release of their own.
### [Unreleased]
+#### Fixed
+- **The Helm chart's Ingress now routes every agent API path to switch-core.**
+ `/agent-sessions` (session starts, turn activity, approval requests and their
+ answers), `/version` and `/deeplink` were missing from
+ `ingress.agentApiPaths` and from the sample Ingress, so behind a path-routed
+ ingress they reached the gateway, which answered with its web page. Agent
+ sessions then failed mid-turn with `Unexpected token '<'`, and activity and
+ approval cards never reached messaging platforms. An install that overrides
+ `ingress.agentApiPaths`, or routes with its own Ingress, must add these paths
+ itself. A test now fails when the agent bridge serves a path the chart does
+ not route.
+
### [0.29.0] - 2026-09-29
#### Added
diff --git a/core/tests/switch_core/test_ingress_agent_api_paths.py b/core/tests/switch_core/test_ingress_agent_api_paths.py
new file mode 100644
index 000000000..d98af6166
--- /dev/null
+++ b/core/tests/switch_core/test_ingress_agent_api_paths.py
@@ -0,0 +1,106 @@
+"""Every path the agent bridge serves must be routed to switch-core by the ingress.
+
+A Helm install sends `ingress.agentApiPaths` to switch-core and everything else
+to the gateway, whose SPA answers any unknown path with `200 text/html` and any
+POST with `405`. So a top-level prefix the agent bridge serves but the ingress
+does not list fails in production only, and fails badly: a session host that
+asks for JSON is handed the SPA's `<!doctype html>` and gives up mid-turn. That
+is what happened to `/agent-sessions`, which reached neither the chart's
+defaults nor the sample Ingress when it was added.
+"""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from switch_core.bridges.agent.app import create_agent_bridge_app
+from switch_core.bridges.agent.protocol.event_buffer import EventBuffer
+from switch_core.keys import Keyring
+
+_CHART = Path(__file__).resolve().parents[3] / "deploy/remote/helm/switch"
+
+# FastAPI's own pages; nothing routes them from outside.
+_NOT_PUBLISHED = {"/docs", "/openapi.json", "/redoc", "/docs/oauth2-redirect"}
+
+# Added to the agent bridge app in `main.run` rather than in
+# `create_agent_bridge_app`. `/gateway` is absent on purpose: it is reached
+# through the gateway, which proxies it to switch-core.
+_ADDED_IN_MAIN = {"/health", "/messaging"}
+
+
+def _config() -> Any:
+ class _Config:
+ agent_auth_cache_ttl_seconds = 1
+ agent_auth_cache_max_entries = 16
+ keyring = Keyring.parse("test:" + "x" * 40, legacy_secret=None)
+ oauth_issuer_url = None
+ oauth_audience = None
+ oauth_verify_issuer = True
+ id_server_name = "test"
+
+ return _Config()
+
+
+def _served_prefixes() -> set[str]:
+ app, _ = create_agent_bridge_app(
+ agent_store=object(), # type: ignore[arg-type]
+ agent_session_store=object(), # type: ignore[arg-type]
+ room_store=object(), # type: ignore[arg-type]
+ room_service=object(), # type: ignore[arg-type]
+ client_lifecycle=object(), # type: ignore[arg-type]
+ collab_lifecycle=object(), # type: ignore[arg-type]
+ event_buffer=EventBuffer(),
+ task_store=object(), # type: ignore[arg-type]
+ resource_service=object(), # type: ignore[arg-type]
+ api_key_store=object(), # type: ignore[arg-type]
+ external_user_store=object(), # type: ignore[arg-type]
+ bridge_store=object(), # type: ignore[arg-type]
+ session_factory=object(),
+ config=_config(),
+ approval_outcomes=object(), # type: ignore[arg-type]
+ )
+ prefixes = set(_ADDED_IN_MAIN)
+ for route in app.routes:
+ path = getattr(route, "path", "")
+ if path in _NOT_PUBLISHED:
+ continue
+ prefixes.add("/" + path.strip("/").split("/")[0])
+ return prefixes
+
+
+def _chart_default_paths() -> set[str]:
+ values = yaml.safe_load((_CHART / "values.yaml").read_text())
+ return set(values["ingress"]["agentApiPaths"])
+
+
+def _sample_ingress_paths() -> set[str]:
+ ingress = yaml.safe_load((_CHART / "samples/ingress.example.yaml").read_text())
+ paths: set[str] = set()
+ for rule in ingress["spec"]["rules"]:
+ for entry in rule["http"]["paths"]:
+ service = entry["backend"]["service"]
+ if (
+ service["name"].endswith("switch-core")
+ and service["port"]["number"] == 8000
+ ):
+ paths.add(entry["path"])
+ return paths
+
+
+def test_the_charts_default_ingress_routes_every_agent_bridge_prefix() -> None:
+ missing = sorted(_served_prefixes() - _chart_default_paths())
+ assert not missing, (
+ f"The agent bridge serves {missing}, but ingress.agentApiPaths in "
+ "deploy/remote/helm/switch/values.yaml does not route them to "
+ "switch-core, so they reach the gateway SPA instead."
+ )
+
+
+def test_the_sample_ingress_routes_every_agent_bridge_prefix() -> None:
+ missing = sorted(_served_prefixes() - _sample_ingress_paths())
+ assert not missing, (
+ f"The agent bridge serves {missing}, but "
+ "deploy/remote/helm/switch/samples/ingress.example.yaml does not "
+ "route them to switch-core on port 8000."
+ )
diff --git a/deploy/remote/helm/switch/samples/ingress.example.yaml b/deploy/remote/helm/switch/samples/ingress.example.yaml
index 998f9fa6a..469af0650 100644
--- a/deploy/remote/helm/switch/samples/ingress.example.yaml
+++ b/deploy/remote/helm/switch/samples/ingress.example.yaml
@@ -37,6 +37,19 @@ spec:
- path: /agents
pathType: Prefix
backend: { service: { name: RELEASE-switch-core, port: { number: 8000 } } }
+ # Session hosts report session starts, turn activity and approval
+ # requests here, and poll for approval answers. Without it a
+ # session fails on the HTML the gateway serves instead.
+ - path: /agent-sessions
+ pathType: Prefix
+ backend: { service: { name: RELEASE-switch-core, port: { number: 8000 } } }
+ - path: /version
+ pathType: Prefix
+ backend: { service: { name: RELEASE-switch-core, port: { number: 8000 } } }
+ # The "Open in Switch Console" redirect posted in messaging platforms.
+ - path: /deeplink
+ pathType: Prefix
+ backend: { service: { name: RELEASE-switch-core, port: { number: 8000 } } }
- path: /mcp
pathType: Prefix
backend: { service: { name: RELEASE-switch-core, port: { number: 8000 } } }
diff --git a/deploy/remote/helm/switch/values.yaml b/deploy/remote/helm/switch/values.yaml
index 3ab0aa1f2..8a534ca46 100644
--- a/deploy/remote/helm/switch/values.yaml
+++ b/deploy/remote/helm/switch/values.yaml
@@ -54,6 +54,11 @@ ingress:
# gateway: the Bearer-auth agent bridge + MCP, and public OAuth/MCP discovery.
agentApiPaths:
- /agents
+ # Session hosts report session starts, turn activity and approval requests
+ # here, and poll for approval answers.
+ - /agent-sessions
+ - /version
+ - /deeplink
- /mcp
- /oauth
- /.well-known