Starlette — The Little ASGI Framework That Shines

What it is

Starlette is a lightweight ASGI framework for building high-performance async web services in Python. It provides routing, middleware, WebSocket support, GraphQL, background tasks, and streaming responses. Most notably, Starlette is the foundation that FastAPI is built on top of, handling all the HTTP-level concerns while FastAPI adds data validation and OpenAPI generation.

Starlette targets Python developers who want async web capabilities without the overhead of a full framework. It is also relevant to anyone using FastAPI who wants to understand or extend the underlying request handling layer.

How it saves time or tokens

Starlette's minimal surface area means less boilerplate to write and maintain. A working API endpoint requires only a route function and a response object. The async-first design handles concurrent requests efficiently without thread pool management. For AI agent backends that need to handle streaming LLM responses, Starlette's native StreamingResponse maps directly to server-sent events without additional dependencies.

How to use

1. Install Starlette and an ASGI server:

pip install starlette uvicorn

1. Create a basic application:

from starlette.applications import Starlette
from starlette.routing import Route
from starlette.responses import JSONResponse
import uvicorn

async def list_items(request):
    return JSONResponse([{'name': 'item-1', 'status': 'active'}])

app = Starlette(routes=[Route('/items', list_items)])

if __name__ == '__main__':
    uvicorn.run(app, host='0.0.0.0', port=8000)

1. Run the server with python app.py and access http://localhost:8000/items.

Example

Streaming response for an AI agent backend:

from starlette.responses import StreamingResponse
import asyncio

async def stream_response(request):
    async def generate():
        for i in range(10):
            yield f'data: chunk {i}\n\n'
            await asyncio.sleep(0.1)
        yield 'data: [DONE]\n\n'

    return StreamingResponse(
        generate(),
        media_type='text/event-stream'
    )

This pattern is commonly used for streaming LLM completions to frontend clients via server-sent events.

Related on TokRepo

• AI Tools for API — API frameworks and tools for building AI service backends
• AI Tools for Coding — Development tools that complement web framework work

Common pitfalls

• Starlette requires an ASGI server like Uvicorn or Hypercorn. It does not include a built-in server, so forgetting to install one causes import errors at startup.
• WebSocket handlers must explicitly accept the connection before sending messages. Skipping await websocket.accept() causes silent connection drops.
• Middleware ordering matters. Authentication middleware must come before route-specific middleware to prevent unauthenticated access to protected endpoints.
• Always check the official documentation for the latest version-specific changes and migration guides before upgrading in production environments.
• For team deployments, establish clear guidelines on configuration and usage patterns to ensure consistency across developers.