FastAPI
v1.13.0 Apache-2.0z4j-fastapi ยท Upstream project
Lifespan-hook integration for async stacks.
FastAPI lifespan-aware. Most commonly paired with arq or taskiq (both async-native) but works with Celery or RQ when your sync stack calls for them. Pass your engine handle to z4j_lifespan(); get_runtime() exposes the running agent to application code.
- Latest
- v1.13.0
- Released
- 2026-10-19
- License
- Apache-2.0
Install
pip install z4j-fastapi Pick an engine
FastAPI + any task engine
Every extra pulls the engine adapter AND its companion scheduler in one shot, so a fresh install never needs a second command.
| Engine | Install command | Bundled scheduler |
|---|---|---|
| Celery | pip install z4j-fastapi[celery] | celery-beat |
| RQ | pip install z4j-fastapi[rq] | rq-scheduler |
| Dramatiq | pip install z4j-fastapi[dramatiq] | APScheduler |
| Huey | pip install z4j-fastapi[huey] | huey-periodic |
| arq recommended | pip install z4j-fastapi[arq] | arq-cron |
| TaskIQ | pip install z4j-fastapi[taskiq] | taskiq-scheduler |
| Every engine (CI / kitchen sink) |
pip install z4j-fastapi[all]
| all of the above |
pip install z4j-fastapi with no extra installs only the framework adapter. Pick an engine extra for the normal case.
Wire it in
from arq.connections import RedisSettings
from fastapi import FastAPI
from z4j_fastapi import z4j_lifespan
# Pass the engine handle so the web process registers the adapter
# (submit and cancel). Lifecycle events come from the arq worker,
# which needs its own hook: attach_to_worker_settings (see the arq docs).
app = FastAPI(
lifespan=z4j_lifespan(
arq_redis_settings=RedisSettings(),
arq_function_names=["my_task"],
),
) Verify
Confirm the agent reaches the brain
Run the doctor as the same user the service runs under. It checks the on-disk buffer path, DNS, TCP and TLS to the brain, and that the agent runtime starts locally (the Django doctor also lists the engines it detects); it exits 0 on all-green, 1 on any failure. It does not prove the WebSocket upgrade or that the brain accepts the token, so confirm the authenticated connection in the agent log and the dashboard.
python -m z4j_fastapi doctor
Catches the gunicorn-under-www-data silent startup failure (the agent auto-relocates the buffer to $TMPDIR/z4j-{uid} when $HOME is unwritable), DNS failures, and firewall or certificate problems on the path to the brain. It does not check the token or project id; a rejected token shows up in the agent log as a 4401 close. Add --no-websocket to skip the local runtime probe, --json for scripts. Reference.
What you get
FastAPI-specific features
Engine pairings
FastAPI works with every z4j engine
The framework adapter handles lifecycle and config. Any engine adapter slots in alongside.
Celery
The industry standard, covered end-to-end.
Learn more
RQ
Lightweight Redis queue, fully instrumented.
Learn more
Dramatiq
Middleware-driven Dramatiq observability.
Learn more
Huey
Lightweight Redis/SQLite queue, first-class.
Learn more
arq
Async Redis queue for FastAPI-era Python.
Learn more
taskiq
Broker-agnostic async task framework.
Learn moreOther frameworks