ag-ui-protocol/ag-ui

[Bug]: ag-ui-langgraph __init__ eagerly imports fastapi, breaking middleware-only (non-web) installs

Open

#2,013 opened on Jun 22, 2026

View on GitHub
 (3 comments) (0 reactions) (0 assignees)TypeScript (1,262 forks)auto 404
Integrationbughelp wanted

Repository metrics

Stars
 (14,090 stars)
PR merge metrics
 (Avg merge 9d 15h) (97 merged PRs in 30d)

Description

Pre-flight Checklist

  • I have searched existing issues and this hasn't been reported yet.
  • I am using the latest version of AG-UI (ag-ui-langgraph 0.0.42, also reproduces on main).

Describe the Bug

fastapi is declared as an optional dependency in the ag-ui-langgraph pyproject.toml:

[project.optional-dependencies]
fastapi = ["fastapi>=0.115.12"]

…but the package's top-level __init__.py unconditionally imports the FastAPI endpoint module:

# ag_ui_langgraph/__init__.py
from .endpoint import add_langgraph_fastapi_endpoint

and endpoint.py imports FastAPI at module top:

# ag_ui_langgraph/endpoint.py
from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import StreamingResponse

Because Python evaluates a package's __init__.py before any submodule, any import from the package — including from ag_ui_langgraph.middlewares.state_streaming import StateStreamingMiddleware — fails on a default install (pip install ag-ui-langgraph, i.e. without the [fastapi] extra). The "optional" dependency is effectively mandatory for every consumer, so middleware-only / non-web consumers cannot import anything without pulling in fastapi/starlette/uvicorn.

Steps to Reproduce

python -m venv .venv && source .venv/bin/activate
pip install ag-ui-langgraph        # default install, NO [fastapi] extra
python -c "from ag_ui_langgraph.middlewares.state_streaming import StateStreamingMiddleware"

Expected Behavior

Middleware-only consumers (e.g. a LangGraph backend that is not a web server) should be able to import ag_ui_langgraph and its middleware/utils submodules without installing fastapi. FastAPI should only be required when actually using add_langgraph_fastapi_endpoint, consistent with it being an optional extra.

Environment

ag-ui-langgraph 0.0.42 (also reproduces on main)
Python 3.10–3.12
fastapi NOT installed (default install, no [fastapi] extra)

Logs & Errors

ModuleNotFoundError: No module named 'fastapi'
  File ".../ag_ui_langgraph/__init__.py", in <module>
    from .endpoint import add_langgraph_fastapi_endpoint
  File ".../ag_ui_langgraph/endpoint.py", line 1, in <module>
    from fastapi import FastAPI, HTTPException, Request

Additional Context — suggested fixes (any one resolves it)

  1. Lazy export (smallest change): drop the eager from .endpoint import ... from __init__.py and expose it via module-level __getattr__ (PEP 562) so add_langgraph_fastapi_endpoint only triggers the fastapi import when accessed.
  2. Guarded import: wrap the endpoint import in try/except ImportError in __init__.py and raise a clear "install ag-ui-langgraph[fastapi]" message only on use.
  3. Keep endpoint out of the default surface: have consumers do from ag_ui_langgraph.endpoint import add_langgraph_fastapi_endpoint and stop re-exporting it from the top-level __init__.py.

Option 1 (__getattr__) preserves the current public API while keeping fastapi truly optional.

Workaround today: consumers must either install the unwanted [fastapi] extra (pulls in fastapi/starlette/uvicorn) or inline the middleware. We currently inline StateStreamingMiddleware to avoid bolting a web stack onto a non-web backend.

Happy to open a PR for option 1 if a maintainer can confirm the preferred approach.

Contributor guide