Quickstart - Bare Python

z4j-bare is the foundation package - every framework adapter depends on it. You can use it directly if you have no framework.

1. Install

pip install z4j-bare z4j-celery

2. Start the agent

worker.py

import asyncio
import os
from z4j_bare import Agent

async def main():
    agent = Agent(
        brain_url=os.environ["Z4J_BRAIN_URL"],
        token=os.environ["Z4J_TOKEN"],
        project_id=os.environ.get("Z4J_PROJECT_ID", "default"),
        agent_name=os.environ.get("HOSTNAME", "bare-worker"),
    )
    async with agent:
        # your worker runloop here
        await your_work()

asyncio.run(main())

3. What async with agent does

• Opens the WebSocket to the brain.
• Sends hello with engine/scheduler capabilities.
• Installs patches on the selected engine(s) to capture events.
• Starts a heartbeat loop.
• On exit, sends goodbye and closes cleanly.

4. Manual engine wiring (if you need it)

Auto-discovery usually works. If you need to register engines explicitly:

from z4j_bare import Agent, register_engine
from z4j_celery import CeleryAdapter

agent = Agent(...)
register_engine(agent, CeleryAdapter(app=my_celery_app))

Notes

• The agent runs on the asyncio event loop. In sync workers, wrap it in a background thread - see bare framework.
• Agent is safe to start/stop multiple times in tests.