FastAPI + AgentOS: Pattern for Production

[user1500177]

Overview

We've built a production-ready AgentOS integration for FastAPI using the mount() pattern with explicit MCP lifecycle management. We want to validate this approach with the community—is it the best practice, or should we is there something we can indeed use that we missed from agno side without breaking the present features?

---

Our Current Approach

@asynccontextmanager
async def lifespan(app: FastAPI):
    """
    Explicit MCP tool lifecycle management:
    1. Analyze tool instances needs (which tools are actually used? based on the app_config )
    2. Create only needed tools
    3. Connect with retry (3 attempts, 2s delay)
    4. FAIL HARD if any required tool fails
    5. Mount AgentOS (all tools ready)
    6. On shutdown: disconnect all tools gracefully
    """
    try:
        # Step 1: Initialize framework
        bootstrapper.initialize()
        config_service = bootstrapper.get_config()
        
        # Step 2: Analyze needs
        needs = analyze_tool_needs(app_config)
        
        # Step 3: Create only needed tools
        mcp_tools = await create_tools_conditionally(needs)
        
        # Step 4: Connect with retry
        connected, failed = await connect_all_with_retry(
            mcp_tools,
            max_retries=3,
            delay=2,
        )
        
        # Step 5: Fail hard if required tools missing
        if failed:
            raise RuntimeError(f"Could not connect: {failed}")
        
        # Step 6: NOW create AgentOS (tools guaranteed ready)
        agent_os = AgentOS(teams=[...], agents=[...])
        app.mount("/v1/api", agent_os.get_app())
        
        yield  # App is running
        
    except Exception as e:
        logger.error(f"Startup failed: {e}")
        raise
    
    finally:
        # Shutdown: disconnect all tools
        await disconnect_all_tools(mcp_tools)

---

Architecture: What We Do

FastAPI main_app
├── Middleware Stack
│   ├── ApplicationContextMiddleware  (extract headers)
│   ├── AgentContextMiddleware        (enrich context)
│   ├── PhoenixContextMiddleware      (OTel tracing)
│   └── CORSMiddleware
├── Version-prefixed routes
│   ├── /v1/api/health/live          (liveness)
│   ├── /v1/api/health/ready         (readiness)
│   ├── /v1/api/admin/*              (service control)
│   └── /v1/api/swagger/*            (docs)
└── Mount AgentOS (inside lifespan!)
    └── /v1/api/*                    (AgentOS routes)
        ├── /agents/*                (AGUI agents)
        └── /teams/*                 (Team orchestration)

---

1. Is mount() the right pattern for production? Or should we use base_app with modifications (which i saw now , can we use that and be able to sure to add the tracing , middlewares and the extra routes prefixes etc )

2. Agno docs say "automatic connection management"—should we trust it more?

Automatic Connection Management in AgentOS
When using MCPTools within AgentOS, the lifecycle is automatically managed. No need to manually connect or disconnect the MCPTools instance. This does not automatically refresh connections, you can use refresh_connection to do so.
See the AgentOS + MCPTools page for more details.
This is the recommended way to manage the connection lifecycle of the MCP server when using AgentOS.

Is there anything that we should have done so as to make it more production ready CODE - keeping my logic for the middlewares , extra routes prefixes (as needed for checking health states , that version of the app is important. ,)