Using Wactorz as a library

Wactorz is an application, the wactorz command with its dashboard, planner and catalogue, and it is a library: the supervision, persistence, MQTT wiring and dashboard underneath, for agents you write yourself. This guide is the library side, from one function to a declared pipeline, with no Home Assistant and no language model required.

Everything here is in examples/imu_anomaly/, runnable end to end.

Install

pip install wactorz
docker compose up -d mosquitto     # or any MQTT broker on localhost:1883

One function is an agent

import wactorz

@wactorz.agent(
    name="imu-anomaly",
    subscribes="sensors/imu/#",
    publishes="anomalies/imu",
    description="Flags IMU readings the trained model calls abnormal.",
    requires={"ram_mb": 128, "packages": ["numpy"]},
)
def detect(reading: dict) -> dict | None:
    score = MODEL.score(reading)
    return {"score": score, "reading": reading} if score > 4.0 else None

detect is still a function: call it in a test, import it elsewhere. As an agent it is called once per message on sensors/imu/# with the decoded payload, and once per task sent to it by chat or by another agent. What it returns is published to anomalies/imu; None publishes nothing. A task's payload is untrusted input: on a node, any node on the broker may send one by name, so check what the function acts on. A plain function runs on a worker thread, so a slow model never holds the event loop every other agent shares; a coroutine function runs on the loop.

A function that wants the actor takes it as a second parameter, for state, options and publishing elsewhere:

@wactorz.agent(subscribes="sensors/imu/#", publishes="anomalies/imu")
def detect(reading: dict, me: wactorz.FunctionAgent) -> dict | None:
    model = me.options.get("_model")           # loaded once, kept on the actor
    if model is None:
        model = load(me.options.get("model", "imu.onnx"))
        me.options["_model"] = model
    score = model.score(reading)
    if score < 4.0:
        return None
    me.persist("anomalies_total", int(me.recall("anomalies_total", 0)) + 1)
    return {"score": score, "reading": reading}

persist and recall keep small values across restarts and migrations: counters, thresholds, calibration. Keep the model itself in a file and load it; do not persist the model object.

Start it

From a script, the dashboard on, nothing else:

wactorz.run(agents=[detect], minimal=True)        # http://localhost:8888/

minimal=True starts the monitor, the dashboard and your agents: no orchestrator, no catalogue, no installer, so no model, no API key and no provider SDK; a plain pip install wactorz is enough. A model is built under it only when one is named (llm="ollama"). Leave it out to run beside the full system, where chat can ask your agent questions (@imu-anomaly {"ax": 9, "ay": 0, "az": 1}) and the planner can wire new agents to what it publishes.

Inside a program that already has an event loop, a notebook, a web framework, a ROS node, await serve instead; the host keeps its signals, and cancelling the task stops the system cleanly:

# Jupyter: `serve` returns when the system stops, so it runs as a task, and the
# notebook's own server is on 8888, the dashboard's default, so pick another port.
system_task = asyncio.create_task(wactorz.serve(agents=[detect], minimal=True, monitor_port=8890))
await asyncio.sleep(4)  # the broker connection, the dashboard and the agent come up
actor = wactorz.system().registry.find_by_name("imu-anomaly")
...
system_task.cancel()  # to stop; the actors are stopped on the way out
# FastAPI
from contextlib import asynccontextmanager, suppress

@asynccontextmanager
async def lifespan(app: FastAPI):
    task = asyncio.create_task(wactorz.serve(agents=[detect], minimal=True))
    yield
    task.cancel()
    with suppress(asyncio.CancelledError):
        await task  # the system is stopped, and its state written, before the host exits

app = FastAPI(lifespan=lifespan)

run() is asyncio.run(serve(...)) with signal handling on; the two take the same arguments: web, minimal, monitor_port, mqtt_broker, mqtt_port, llm, state_dir. The dashboard's default port is 8888, which Jupyter also uses; inside a notebook, or beside any other server on that port, pass monitor_port or set MONITOR_PORT.

serve behaves as a library call inside someone else's program: it leaves the host's logging configuration alone (configure_logging=True asks for the command's console and file handlers, which run() does; a host that has configured no logging at all still sees warnings and errors on stderr, as it would without Wactorz), state_dir is set for the run rather than written to the environment, and a configuration that cannot be started, an exposed bind address with no API key, a chat interface whose token is missing, a provider whose SDK is not installed, raises wactorz.StartupError with the reason instead of exiting the process, and leaves the process as it found it: no thread of ours left watching the loop, no handler of ours on the root logger. The host's own tasks, started before serve or while it runs, are left alone at shutdown: Wactorz marks the tasks it creates and stops only those. Cancelling the serve task raises CancelledError once the system has stopped, so a timeout or a task group around it sees the cancellation as one. wactorz.system() is the running ActorSystem, with the registry your actors are in, and None outside a run.

On Windows the loop matters: the broker client needs a selector loop, and a proactor loop, which uvicorn builds there by default, cannot serve it. serve refuses to start on one with a StartupError that says what to do: start uvicorn with --loop asyncio:SelectorEventLoop, or set asyncio.WindowsSelectorEventLoopPolicy() before the loop is made. Jupyter's kernel already uses the selector loop.

Or register it, and start wactorz as usual

For a deployment that runs the wactorz command, name the agent instead of writing a script:

How Where For
WACTORZ_AGENTS=mypkg.agents:detect,mypkg.agents:Sink the environment a configured deployment
[project.entry-points."wactorz.agents"] in pyproject.toml your package, named in WACTORZ_EXTENSIONS an installed package
[project.entry-points."wactorz.extensions"] in pyproject.toml your package, named in WACTORZ_EXTENSIONS a server extension (routes, /api/config values) loaded like those in wactorz/ext/; see the extensions guide
wactorz.run(agents=[...]) or serve(...) a script development

A package's entry points load only once its distribution is in WACTORZ_EXTENSIONS (* for all); installing it is not enough. The target must be importable from where wactorz starts: a package that is installed, or a folder on PYTHONPATH. One that is not is reported at startup and left out. A registered agent is supervised, listed by @catalog list, restored after a restart, and may be spawned under another name with a type: "module" spawn config; only registered targets are accepted there, because a spawn config can be written by the model.

On a node, and moving between machines

A registered agent can run on a node as well as on main, and move between the two with /migrate. Main sends its code with it, so nothing has to be copied to the node by hand, as long as the agent keeps to one rule.

An agent's own code lives in its own folder. What main sends is the folder its module is in -- every .py file in it and in the folders under it -- or, for a module inside a package, the package. Everything else the agent imports must be one of:

Code of your own from anywhere else -- a mylab package in another folder, on PYTHONPATH or installed with pip install -e -- would not be on the node, so the move is refused before anything stops, naming the import: move that code into the agent's folder, or publish it and list it in requires. Only .py files go, up to 1 MiB of them; a model goes as one of the agent's models (models=, above), and a folder that is hidden, a cache or a virtual environment is skipped. Two agents on one node cannot both have a module of the same name, so give an agent's module a name of its own (imu_detector.py rather than agent.py) when several will share a node.

A node that has the agent installed itself -- the package in its environment and the target in WACTORZ_AGENTS there, or a wactorz.agents entry point of a package in the node's WACTORZ_EXTENSIONS -- builds it from that instead, and is sent no code; that is how to run code that cannot follow the rule. A node from before this release takes no code from main, and is refused the move until it is deployed again.

On the node the agent subscribes, publishes and persists as it does on main, answers tasks sent to it by name, and keeps its state under the node's state directory. It has no model there: me.llm is None, since a node makes no model calls.

/migrate imu-anomaly rpi-kitchen      # its code, packages and models go with it
/migrate imu-anomaly local            # and back, with its state

What it persisted goes with it both ways, blobs included: a model, an array or bytes an agent persists is kept as a file of its own beside its state and travels beside the snapshot, so a detector that keeps its model with persist() arrives with it. A pickled model, or a torch module, loads by running code: main sends such a value to a node but does not take one from a node, so an agent that must come home keeps a state_dict() or plain bytes instead. On a restart of main, an agent the spawn registry places on a node is not started on main as well.

An Actor subclass

For an agent with its own lifecycle, subclass Actor. The base class subscribes, keeps rolling windows and publishes for you, on one broker connection per actor that closes when the actor stops:

from wactorz import Actor, Message, MessageType

class PumpWatch(Actor):
    DESCRIPTION = "Watches the pump's flow."
    SUBSCRIBES = ["sensors/pump/#"]
    PUBLISHES = ["alerts/pump"]

    async def on_start(self) -> None:
        self.subscribe("sensors/pump/#", self.on_reading)        # plain or async callback
        self.flow = self.window("sensors/pump/flow", seconds=60)  # rolling window

    async def on_reading(self, payload: dict) -> None:
        if self.flow.falling(threshold=2.0):
            await self.publish("alerts/pump", {"flow": payload})

    async def handle_message(self, msg: Message) -> None:
        if msg.type != MessageType.TASK:
            return
        result = {"flow_mean": self.flow.mean("value")}
        if isinstance(msg.payload, dict) and "_task_id" in msg.payload:
            result["_task_id"] = msg.payload["_task_id"]
        await self.send(msg.reply_to or msg.sender_id, MessageType.RESULT, result)

DESCRIPTION, CAPABILITIES, REQUIRES, SUBSCRIBES, PUBLISHES, INPUT_SCHEMA and OUTPUT_SCHEMA on the class become the catalogue entry and the wiring a pipeline checks against; AGENT_NAME names it (default PumpWatch → pump-watch); AUTOSTART = False keeps it in the catalogue until asked for. A subclass whose constructor names llm_provider (its own, or one it hands **kwargs on to) is given the system's model; spawn options reach a constructor that names them or takes **kwargs.

A message on a subscribed topic arrives decoded: a dict or list when it was JSON, {"raw": text} for text, {"raw": bytes} for anything else, such as a camera frame. Messages on one topic are handled one at a time, in order, unless the subscription says otherwise (below).

More than one at a time

By default an agent handles one message of a topic at a time, in order, and one task at a time, so a function that keeps state between calls is never run against itself. That is right for a sensor stream and wrong for a function that waits rather than computes: a model call, a training job, a graph with three model calls in it, where a twenty-second step queues every message behind it.

@wactorz.agent(subscribes="tickets/new", publishes="tickets/triaged", concurrency=4)
async def triage(ticket: dict, me: wactorz.FunctionAgent) -> dict:
    return await GRAPH.ainvoke({"ticket": ticket})

class Trainer(Actor):
    async def on_start(self) -> None:
        self.subscribe("mlops/candidates", self.train, concurrency=2)

concurrency=N runs up to N messages of the topic, and N tasks, at once. Order within the topic is then not kept, and the function runs against itself, so what it shares between calls must cope with that; a model loaded once and read by every call is fine, a counter updated with persist is a race. A plain def under concurrency runs on that many worker threads.

Models

A model kept with wactorz-artifacts (see the deployment guide) is named by the agent that loads it, under a key of its own:

@wactorz.agent(subscribes="sensors/imu/#", models={"model": "imu-detector:3"})
async def detect(reading: dict, me: wactorz.FunctionAgent) -> dict | None:
    model = await me.load_model("model")  # {"mean": array, "inverse_covariance": array}
    ...

class Watcher(wactorz.Actor):
    MODELS = {"detector": "yolo-onnx"}  # the newest, pinned when it starts

    async def on_start(self) -> None:
        self.session = onnxruntime.InferenceSession(self.artifact_path("detector"))

Each is found before on_start, and an agent whose model is not stored does not start. artifact_path(key) is where the file is on this machine (for a directory artifact, the directory it unpacks to), for whatever library reads it. await load_model(key) reads the formats that need only a well-known library, once, off the event loop, the way that runs no code from the file:

Format load_model gives
npz a dict of numpy arrays (allow_pickle=False)
npy the numpy array (allow_pickle=False)
safetensors a dict of numpy arrays, through safetensors.numpy
state_dict what the checkpoint holds, through torch.load(weights_only=True) on the CPU: tensors, numbers and containers, and numeric numpy arrays beside them
onnx an onnxruntime.InferenceSession
raw the bytes

A pickle, a joblib file and a whole torch module run code when they load, so load_model refuses them unless given allow_code=True. GGUF, TFLite, skops and directories are opened through artifact_path by the library that reads them. me.artifacts lists each model with its name, version, format and path, and its metadata: what was said of the version when it was added (--meta k_sigma=5), so a threshold or a calibration constant can live with the version it belongs to. A version's metadata does not change once stored; a different threshold is a new version, which a trial can then compare. On a shadow pass, me.artifacts is the version on trial's, metadata included.

Training a version

A version can be trained inside the loop rather than by a script you run: the trainer library agent, or wactorz-train from a terminal, runs a recipe you write on a window of recorded readings (docs/design/train-step.md). A recipe is a module, named by its importable name or its .py file (which may import the modules beside it), with two functions and an optional third:

# examples/imu_anomaly/recipe.py
import numpy as np


def train(frame, settings):
    """Fit on an Arrow table from the loader; settings is what the run was given."""
    rows = np.column_stack([frame.column(axis).to_pylist() for axis in ("ax", "ay", "az")])
    return fit(rows)                       # a mapping of numpy arrays


def score(model, frame):
    """Figures on rows the model was not fitted on: a mapping of numbers, each named."""
    ...
    return {"caught": caught, "false_alarms": false_alarms}


def save(model, directory):               # optional: without it, arrays go as model.npz
    path = directory / "model.npz"
    np.savez(path, **model)
    return path

The frame carries a label column, the effective label at each row's event time, when the version compared against says what it is judged on, or when the run asks for it. Spawn the agent with the recipe, the model's name, the source and what a move depends on:

@catalog spawn trainer {"recipe": "examples/imu_anomaly/recipe.py", "model": "imu-detector",
                        "source": "sensors/imu", "metric": "caught", "margin": 0.02}

A task to it runs one training: {"since": ..., "until": ..., "split": {"kind": "time_split", "at": ...}, "settings": {...}, "reason": "regime change at 14:02"}, from chat, from a rule's task action or from another agent. What the task does not say takes the agent's options; the default window is the last week the source has seen, ending at its newest recorded reading held back by lateness_s (a minute), with its last fifth held out, and a split is holdout, time_split, rolling_origin or leave_k_out, as the loader makes them. The fit runs in a child process with the agent's timeout_s and memory_mb. The version is stored with the recipe's hash, the seed, the settings, the window, the split's manifest and the figures, and the pointer the agent is for (pointer, shadow unless said) moves only when the new version beats the one served by the margin on the same held-out rows, with the figures in the move's reason. {"action": "status"} says what is running or what the last run came to. From a terminal:

wactorz-train check examples/imu_anomaly/recipe.py
wactorz-train run examples/imu_anomaly/recipe.py --model imu-detector --source sensors/imu \
    --metric caught --margin 0.02 --split time:1760050920 --reason "regime change at 14:02"

Each run is an action in the provenance graph and each version a model node, with produced, trained and led_to edges, so GET /api/labels and the model's history say what a version learned from and why it was tried. A task that names an observation, the id of a drift alarm, has its run joined led_to from it.

Watching for drift

The drift library agent watches one model's recorded readings and says when they no longer look like what the served version learned from (docs/design/drift.md). Spawn it with the model, and the recorded source of its inputs when the version does not say what it read:

@catalog spawn drift {"model": "imu-detector", "source": "sensors/imu", "scores": "anomalies/imu"}

Every check_s seconds (WACTORZ_DRIFT_CHECK_S, ten minutes unless set) it reads two windows through the loader, in event time: the current one, the last window_s (a day) ending at the source's own now, its newest recorded reading held back by lateness_s (a minute), so a replayed day is checked at the replay's own moments; and the reference, the window the served version was trained on when the trainer made it, else reference as spawned, else the window of the same length before the current one. Over them it runs, on every numeric column (or columns), PSI, which alarms at 0.2, and the two-sample KS test, which alarms at D >= 0.1 with p < 0.05; and, when scores names a recorded source of the model's scores (its score_column, score unless said), the same on the scores and ADWIN over the current window, which says the moment the scores changed. Each test runs only when both windows hold min_rows (100). The thresholds are spawn options with these names.

A test over its threshold on a column raises an episode, once: an observation node about the model, a line on the feed, a message on models/<name>/drift with the observation's id, and the gauges wactorz_model_drift{model,test,column} and wactorz_model_drift_alarm. The episode stays raised, the gauges following, until a check finds the statistic back under its threshold; a promotion moves the reference to the new version and starts afresh; after a restart the episodes of the version served are read back from the graph. GET /api/models/{name}/drift lists the alarms, and {"action": "check"} as a task runs a check now.

What follows from an alarm is a rule's, so the loop closes without a person: a rule on the topic sends the trainer a task with the window and split it names and the alarm's observation, and the policy decides the promotion.

{"type": "rule", "name": "imu-retrain",
 "triggers": ["models/imu-detector/drift"],
 "conditions": [{"field": "test", "op": "in", "value": ["psi", "adwin"]}],
 "actions": [{"type": "task", "agent": "trainer",
              "payload": {"split": {"kind": "time_split", "at": "{at}"},
                          "observation": "{observation}",
                          "reason": "drift: {test} on {column} ({statistic})"}}],
 "cooldown_seconds": 86400}

A rule's placeholder that is a value on its own, "at": "{at}", is the trigger's value as it is, a number staying a number, and placeholders are filled inside nested objects, so the split above reaches the trainer as it reads it. The cooldown makes however many columns alarm at once one retrain; it counts the alarms' own time, so a replayed day is a day.

Your own files

me.state_dir (or self.state_dir in a subclass) is the agent's own directory under the state directory: for model weights, a checkpoint store, a local experiment log, anything too large or too un-JSON for persist(). It exists from construction, survives restarts, and is removed with the agent on a delete. What moves with a migration to another node is the persisted state, not these files; an agent that needs a file on another machine ships it, and a model it loads belongs among its models (above).

A value the agent learns -- bytes, a numpy array, a torch tensor or state_dict(), a scikit-learn-family model -- is better persisted than written here: persist() keeps each as a file of its own beside the state, written when its key is persisted rather than with every counter, and a migration carries it.

checkpointer = SqliteSaver.from_conn_string(str(me.state_dir / "graph.sqlite"))

Spend made elsewhere

A call through me.llm is counted as it returns: tokens and cost on the agent's card, and against the cost limit, with nothing to write in the function. A model called another way, through LangChain, AG2 or an SDK directly, is invisible until the agent says what it spent:

me.record_llm_cost(0.0012, input_tokens=300, output_tokens=40, model="gpt-4o-mini")

That joins the agent's card and the process-wide total the cost limit is checked against. Two helpers do it for the common cases:

LangGraph, LangChain and AG2

Wactorz does not compete with them. LangGraph and AG2 decide how an agent thinks: the graph, the prompts, the conversation. Wactorz keeps that running, wired to topics and events, restarted when it crashes, saved across restarts and visible on a dashboard, which is what a graph you call and a chat you start do not have on their own. An async function that invokes the graph is the whole integration:

@wactorz.agent(subscribes="tickets/new", publishes="tickets/triaged",
               requires={"packages": ["langgraph"]}, concurrency=4)
async def triage(ticket: dict, me: wactorz.FunctionAgent) -> dict:
    result = await GRAPH.ainvoke({"ticket": ticket}, config={"callbacks": [CostCallback(me)]})
    return result["decision"]

The graph's nodes can call the system's model through me.llm, so its spend is counted and capped like every other call, or a LangChain model with the callback above. examples/langgraph_triage/ and examples/ag2_review/ are the two, runnable; pip install 'wactorz[langgraph]' and 'wactorz[ag2]' bring the libraries. Ray is the same shape: an always-on agent at the edge awaits a Ray task's handle and publishes the result. Keep Ray's actors and Wactorz's in separate roles, compute you call and the control layer that calls it, rather than merging the two actor models.

A pipeline

Steps that work together are declared together. Each step is still an agent with its own card; the pipeline groups them, adds a schedule and rules, and is recorded beside the planner's pipelines so /rules lists it:

import wactorz
from wactorz import RuleAction, RuleCondition, RuleConfig

@wactorz.agent(subscribes="anomalies/imu")
async def notify(anomaly: dict, me: wactorz.FunctionAgent) -> None:
    await me.notify_user(f"IMU anomaly, score {anomaly['score']}")

@wactorz.agent(subscribes="pipelines/imu-watch/tick", publishes="reports/imu")
def report(tick: dict, me: wactorz.FunctionAgent) -> dict:
    return {"total": int(me.recall("anomalies_total", 0))}

alert = RuleConfig(
    triggers=("anomalies/imu",),
    conditions=(RuleCondition("score", "gt", 20),),
    actions=(RuleAction("publish", topic="alerts/imu", payload={"level": "high"}),),
    cooldown_seconds=30,
)

watch = wactorz.pipeline(
    "imu-watch",
    steps=[detect, notify, report],
    schedule={"type": "interval", "seconds": 300},
    rules=[alert],
)

The schedule becomes a scheduled agent ticking pipelines/imu-watch/tick, which report listens to. The rule becomes a rule agent: when a message on anomalies/imu has score above 20, it publishes to alerts/imu, at most every thirty seconds. Rules are the typed dataclasses above or the equivalent dicts, which are the spelling chat and JSON use:

rules=[{"triggers": ["anomalies/imu"],
        "conditions": [{"field": "score", "op": "gt", "value": 20}],
        "actions": [{"type": "publish", "topic": "alerts/imu", "payload": {"level": "high"}}],
        "cooldown_seconds": 30}]

Actions are publish, task (sent to an agent by name), webhook, ask_operator (a question to the person, with options, whose pick is published when it comes; see Asking and waiting in the interfaces guide) and label (a record that a source was doing something from the trigger's time on). Conditions take eq, ne, gt, gte, lt, lte, in, contains, exists, absent, with dotted fields such as reading.ax; an action's payload may name trigger fields in braces and carries the trigger under trigger.

Wiring is checked when the pipeline is declared: a step or rule listening on a topic nothing in the pipeline publishes, and not named in inputs, raises ValueError before anything starts. The first step may listen to the outside world without saying so. A pipeline declared at module level is found through WACTORZ_PIPELINES=mypkg.flows:watch, a wactorz.pipelines entry point (of a package named in WACTORZ_EXTENSIONS), or wactorz.run(pipelines_=[watch]).

From chat

A registered agent is a building block for main and the planner, with nothing more to declare than the decorator already says.

Ask it directly. In the dashboard chat, the REST interface or the CLI, address it by name with a JSON object matching its input schema, and the function's return value is the reply:

@imu-anomaly {"ax": 9, "ay": 0, "az": 1}
→ {"score": 12.4, "reading": {"ax": 9, "ay": 0, "az": 1}}

Plain text after the name travels as {"text": "..."}, for an agent that reads natural language.

Let main start it. Main's system prompt lists the registered agents that are not running, each with the one spawn config that starts it ("type": "module" and its registered target), so "start the IMU detector" is a spawn of yours rather than freshly written code. Registered targets only: a spawn config can be model-written, and type: "module" refuses anything not in the registry.

Let the planner use it. When the planner designs a pipeline, its prompt carries a registered agents section: name, description, the topics each listens to and writes to, its schemas, whether it is running, and the same spawn config. The rules say to prefer one of yours over a dynamic agent that does the same, to subscribe to what it publishes when it runs, and to spawn it by that exact target when it does not. So "alert me when the IMU detector scores above 20" proposes your detector as the first step, and a notifier listening on anomalies/imu after it.

To see all of this with a real agent, run the IMU example with python run.py --with-main and follow Ask it from chat in examples/imu_anomaly/README.md.

Asking an agent

An agent that needs another agent's answer, and a program that needs one from the running system, use the same call:

# inside an agent: the actor is the second parameter
@wactorz.agent(name="relay")
async def relay(payload: dict, me: wactorz.FunctionAgent) -> dict:
    score = await me.ask("imu-anomaly", {"ax": 9, "ay": 0, "az": 1})
    return {"score": score["score"]}

# beside the system: a notebook cell, a web handler, a test
score = await wactorz.ask("imu-anomaly", {"ax": 9, "ay": 0, "az": 1}, timeout=30)

The request goes to the agent as a task, the way chat or a pipeline step would send it, and the reply is what the agent answered: a function's return value, with a plain value wrapped as {"result": ...}. Three things go wrong loudly rather than quietly. No agent of that name is running: LookupError. The agent answered with an error, which is what a function that raised reports: RuntimeError carrying the message, a wactorz.core.actor.ReplyError whose reply holds the agent's whole answer. No reply within timeout seconds, 60 by default: asyncio.TimeoutError. In every case nothing is left waiting.

wactorz.ask needs a running system, from run() or serve(); it raises RuntimeError otherwise. Its reply address is a slot of the registry rather than an actor, so nothing is registered, listed or supervised on the caller's behalf.

Your own orchestrator

What answers a chat message, in the dashboard, the REST interface, the terminal, Discord, Telegram or WhatsApp, is an orchestrator. Main, the model-driven one, is the default. Without a model, in the minimal profile, a model-free one answers. And a deployment can supply its own: a LangGraph graph, a rule engine, anything that implements three methods.

from collections.abc import AsyncIterator

import wactorz


class Rules:
    async def handle_turn(self, text: str, *, channel: str, user: str | None = None) -> str:
        if text.startswith("score "):
            ax, ay, az = (float(v) for v in text[6:].split())
            verdict = await wactorz.ask("imu-anomaly", {"ax": ax, "ay": ay, "az": az})
            return f"score {verdict['score']}"
        return "Say: score <ax> <ay> <az>"

    async def handle_turn_stream(
        self, text: str, *, channel: str, user: str | None = None, attachments=None
    ) -> AsyncIterator[str]:
        yield await self.handle_turn(text, channel=channel, user=user)

    def commands(self) -> frozenset[str]:
        return frozenset()


wactorz.run(agents=[detect], minimal=True, orchestrator=Rules())

No base class: wactorz.Orchestrator is a protocol, and a class with these three methods satisfies it. handle_turn answers a message in full; handle_turn_stream answers it in pieces, for the surfaces that show words as they arrive, and yields the whole answer once when there is nothing to stream; commands names the slash commands the orchestrator answers, by first word (/help), so a surface can say "unknown command" for the rest instead of handing it over.

An orchestrator may also have a command_forms() method, returning a list of wactorz.orchestration.Form(usage, summary): each way to type one of its commands, as Form("/report <day>", "the readings for one day"). The dashboard's chat box offers them as a person types /. Without it the dashboard offers each command by its name alone.

The channel. Every call says where the message came from: "dashboard", "cli" and "rest" are the operator's own surfaces; "social" is Discord, Telegram or WhatsApp, a public endpoint that anyone who finds it can talk to, and user is the sender's id there. Main answers a social message through its restricted path (conversation and device control, no spawning, deleting or code) and treats any channel it does not know as social, which is the safe default; an orchestrator of your own should draw the same line.

What stays with the agents and with main. Naming an agent, @imu-anomaly {"ax": 9, "ay": 0, "az": 1}, reaches that agent directly, whichever orchestrator is installed, and a task sent to one on a node travels as before. /deploy, /migrate and /nodes are main's, since the nodes are reached through it; in a profile without main they say so.

Choosing one. From a script, run(orchestrator=...) or serve(orchestrator=...): an orchestrator object, or a class or factory that is called with the actor registry, since most orchestrators need it to reach the agents. From a deployment, WACTORZ_ORCHESTRATOR=package.module:attr, loaded the way a WACTORZ_AGENTS entry is; the target may be any of the three. Either wins over main and over the model-free one. A target that cannot be imported, or is not an orchestrator, refuses to start with the target in the message, since answering with main instead would be a silent substitution.

Without a model. In the minimal profile wactorz.DirectOrchestrator answers: @name {json} sends the JSON to that agent as its task and shows the reply, @name words sends {"text": "words"}, bare text is answered with the running agents and how to address one, and /agents, /topics, /nodes and /help are answered from the registry. The IMU example's README walks through it. wactorz.MainOrchestrator is main behind the same seam, for a program that wants to wrap or delegate to it.

Profiles

Without Home Assistant configured (HA_URL and HA_TOKEN) its agents do not start, and main and the planner are not told about it either: their prompts are assembled from a core plus what each configured integration adds, so an assistant for your agents never offers to dim the lights (see Prompt fragments). WACTORZ_HA_AGENTS=on|off decides outright. wactorz --minimal, WACTORZ_MINIMAL=1 or minimal=True starts the monitor, the dashboard and your agents only. The minimal profile runs no planner, no generated code and no runtime package install, which is the reproducible mode a pinned environment wants. Its dashboard chat still reaches your agents, through the model-free orchestrator described above.

Examples

examples/ in the repository holds complete programs, each with a README:

Testing

A decorated function is tested as a function. The actor around it is built without a broker and exercised directly:

import wactorz

def test_a_jolt_is_flagged(tmp_path):
    actor = wactorz.spec_of(detect).build(persistence_dir=str(tmp_path))
    assert detect({"ax": 9.0, "ay": -7.5, "az": 1.0}, actor)["score"] > 4
    assert detect({"ax": 0.1, "ay": 0.0, "az": 1.0}, actor) is None

actor.call(payload) runs it the way a message would, on a thread for a plain function; actor.handle_message(...) answers a task. Nothing connects until on_start. spec_of is the AgentSpec the decorator recorded: name, subscribes, publishes, options, and build() for the actor.

Where things go

Stable API

What this guide uses is the surface you can rely on:

Name Role
wactorz.agent declare a function as an agent
wactorz.pipeline declare steps, a schedule and rules together
wactorz.run, wactorz.serve start the system from a script, or on a running loop
wactorz.system the running ActorSystem (registry, supervisor), None outside a run
wactorz.ask, Actor.ask send an agent a task and wait for its reply, from host code or from another agent
wactorz.Orchestrator what answers chat: handle_turn, handle_turn_stream, commands, with the channel named on every call
orchestrator= on wactorz.run and wactorz.serve your own orchestrator, an object or a class or factory called with the registry
wactorz.DirectOrchestrator, wactorz.MainOrchestrator the model-free orchestrator of the minimal profile, and main behind the same seam
wactorz.spec_of the AgentSpec behind a decorated function, with build() for tests
wactorz.StartupError what serve and run raise for a configuration that cannot start
wactorz.Actor with subscribe, window, publish, persist, recall, send, notify_user, on_start, on_stop, handle_message, state_dir, record_llm_cost the base class
notify_user(text, options=[...], channel=..., user=...) and agents/<id>/answer a message to the person on a chat channel, with a choice; the pick comes back on the agent's topic (see Messages from an agent in the interfaces guide)
ask_operator(text, options=[...], channel=..., user=..., timeout=..., label=..., context=...), wait_for_answer, open_questions, on_operator_answer the same, waiting for the pick; a question outlives a restart, and with label= its answer becomes a label
label(source, value, start=..., end=...) a label written as the agent's own, on main (see Answers that become labels in the interfaces guide)
models= on wactorz.agent, MODELS on an Actor, with artifact_path, load_model and artifacts the models an agent loads
concurrency= on wactorz.agent and Actor.subscribe messages and tasks at once
wactorz.core.integrations.langchain.CostCallback, wactorz.core.integrations.ag2.model_config and record_reply LangChain and AG2 beside the system
wactorz.FunctionAgent the actor behind a decorated function: call, options, log
wactorz.RuleConfig, RuleCondition, RuleAction, wactorz.RuleAgent typed rules
wactorz.Message, MessageType what handle_message receives
WACTORZ_AGENTS, WACTORZ_PIPELINES, WACTORZ_MINIMAL, WACTORZ_HA_AGENTS, WACTORZ_ORCHESTRATOR the settings above

Other names the package exports, the built-in agents among them, are the application's own and may change between releases.