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

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.