How to debug routing decisions in traces

Use this when support, QA, or partners need to understand why a user went to one specialist instead of another, or why a route silently fell through to fallback.

Concept

Every HANDOFF decision, whether deterministic (WHEN: intent.category == "billing") or semantic (WHEN: "the request is about billing"), produces a trace event describing what was evaluated and why a target was or wasn’t selected. The runtime does not just log “routed to Billing_Agent” — it records the condition it evaluated, the context available at evaluation time, the outcome, and (for temporary child agents) what came back through ON_RETURN. One thing surprises people the first time they read a routing trace: not every routing event is visible at every trace verbosity level. The runtime supports minimal, standard, verbose, and debug verbosity. If you’re not seeing an event you expect (like handoff_condition_check for a route that didn’t match), raise verbosity before assuming the event doesn’t exist.

Minimal working example

SUPERVISOR: Traceable_Routing_Supervisor
GOAL: "Make routing decisions easy to inspect in traces"

ON_START:
  SET:
    _meta.entry_channel = session.channel
    _meta.routing_version = "support-router-v3"

INTENTS:
  billing: "Billing and payment requests."
  technical_support: "Product troubleshooting requests."

HANDOFF:
  - TO: Billing_Agent
    WHEN: intent.category == "billing"
    EXPECT_RETURN: false
    CONTEXT:
      pass: [customer_id, account_id, conversation_summary]
      summary: "Traceable billing route."

  - TO: Technical_Support_Agent
    WHEN: intent.category == "technical_support"
    EXPECT_RETURN: false
    CONTEXT:
      pass: [customer_id, issue_summary, conversation_summary]
      summary: "Traceable technical support route."

  - TO: Fallback_Triage_Agent
    WHEN: "the request does not clearly match billing or technical support"
    EXPECT_RETURN: true
    CONTEXT:
      pass: [customer_id, conversation_summary]
      summary: "Traceable fallback route."
    ON_RETURN:
      action: resume_intent

AGENT: Billing_Agent
GOAL: "Resolve billing requests"

AGENT: Technical_Support_Agent
GOAL: "Resolve technical support requests"

AGENT: Fallback_Triage_Agent
GOAL: "Clarify unclear requests"

customer_id, account_id, issue_summary, and conversation_summary are shown as passed context fields; declare them via MEMORY or populate them via GATHER/tool results in your actual project — this example assumes they already exist as project-local session values.

How it works

The supervisor keeps ownership until a HANDOFF condition matches, evaluated in authored order.
Each evaluated condition emits handoff_condition_check with a shape similar to:
{ "event": "handoff_condition_check", "condition": "intent.category == \"billing\"", "result": false, "evaluatedContext": { "intent.category": "technical_support" }, "target": "Billing_Agent", "whenOutcome": "deterministic_no_match" }
For a matched deterministic route, the runtime also emits deterministic_routing and deterministic_handoff; for a matched semantic (quoted natural-language) WHEN, whenOutcome reflects the semantic evaluation path instead.
If a condition references a variable that is not yet set anywhere in scope, the runtime emits route_condition_unresolved instead of silently treating it as a non-match — check for this event before concluding “the condition just didn’t match.”
If a flow-level return suppresses a condition that would otherwise have matched (for example, the conversation is mid-flow and routing is intentionally deferred), the runtime emits handoff_condition_suppressed.
Once a target is selected, handoff_context_pass_resolved records what the resolved CONTEXT.pass values actually were, and handoff_context_set_applied records any CONTEXT.set writes applied to the child.
When EXPECT_RETURN: true is used (as in the fallback route above), the child’s return path emits handoff_return_handler, and ON_RETURN.action: resume_intent produces a resume_intent trace entry showing what intent processing resumed with.
Remember: since HISTORY is omitted from every HANDOFF above, each child receives the full conversation history by default (the platform default when HISTORY is unset). Set HISTORY: auto or another explicit strategy if you want bounded/summary history instead, and expect the trace’s history-related fields to reflect whichever strategy is in effect.
_meta.* values (like _meta.entry_channel above) are not routing logic — they’re custom trace dimensions for filtering/grouping in dashboards. You can SET _meta.* in ON_START, in flow steps, in lifecycle hooks, and in ON_ERROR/ESCALATE triggers, not only at conversation start.

Common variations

Debugging a semantic (natural-language) condition

Quoted WHEN text like WHEN: "the request does not clearly match billing or technical support" produces the same handoff_condition_check event, but whenOutcome distinguishes the semantic evaluation path from a deterministic one. There’s no separate event name to search for — filter on whenOutcome instead.

Debugging multiple intents in one message

Multi-intent routing emits its own event family instead of a single glob: multi_intent_plan_built (the queue was constructed), multi_intent_target_resolved (a queue entry resolved to a target agent), multi_intent_queued (an entry queued for later processing), multi_intent_sequential plus multi_intent_sequential_task_start/_task_complete/_executed (sequential processing), and multi_intent_parallel (parallel processing). Search for the specific event you expect rather than a wildcard.

Debugging trace visibility

If an event you expect isn’t showing up, check the trace verbosity setting first (minimal/standard/verbose/debug) before assuming the routing logic is wrong — some events only appear at verbose or debug.

Verification

Parse and compile the ABL and confirm there are no parser or compiler errors/warnings.
Test at least one matching utterance for each deterministic route, one for the semantic fallback, and one that should trigger route_condition_unresolved (reference a variable you know is unset).
Inspect the trace for: the selected target, the condition actually evaluated (matches your literal authored text), evaluatedContext, and — for EXPECT_RETURN: true routes — the handoff_return_handler and resume_intent entries.
Raise trace verbosity to verbose or debug if an expected event isn’t appearing.

Production readiness checklist

Every specialist route has a clear owner and a concise context summary.
Deterministic conditions use declared, gathered, tool-result, runtime, or returned fields.
Semantic conditions are quoted as natural-language WHEN text.
Temporary child agents (EXPECT_RETURN: true) produce every field mapped in ON_RETURN, verified via handoff_return_handler/resume_intent traces.
Fallback behavior is explicit and does not hide missing intent coverage — confirm via route_condition_unresolved and handoff_condition_suppressed that nothing is silently falling through.
_meta.* dimensions are stable, low-cardinality values (not raw user text), set consistently across the surfaces where routing decisions can occur (not just ON_START).
Trace verbosity is set appropriately for the environment (higher in staging/debugging, tuned for volume/cost in production).

Common mistakes

Mistake	Why it happens	How to avoid it
Only checking `handoff_condition_check` for the matched route	Skipped candidates are just as diagnostic when a route unexpectedly loses to another	Inspect all `handoff_condition_check` entries in the turn, not just the one that matched
Setting `_meta.*` only in `ON_START`	The article/example historically only showed `ON_START`	Also set `_meta.*` in flow steps, hooks, or `ON_ERROR`/`ESCALATE` when the dimension should reflect later-turn state
Setting high-cardinality `_meta.*` values (e.g. raw user utterance)	Seems convenient for debugging one session	Use stable, low-cardinality values; high-cardinality dimensions break dashboard aggregation
Not finding an expected trace event	Trace verbosity is below the level that surfaces it	Raise verbosity to `verbose`/`debug` before concluding the event doesn’t fire

Troubleshooting

Symptom	Likely cause	What to check
A route you expect to match never fires, and there’s no `handoff_condition_check` for it at all	Trace verbosity is too low, or the flow suppressed the condition before it was ever evaluated	Raise verbosity; check for a `handoff_condition_suppressed` entry
A condition evaluates to a non-match even though the variable looks set in your test	The variable is a different path than the condition references, or it’s unset at evaluation time	Look for `route_condition_unresolved`; confirm the variable’s actual path via `evaluatedContext` in `handoff_condition_check`
A temporary child agent’s fields never make it back to the parent	Missing or mismatched `ON_RETURN` field mapping	Inspect `handoff_return_handler` for the actual returned payload shape
Child agent has less/more conversation context than expected	`HISTORY` was omitted and the platform default (`full`) applied, or an explicit strategy elsewhere in the project differs from what you assumed	Check `HISTORY`/`CONTEXT.history` on the `HANDOFF`; confirm against the current platform default

​Concept

​Minimal working example

​How it works

​Common variations

​Debugging a semantic (natural-language) condition

​Debugging multiple intents in one message

​Debugging trace visibility

​Verification

​Production readiness checklist

​Common mistakes

​Troubleshooting

​Related articles