Skip to content

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 (startChat with conversationName) 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 no seq comes 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.entryCondition as the same JSONLogic an edge condition uses, with one limit: it may read only memory.* and agent.* fields (the now() and today() clock builtins are also accepted). chat.* and message.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_FAILED and 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_node on 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, without goal_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 as rejectedNextStage. The same happens when the conversation's stage list cannot be read.
  • A turn that names no next stage checks the always rules.
  • A turn with goal_reached: true completes the conversation (see Completing a conversation). The flag wins over a named stage, which is ignored. The on_complete and always rules 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 stage s if it is in the conversation's stage list.
  • on_enter is not built. An on_enter rule 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 sets goal_reached. To move from one stage to the next, have the model name the next stage, or use an always rule 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 set next_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. With behavior: detour it is a detour the chat can return from.
  • Fallback: timing: always, behavior: transition, meant to fire on onTrack: false. It can't be built today: an edge condition can't see onTrack (see The onTrack field), 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:

  1. A rule fires. If an on_complete or always rule resolves, the chat goes where it says. A firing rule beats the return and the fallback below, and a detour goal stays active.
  2. Return from a detour. Otherwise the most recent active goal that carries detourTo is marked completed and the chat re-enters the stage it left (see Detours and returns).
  3. 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 detourTo and 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.