Why We Chose Python stdlib Over FastAPI for a Multi-Agent Server

Why We Chose Python stdlib Over FastAPI for a Multi-Agent Server

Bridge ACE's server handles 200+ API endpoints, WebSocket connections for real-time agent communication, and 16 background daemons. We built it with Python's standard library — no Flask, no FastAPI, no Django.

Here is why.

The Decision

When you build a multi-agent coordination server, you need:

• HTTP API for external clients (UI, CLI, integrations)
• WebSocket server for real-time agent push
• Background threads for health monitoring, auto-restart, context tracking
• Atomic file operations for state persistence
• No external dependencies that could break in production

FastAPI would give us automatic OpenAPI docs, dependency injection, and async request handling. But it would also give us:

• uvicorn/hypercorn dependency for WebSocket
• Pydantic v2 migration headaches
• An async event loop that complicates thread-based daemons
• A framework that owns the execution model

What stdlib Gives Us

http.server.HTTPServer — Threaded HTTP handler. Simple, predictable, no magic. Each request gets its own thread. Lock ordering is explicit.

websockets library — The one external dependency for the WebSocket server. Lightweight, well-tested, async-native but easy to run in a thread.

threading — 16 daemon threads for background tasks. No async/await complexity. Each daemon is a simple loop with a sleep interval.

tempfile + os.replace — Atomic writes for team.json and task state. No database. No ORM. File operations that survive crashes.

json — State persistence as JSON files. Human-readable, git-diffable, zero setup.

The Tradeoff

We lose:

• Automatic API documentation (we handle routing manually with path matching)
• Request validation (we validate manually)
• Middleware patterns (we implement cross-cutting concerns in the handler)

We gain:

• Zero framework dependency risk
• Full control over the execution model
• Simple deployment (Python 3.10 + pip install)
• Predictable threading behavior
• A server that starts in under 2 seconds

The Numbers

• server.py: 7,000+ lines
• bridge_mcp.py: 12,667 lines
• 200+ explicit path routes
• 37 handler modules
• 16 background daemons
• Startup time: <2 seconds
• Dependencies: minimal (websockets, httpx, a few others)

When To Use This Pattern

Use stdlib when:

• You need full control over threading and execution
• Your server has mixed concerns (HTTP + WebSocket + daemons)
• Deployment simplicity matters more than development speed
• You want zero framework lock-in

Use FastAPI when:

• You need automatic API docs
• Your team expects framework conventions
• You are building a pure REST API without background tasks

Open Source

The full server implementation is in the repo.

git clone https://github.com/Luanace-lab/bridge-ide.git

GitHub: github.com/Luanace-lab/bridge-ide