Quickstart - Flask

1. Install

pip install z4j-flask z4j-rq z4j-rqscheduler
# or: pip install z4j-flask z4j-celery z4j-celerybeat

2. Mint an agent token

From the brain dashboard → Agents → Mint token.

3. Initialize in app factory

app.py

from flask import Flask
from z4j_flask import Z4J

def create_app():
    app = Flask(__name__)
    app.config.from_object("myapp.config.Config")

    Z4J(app, {
        "brain_url": app.config["Z4J_BRAIN_URL"],
        "token": app.config["Z4J_TOKEN"],
        "project_id": app.config.get("Z4J_PROJECT_ID", "default"),
    })

    return app

Z4J(app, ...) registers app teardown hooks and starts the agent’s background WebSocket task on first request.

4. Verify

Boot Flask + your RQ worker. Both processes register as agents (web + worker). In the dashboard you should see two agents.

Multiple processes

Each gunicorn / uwsgi worker is a separate process and registers as a separate agent. This is normal - the dashboard deduplicates at the project level for display. Set agent_name to include the host to keep them distinguishable:

import socket
Z4J(app, {
    ...,
    "agent_name": f"web-{socket.gethostname()}-{os.getpid()}",
})

Troubleshooting

See framework: Flask for deeper reference.