Core Concepts

Core Concepts

AgentDesk is organized around a simple debugging loop: run or import a workflow, inspect trace evidence, replay failed steps, validate the graph, and export a redacted bundle.

Workflow

A workflow is the graph being debugged. It contains:

• nodes
• edges
• labels and descriptions
• provider metadata
• optional model or tool configuration

AgentDesk includes launch demos for common debugging stories, including the Failure Replay Lab.

Nodes

Nodes represent agent workflow steps. Common node kinds include:

• trigger
• model
• tool
• router
• output

Node providers describe how the node can run or be simulated:

• ollama for local Ollama model nodes
• openai for OpenAI model nodes
• anthropic for Anthropic model nodes
• mcp for MCP tool nodes
• local for local command nodes

Clicking a node opens the debugger view for that node and shows the latest trace event tied to it.

Edges

Edges describe the order and structure of the workflow. AgentDesk validates graph health before and during runs. Validation can flag:

• duplicate node IDs
• missing edge endpoints
• missing required edges
• cycles
• unreachable output nodes
• dead-end non-output nodes

Trace Events

A trace event is a single observed step in a run. It can include:

• node ID and label
• status
• provider and model
• started time and duration
• token counts
• cost estimate
• summary
• prompt
• tool call
• result
• stdout
• stderr
• artifacts
• error code and message

Trace events are click-linked to graph nodes. Clicking a trace event highlights the corresponding node. Clicking a node finds the latest trace evidence for that node.

Artifacts

Artifacts are structured evidence captured during a run. AgentDesk currently supports:

• JSON
• markdown
• screenshot previews
• stdout
• stderr

Artifacts are useful when the failure cannot be explained by a single summary string. They are also important for handoffs because they preserve the payload around a failure.

Costs

Cost rows group trace cost by provider/model where available. Demo and simulated steps use zero cost. Cloud BYOK model nodes can include usage metadata returned by the provider.

Cost data is a debugging aid, not a billing system. Treat it as a directional estimate unless you verify it against provider billing records.

Replay

Replay has two meanings:

• Whole-run replay: run the workflow again.
• Failed-step replay: append a replay event for the selected failed step without erasing the original failure.

Failed-step replay is intentionally evidence-preserving. The original failed event remains visible, and the replay event is linked to it.

Export

AgentDesk exports two main evidence formats:

• replay-session JSON for restoring the workflow, trace, selected evidence, imported MCP metadata, and UI state
• trace bundle ZIP for manifest and artifact files

Exports are redacted, but users should still avoid putting raw secrets into prompts, labels, artifacts, stdout, stderr, or screenshots.