Skip to main content
FastAPI logo

FastAPI

v1.13.0 Apache-2.0

z4j-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

bash
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

python
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.

bash
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

FastAPI lifespan integration
Async-native (arq / taskiq best fit)
get_runtime() exposes the running agent to application code
Works alongside Celery / RQ too
install_z4j() for apps that cannot use lifespan

Engine pairings

FastAPI works with every z4j engine

The framework adapter handles lifecycle and config. Any engine adapter slots in alongside.

Other frameworks

See also

Get started with z4j + FastAPI