Writing handlers

A handler is what a system node (the deterministic, non-LLM worker in a flow) runs when a matching event arrives, declared as YAML. The engine runs a handler’s parts in a fixed order — not the order you wrote them — and commits them all in one transaction, so a crash never leaves a half-applied change. The common path: That order is: acquire entity → guard → accumulate/compute → write and advance → emit → action. This page is the overview; each part below has its own page with the syntax and examples. For the conceptual model see System nodes and handlers; for the full step order and precedence see the execution model; for the exhaustive field list see Handler fields.

​

How data moves between steps

Two places hold data, and one rule governs what an agent can see:

• The entity is the durable store. Write to it with data_accumulation (the step that records fields on the entity; unrelated to accumulate); read it anywhere with entity.*. Entity fields persist across handlers, so a value written when the ticket was created is still readable when a later event arrives.
• The emitted payload is how a handler hands data to the next subscriber. You build it with emit.fields. It is neither the entity nor the triggering event: you populate it explicitly.
• An agent sees only the payload of the event delivered to it, never the entity directly. So that payload is the contract for what the agent can act on. If a resolver agent needs the ticket body, the event that reaches it must carry the body.

So a value flows like this: an event arrives, data_accumulation records what matters on the entity, and emit.fields reads from the entity to populate the next event.

​

What goes in a handler

A handler is written roughly in this order, and each part is its own page: