[ciaransweet]

Why

create_app built the agent once at startup and kept its tool list for the life of the process. ViewCache did the same with the view bundles. A toolset redeployed after the API started reached the model with its old descriptions, and the UI with its old views, until something restarted the API.

This happened in production on dss (ecmwf/dss-agentic-ai-services#157). The knowledge-base toolset gained an announcements section, but the agent still had the old search_knowledge description, so for two days it never searched announcements. Locally the bug can't be seen, because a fresh process always lists the current tools.

What

mcp_agent_api.refresh (new, about 60 lines)

• MCP_AGENT_API_REFRESH_SECONDS sets the interval: default 1800, 0 for never.
• fingerprint(built) hashes what the model sees of the tools: their names, descriptions and arguments.
• keep_fresh(app, build, every) runs the same build as startup on that interval, and swaps app.state.built only when the fingerprint changed. A failed build keeps the current agent; a toolset that's down makes list_tools raise, so it never silently drops that toolset's tools.

create_app

Starts keep_fresh beside the lifespan's yield and cancels it on shutdown.

ViewCache

Re-reads the bundles at most once per interval. A toolset that doesn't answer a re-read keeps the bundles it had.

Behaviour

A turn already running finishes on the agent it started with, because the routes read the agent once per request. Threads carry on across a swap, because the checkpointer is shared. Each refresh costs one connections request plus one tools/list per toolset.

A host with its own lifespan (dss) starts the same task itself. The example is in Mounting the routes into your own application in CONSUMING.md. Behaviour changes by default: existing create_app deployments start refreshing every 30 minutes, and 0 restores the old behaviour.

In dss

dss builds its own app around create_router, so it starts the refresh in its own lifespan. Once it takes this release, packages/dss-agent/src/dss_agent/api.py changes like this:

--- a/packages/dss-agent/src/dss_agent/api.py
+++ b/packages/dss-agent/src/dss_agent/api.py
@@ -51,6 +51,7 @@ questions that only need ``geocoding`` or ``ecmwf-paramdb`` are answered normall
 which a pre-flight rejection would break.
 """
 
+import asyncio
 import logging
 import os
 import secrets
@@ -67,6 +68,7 @@ from fastapi.responses import JSONResponse
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from mcp_agent.main import Checkpointing
 from mcp_agent_api.app import cors_origins
+from mcp_agent_api.refresh import keep_fresh, refresh_seconds
 from mcp_agent_api.routes import Built, create_router
 from mcp_agent_api.ui import config_from_environment, create_ui_router
 from starlette.datastructures import MutableHeaders
@@ -363,10 +365,17 @@ def create_api(
         checkpoint tables.
         """
         async with checkpointing:
-            app.state.built = await (build or _from_settings(config, checkpointing))()
+            builder = build or _from_settings(config, checkpointing)
+            app.state.built = await builder()
+            every = refresh_seconds()
+            refresh = (
+                asyncio.create_task(keep_fresh(app, builder, every)) if every else None
+            )
             try:
                 yield
             finally:
+                if refresh:
+                    refresh.cancel()
                 app.state.built = None
 
     app = FastAPI(title="dss-agent-api", lifespan=lifespan)

MCP_AGENT_API_REFRESH_SECONDS can then be set in the chart's API values; left unset, it refreshes every 30 minutes.

Tests

• In create_app: an unchanged tool list and a failed build both keep the current agent, and a changed description swaps it.
• 0 builds the agent once.
• The interval parsing.
• The view cache re-reads after the interval, and keeps a bundle the re-read missed.

611 passed. Lint clean.

🤖 Generated with Claude Code

[j08lue]

I don't fully understand how this works (create_app), but it looks clean.

[j08lue]

Your lifespan owns the refresh

This cryptic / condensed LLM-speak freaks me out.