Observability

A process run is durable. Everything that happened — which node executed, what the context was before and after, what the child agent said, which tools it called — is captured. The run UI surfaces this through three tabs.

Process tab

The default view. Two panes and a strip:

State chart

An interactive graph of the process definition. The renderer uses the visual metadata in the definition when present:

• node.metadata.phase groups a large process into major stages.
• node.metadata.lane separates responsibility, such as agent, review, routing, or finalization.
• node.metadata.order gives a stable order inside a phase / lane.

If that metadata is absent, the UI infers a readable grouping from node titles and ids. That works for quick drafts, but published definitions should set metadata explicitly so the graph stays stable as the process evolves.

The graph has two complementary renderers:

• Diagram — a compact node-link view for quick topology checks.
• Swimlanes — a process board that groups nodes by responsibility lane and phase. Use this for business review, demos, and long-running processes with human handoffs.

The left Process Navigator groups nodes by phase and lets you jump without panning across the full canvas. The graph can render in three visibility modes:

• Main — the primary path through the process, hiding most loop-limit and escalation detours.
• Nearby — the selected node, its direct incoming / outgoing neighbors, and their guards.
• All — the complete process definition.

Each node card shows:

• Node id (or title, if set).
• Node type (agent, human_task, …) as a pill.
• human_description if set, otherwise node.title.
• tool: or interaction: ref if declared.
• The writes scope as small chips.

Color rings indicate state: the current node has an info-colored ring, completed nodes a success ring, failed nodes a destructive border, skipped nodes are dimmed. The initial node is always tagged.

On a run, the executed route is highlighted separately from the untaken graph. Completed nodes show success state, the current node is emphasized, and the transitions that were actually taken use a stronger primary stroke. This matters on branching processes: the definition may have many exits, but the run should make the chosen path obvious.

Transitions and condition branches are selectable too. Guarded exits render as small edge labels. Click a guard label or edge to inspect the YAML definition on the right.

Node inspector

Click a node to inspect it on the right pane:

• Header — the node's human_description in plain text, plus badges and a Retry action (for admins, when the run is active and this is the current node).
• Transitions — the declared targets with labels / triggers, and for the currently-active node an Advance button that emits a manual transition signal (admin-gated).
• Tasks — any human tasks created for this node, embedded with the response form so admins can answer inline.
• Node History — every time the node has been entered, with:
  • Status (completed, running, skipped, failed)
  • Entered / exited timestamps
  • The context diff that was applied on exit, rendered as a scrollable JSON block
• Definition — type, tool, interaction, writes, skippable.
• Context — the full current process context, scrollable.
• YAML — the selected node, transition, branch, task, input, metadata, or runtime state as copyable YAML.
• Explain — calls the built-in sys:ExplainProcess interaction with the process definition, current context, selected node, and selected guard. Use it to get a concise explanation of what the step does, why it routes the way it does, and what can go wrong.

The context diff is what most debugging starts with: for each run of the node, it shows exactly what was written. An empty diff after an agent node running a schema-constrained write usually means the child conversation produced unparseable output (the run will have failed).

When a transition is selected, the inspector switches from node details to edge details. This is the fastest way to debug "why did it go there?" questions: inspect the guard YAML, current context, and explanation together.

Timeline strip

Along the bottom: one pill per node_history entry in chronological order. Clicking a pill selects that node in the inspector.

Conversation tab

Mounts the same ModernAgentConversation you get for standalone agent runs, scoped to the process run id. Every agent node's child conversation lives under that run as its own workstream (named after the node id). The conversation view's workstream tabs let you flip between:

• the main workstream (usually read-only for programmatic runs — the process workflow doesn't do LLM calls itself),
• and one workstream per agent node that ran.

Each workstream streams live while the node is active, and stays inspectable after completion — you can read the full message history, see every tool call (with inputs and outputs), and copy structured outputs.

This is the equivalent of the agent observability view you already use for conversational agents, but rooted at the process run rather than a bare agent run.

For supervised process runs, the Conversation tab also exposes chat input to the top-level ProcessSupervisor. The process workflow posts structured events into that supervisor conversation: run start, node entered, node completed, guard failed, no transition matched, node failed, and human task waiting. The supervisor can answer by calling process-control tools: set_context, transition_to, skip_node, continue_process, retry_node, or fail_process. The process workflow remains the source of truth: it validates context writes, declared transition targets, skip policy, internal _ fields, and checkpoint sequence before applying anything.

The supervisor is useful when the deterministic engine reaches an ambiguous point: a guard fails, no transition matches, a node result needs interpretation, or a human wants a controlled override. In normal programmatic runs there is no top-level supervisor conversation; only child workstreams for agent nodes appear.

Observability tab

The generic Agent Observability view, scoped to the process run id. Useful for:

• Temporal history (every signal, every activity, every retry).
• Conversation snapshots per activity (before / after, downloadable).
• Tool-call metrics and context-window charts.

Because the process run id is also the agent run id for every child conversation, this tab surfaces the full agent hierarchy: the outer process as the parent, each agent node as a sub-agent.

Task inbox

Not a tab of the run view, but related: the Task Inbox in the global nav shows process human_task tasks and agent ask_user tasks that the current user can read. See Task Inbox.

Typical debugging flow

1. Open the failed run; the State tab usually points at the node that failed.
2. In the Inspector, read the last node-history entry's context_diff. Empty diff on an agent node → schema didn't match, jump to the Conversation tab for that workstream.
3. In the Conversation tab, switch to the node's workstream, read the final assistant message. If it's prose, the agent didn't emit JSON. If it's a partial JSON, you can see exactly which required field was missing.
4. If the problem is routing, click the edge or guard label and inspect the guard YAML against the current context.
5. Use Explain on the selected node or guard when you need a plain-language summary before changing the definition.
6. Fix node.writes, the guard, or the prompt, save a new version, and start a fresh run.