Quickstart - FastAPI

1. Install

pip install z4j-fastapi z4j-arq           # or z4j-taskiq, z4j-celery, ...

2. Mint an agent token

Dashboard → Agents → Mint token.

3. Attach to the lifespan

main.py

from contextlib import asynccontextmanager
from fastapi import FastAPI
from z4j_fastapi import Z4JAgent

@asynccontextmanager
async def lifespan(app: FastAPI):
    agent = Z4JAgent(
        brain_url=os.environ["Z4J_BRAIN_URL"],
        token=os.environ["Z4J_TOKEN"],
        project_id=os.environ.get("Z4J_PROJECT_ID", "default"),
    )
    async with agent:
        yield

app = FastAPI(lifespan=lifespan)

4. For arq / taskiq worker processes

The worker processes also need the agent. Add an agent inside the worker’s startup hook. See arq or taskiq for the exact pattern.

5. Verify

Run the doctor first — confirms the agent can reach the brain end-to-end and reports a specific failure if it can’t:

python -m z4j_fastapi doctor

Run as the same user the service runs under. All probes should be [OK].

Then boot your API. Dashboard → Agents - you should see the web process online. Boot your worker - you should see the worker online. Enqueue a task - it appears in Tasks within ~100ms.

Troubleshooting

See framework: FastAPI.