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:
- the standard library, or
wactorz; - a package pip installs, listed in
requires={"packages": [...]}on the decorator (orREQUIRESon a class), which the node installs before it builds the agent.
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:
wactorz.core.integrations.langchain.CostCallback(me, prices={...})is a LangChain callback handler: pass it in a chain's or a graph'sconfig, and every model call is reported with its tokens. LangChain reports tokens, not money, sopricesmaps a model name to dollars per million input and output tokens; an unpriced model is counted at no cost.wactorz.core.integrations.ag2.record_reply(me, reply, prices={...})reads AG2's usage report for a reply, tokens by model, prices them and reports them.model_config(me)in the same module gives AG2's agents the model the system runs on. AG2 1.x,import ag2, plus AG2's extra for the provider (pip install 'ag2[anthropic]','ag2[openai]'), which carries that provider's SDK at the version AG2 asks for. A price table is keyed by model family and matches the resolved name a provider reports as a prefix.
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:
imu_anomaly/: a trained model watching IMU readings, as a script, a pipeline, a notebook and inside a FastAPI app.air_quality/: a model of each room's usual air per hour, an agent that asks a person about the rest and keeps the answers as labels, and a dashboard tab, as one installable package.household_energy/: one power meter, a classifier naming the appliance behind each run, a person asked whether it was right, and a dashboard tab with its own icon, as one installable package.llm_notes/: an agent that calls the system's language model throughme.llm, with the cost kept across restarts.yolo_watch/: a YOLO model as an agent, as a function answering snapshots on MQTT and as anActorreading a camera itself.langgraph_triage/: a LangGraph graph as an agent, several tickets in flight at once, with the model's spend on the dashboard.ag2_review/: an AG2 1.x writer–critic conversation as an agent, on the system's model.
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
- Streams stay where they are produced. An agent that watches a camera or
a microphone reads it on the machine the device is attached to, with
OpenCV, GStreamer, WebRTC or
sounddevice, and publishes decisions. MQTT carries events; a{"raw": bytes}payload is for a snapshot or a clip, not a feed. - Models live in files. Load
.pt,.onnx,.pklor anything else yourself, once, and keep the object on the actor.persist()is for what the agent learns or counts, in JSON-sized pieces. - State lives under
WACTORZ_STATE_DIR(default./state), one folder per agent, with the SQLite database beside them.
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.