ag-ui-protocol/ag-ui

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

オープン

#2,013 opened on 2026/06/22

 (3 件のコメント) (0 件のリアクション) (0 人の担当者)TypeScript (1,262 件のフォーク)auto 404
Integrationbughelp wanted

Repository metrics

Stars
 (14,090 個のスター)
PR merge metrics
 (平均マージ 9d 15h) (30d で 97 merged PRs)

説明

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.

コントリビューターガイド