Conversation Routing¶
How topics, conversations, stages, edges, and goals work together to create chatbots that flow naturally between modes.
The hierarchy¶
Agent
└─ Topic (optional) ← groups related conversations
└─ Conversation ← a coherent flow with a goal
└─ Stage ← a focused step with a prompt + extraction
Topics group conversations that share a broad goal. A yoga studio bot might have topics "Class schedule", "Membership", and "General help." Topics are optional — simple agents skip them.
Conversations are the core unit. Each has a goal ("help the user find a mentor"), a sequence of stages, and routing metadata that helps the system match user messages to the right conversation.
Stages are steps within a conversation. Each stage has a prompt (what the chatbot says/asks), an extraction spec (what data to pull from the user's response), and edges (where to go next).
Starting a chat¶
Built in hadron-server 0.0.1978 (S6, hadron-server#4053); rule
cor:cht:020:02.
- A named start (
startChatwithconversationName) opens that conversation and checks no entry condition. - An unnamed start goes through the agent's ordinary conversations in
the author's order and opens the first one whose entry condition holds for
the person starting. The order is the conversation node's
seq, lowest first; a conversation with noseqcomes after all that have one; ties go by loc, compared as plain character codes. A conversation with no entry condition always holds. - Setup and fallback conversations are outside that order. When no ordinary conversation qualifies, the chat opens the setup conversation, then the fallback conversation, and otherwise the start is refused as it was before this order existed.
- An entry condition is stored in the conversation's
data.entryConditionas the same JSONLogic an edge condition uses, with one limit: it may read onlymemory.*andagent.*fields (thenow()andtoday()clock builtins are also accepted).chat.*andmessage.data.*have no value when a chat starts, and a path built by an expression instead of written out is refused too. - A condition that cannot be judged stops the start. It is not skipped.
The start is refused with
ENTRY_CONDITION_FAILEDand nothing is created. That includes a private memory that is encrypted while the person's session has no key, which refuses even when the first conversation has no condition of its own.
The condition is checked when it is saved, as well as when a chat starts:
a write that stores an invalid or out-of-scope entryCondition is refused
with INVALID_ENTRY_CONDITION. The check runs on node writes through the
GraphQL API, the MCP node tools (and so hadron node update), and the GitHub
sync. Restoring a revision, importing a revision, or moving a node onto a
conversation loc are not checked at save time; the start checks each
condition again before using it.
Both refusals, with their reason and detail, are in the
Chat API. In the portal, the Conversation
Editor's Start section sets the order and the condition; see
Build a chatbot agent.
Goals and signals¶
Every conversation (and optionally every topic) carries routing metadata:
{
"goalDescriptions": [
"Help the user find class times and teacher availability",
"Answer questions about the weekly schedule"
],
"goalSignals": [
"When is yoga?",
"Is the Saturday class running?",
"Who teaches on Monday?",
"Is Nina back in town?"
]
}
goalDescriptions — natural-language descriptions of when this
conversation is the right fit. Multiple phrasings help the routing
engine match ambiguous user messages. Write them from the user's
perspective: "The user wants to..."
goalSignals — example user statements that should route here.
This is a living list — it grows over time as you discover new
ways users express the same need. Multi-language signals are
supported.
Where to define them¶
Goals and signals live in the conversation node's data field. You
can set them via:
- The Chatbot Control tab in the portal (read-only display for now)
- The Conversation Editor (portal)
- Claude Code or any MCP host, with
hadron_update_nodeon the conversation node
Edges¶
Edges connect stages to other stages or conversations. They encode routing logic in the graph itself.
Edge properties¶
{
"target": "conversations:profile-building",
"condition": { "missing": ["memory.business_type"] },
"priority": 0,
"timing": "on_complete",
"behavior": "detour",
"label": "Fill profile if business type is missing"
}
| Property | Values | Description |
|---|---|---|
condition |
JSONLogic JSON, or null |
When the edge fires. null = always fires. See Edge conditions for the full operator subset, the five variable scopes (memory, chat, agent, message data, time), and the memory cascade. |
priority |
integer (default 0) | Resolution-order hook for edges sharing a source node; lower fires first. Reserved space for future agent-exception handlers to slot in at the top. |
timing |
on_complete, on_enter, always |
When to evaluate the condition. on_complete is checked on a turn that completes the conversation; always on a turn that names no next stage or completes it. on_enter is stored but not built — see What the chat engine acts on today. |
behavior |
transition, detour |
transition = permanent move. detour = move, and push a goal that remembers where the chat left, so completing the detour returns it there — see Detours and returns. |
label |
any string | Human-readable description (shown in the editor). |
For everything about condition — operators, variable scopes,
cascade, encryption behavior, the structured builder UI in the portal —
see the dedicated Edge conditions reference.
What the chat engine acts on today¶
The fields above are what an edge can store. This is what the engine does with them each turn (built in S3 and S4 of the Know Yourself engine, hadron-server#3850):
- A turn that names a next stage (
next_stage, withoutgoal_reached) moves to that stage and checks no rule that turn. A name that is not one of the conversation's stages moves nothing: the turn is still recorded and the name comes back asrejectedNextStage. The same happens when the conversation's stage list cannot be read. - A turn that names no next stage checks the
alwaysrules. - A turn with
goal_reached: truecompletes the conversation (see Completing a conversation). The flag wins over a named stage, which is ignored. Theon_completeandalwaysrules are checked together, in priority order. - The first rule that resolves ends the check. A rule resolves when its condition holds and its target exists. A rule whose target does not resolve fires nothing, pushes nothing, and the check goes on to the next rule. That covers a missing conversation, a stage that is not in the target conversation's stage list, and a conversation with no stages. This is how the engine behaves today; no rule promises it.
- A rule may target a conversation or a stage.
conversations:<c>enters that conversation's first stage.conversations:<c>:<s>enters stagesif it is in the conversation's stage list. on_enteris not built. Anon_enterrule can be stored, and the editor shows it as "not available yet; kept as is", but the engine never evaluates it. Do not rely on it.- Every change of conversation writes an exit entry first, plain transitions included (see Route history).
Rules run in every chat home: a shared chat, a private chat and a chat in an App-key session memory all evaluate them. The limits:
- The agent's definition is read only while the agent is installed and licensed in the home's App. After a loss, no rule runs at all, and the agent's memory-wide fields are not read either.
- A home with no App serves only the agent's managers.
- A member's condition reads the speaking member's own facts, not another member's.
This was completed by hadron-server#4038 (S5, closed 2026-11-13).
Common edge patterns¶
These are the usual combinations of timing, behavior and condition. The Conversation Editor has no presets for them: you set the fields yourself in Edit routing rule.
- Next:
timing: on_complete,behavior: transition. "When this conversation is completed, go there." It is checked when a turn setsgoal_reached. To move from one stage to the next, have the model name the next stage, or use analwaysrule with a condition on the stage's facts. - Prerequisite (not built: it uses
on_enter— see What the chat engine acts on today):timing: on_enter,behavior: detour, with a{ missing: [<field>] }condition. "Before entering this stage, make sure we have this data." For a conversation that should only open when data is missing, use an entry condition instead. - Escape:
timing: always,behavior: transition, with a condition. "The user can bail to this conversation when this holds." Without a condition it fires on every turn where the model doesn't setnext_stage, which hands the chat off almost at once. It is also checked on the turn that completes a conversation, where a firing rule beats the return from a detour and the fallback. Withbehavior: detourit is a detour the chat can return from. - Fallback:
timing: always,behavior: transition, meant to fire ononTrack: false. It can't be built today: an edge condition can't seeonTrack(see TheonTrackfield), and the same edge without a condition is the always-firing Escape above.
The onTrack field¶
Every chatbot response includes an onTrack boolean:
{
"message": "I see you want something else...",
"data": { ... },
"next_stage": null,
"onTrack": false,
"offTrackReason": "User is asking about billing, not the schedule"
}
onTrack: false is the model saying the current conversation isn't
serving the user. It was designed to trigger re-routing, but today it is
only recorded: processChatResponse stores it on the chat (with
offTrackReason) and returns it, and nothing reads it back. An edge
condition can't see it either: conditions evaluate against the memory
layers, the chat's message count, conversation and stage, the agent, and
the turn's extracted data. The one re-route that does run is out of the
fallback conversation, on goal signals
(see Fallback conversation).
Completing a conversation¶
Built in hadron-server 0.0.1984 (S3, hadron-server#4055); rules
cor:cht:030:01 and
cor:cht:030:02.
A conversation completes only when the model sets goal_reached: true in its
respond call. A missing, false or non-boolean value completes nothing and
fires no on_complete rule. The goal_reached field is part of the respond
tool the server hands back in tools; a caller forwards the model's whole
toolResponse and does not add it.
On a flagged turn the engine records the conversation as completed, once, in
the order of first completion, and adds a COMPLETED entry to the route
history. Then it goes in this order:
- A rule fires. If an
on_completeoralwaysrule resolves, the chat goes where it says. A firing rule beats the return and the fallback below, and a detour goal stays active. - Return from a detour. Otherwise the most recent active goal that
carries
detourTois marked completed and the chat re-enters the stage it left (see Detours and returns). - Move to the fallback conversation. Otherwise, if the agent has a fallback conversation and the chat is not already in it, the chat moves to the fallback's first stage. If it is already there, or there is none, the chat stays put.
A chat has no end. Completion is reported as conversationCompleted;
chatEnded stays false and nothing marks a chat as ended. If you need an
ending, have the last conversation's final reply say so and stop the
integration yourself.
If two turns complete at the same moment, only one is applied; the other
reports routingSkipped and changes nothing.
Detours and returns¶
Built in S4 (hadron-server#4100); live on alpha at the time of writing.
A rule with behavior: detour moves the chat and pushes a goal that
records the conversation and stage the chat left, plus where it went
(detourTo). The user's state is a stack of these:
[bottom] Find government programs (where the chat started)
→ Update business profile (detour: missing data)
When the detour conversation completes on a turn where no rule fires, the
chat goes back to the stage it left, the goal is marked completed, and the
result reports detourReturned: true. One return pops one level.
Three limits are worth designing around. They describe what the engine does today; the first two are proposed rules, not guarantees:
- If the stage the chat left no longer exists, it returns to the first stage of the conversation it left.
- If a detour's conversation has no stages, completing it closes the goal without a move and the turn continues to the fallback step.
- Goals recorded before this release, and the goal a chat starts with, carry
no
detourToand never return.
Nothing pushes a goal except a firing detour rule: the model's respond
tool has no goal field. The hadron_chatbot_push_goal and
hadron_chatbot_pop_goal MCP tools were removed in
hadron-server#1143.
No API returns the goal stack. What you can read is the list of completed
conversations on the chat: see
Chat.completedConversations.
Route history¶
Every chat records where it has been:
[
{ "action": "ENTER", "conversationUrn": "conversations:onboarding", "nodeUrn": "conversations:onboarding:welcome", "timestamp": "..." },
{ "action": "ENTER", "conversationUrn": "conversations:onboarding", "nodeUrn": "conversations:onboarding:background", "trigger": { "type": "STAGE_TRANSITION" }, "timestamp": "..." },
{ "action": "ENTER", "conversationUrn": "conversations:strategy", "nodeUrn": "conversations:strategy:diagnose", "edgeUrn": "...", "trigger": { "type": "TRANSITION_EDGE" }, "timestamp": "..." }
]
The engine appends an entry when a chat starts, when the LLM's
next_stage moves it to another stage, when a conversation completes, and
whenever the chat changes conversation: an EXIT entry for the one it leaves,
then an ENTER entry for the one it enters. A detour enters with trigger
DETOUR_EDGE, a return with DETOUR_RETURN, and a move to the fallback after
a completion with GOAL_REACHED_FALLBACK.
No surface reads it back today. Neither the Chat API nor the portal
returns a chat's route history or its goal stack. Only the names of the
completed conversations are readable. The hadron_chatbot_get_route_history
MCP tool did, and was removed in
hadron-server#1143.
The engine does not use it for loop prevention either. To see where a
test chat went, run it in the portal Tester's Scripted persona section,
whose report lists each turn's stage and the conversations visited.
Hierarchical extraction¶
Data extraction specs can live at three levels:
| Level | What it extracts | Scope |
|---|---|---|
| Agent | User name, language, account ID | Every conversation |
| Conversation | Order number, problem description | All stages in that conversation |
| Stage | A yes/no confirmation, a rating | Just that step |
Each level inherits from above. A stage sees its own spec + the conversation's spec + the agent's spec. Stage-level fields win on conflict.
Agent-level specs live in a config node in the system memory:
{
"agentExtractionSpec": [
{ "field": "memory.name", "description": "User's full name", "shape": "string" },
{ "field": "memory.language", "description": "Preferred language", "shape": "string" }
]
}
Fallback conversation¶
Every agent should have a fallback conversation — created automatically by the wizard. It handles the case where no conversation matches the user's request:
conversations:fallback
stage: no-match
prompt: "I can't help with that. Here's what I can do: [list].
Or reach a person at [contact]."
The fallback conversation has isFallback: true in its data. The engine
picks the first top-level conversation flagged that way, in the author's
start order. A conversation flagged as both the fallback and the setup
conversation is the setup conversation, not the fallback.
The fallback is used in three places: as a start target when no ordinary conversation qualifies (see Starting a chat), as where a completed conversation with nothing to return to lands, and as the one place an off-topic chat is re-routed out of. That last re-route runs on goal signals and scans the other conversations in the author's start order, not alphabetically and not by loc.
Driving a chat¶
Run a chat through the Chat API — startChat,
sendChatMessage and processChatResponse — or in the portal: an App's
Chats tab for a real chat, and the agent's Tester for test runs.
To view or edit the routing graph, open the agent's Conversation
Editor. There are no MCP tools for chatbot chats: the eleven
hadron_chatbot_* tools were removed in
hadron-server#1143.
Related docs¶
- designing-a-multi-stage-conversation.md — learn-by-doing tutorial that walks through designing a real three-stage conversation (intake → research → summarize) with prompts, extraction specs and signals.
- test-personas.md — automated testing with personas
- chatbot-end-to-end-test.md — manual end-to-end test guide
- building-a-chatbot-agent.md — creating a chatbot from scratch