Agent Canvas — DAG-based workflow orchestration

🎯 Why This Module Exists

The Agent Canvas provides a structured, DAG-based execution model for complex multi-step workflows. Without it, workflows would degrade to imperative scripts, losing visibility into data dependencies and control flow. The Canvas enforces a clean separation between DSL (what to do) and Components (how to do it), allowing LLM applications to be built, debugged, and versioned as structured data rather than code. It enables introspection, serialization, and auditable execution histories. — Replace with 150+ words explaining what problem this module solves, why it exists as a separate module (not merged into something else), and what the system would look like without it. Use narrative voice: "Without this module, every component would need to..."

🚶 Step-by-Step Narrated Walkthrough

Follow a single user submits a canvas with LLM + tool invocation nodes as it flows through the entire Agent Canvas pipeline:

1. DSL Input: User provides a canvas as JSON with nodes (LLM, Agent, Switch, Iteration) and edges defining dependencies.
2. dsl_migration: Legacy DSL schemas are normalized to the current format, ensuring backward compatibility with old workflows.
3. Graph.load(): Canvas parses JSON, instantiates ComponentBase subclasses (LLM, Agent, tools) from the registry, and validates the DAG.
4. Topological Sort: Computed at O(V+E) complexity; determines execution order such that all dependencies run before dependents.
5. Variable System Setup: Global variables, component outputs (cpn_id@output), and nested iteration scopes are pre-registered.
6. Greedy Execution: Canvas iterates: for each ready node (all dependencies complete), invoke component.run(inputs) and cache outputs.
7. Iteration Handling: Iteration components wrap sub-DAGs; executed once per list item, with iteration-scoped variables re-bound each time.
8. LLM Invocation: LLM component calls a chat model (OpenAI, Anthropic, etc.), optionally with structured output via JSON Schema.
9. Agent Tool Loop: Agent extends LLM; LLM suggests a tool, Agent calls it from registry, feeds result back to LLM for next iteration.
10. Switch Routing: Switch evaluates conditions; can route to multiple branches (fan-out) if multiple conditions match.
11. Error Handling: Failures handled via max_retries (exponential backoff), exception_default_value (fallback), or exception_goto (reroute).
12. History Recording: Every step—node start, input variables, outputs, errors—appended to Canvas.history immutably.
13. Completion: After all nodes execute, Canvas returns outputs dict and complete history; caller inspects or re-runs with new inputs.

Topological Scheduling + Variable Resolution

The Problem: What specific problem does this algorithm solve?

The Approach: How does it work, step by step, in plain English?

Why This Algorithm: What alternatives exist and why weren't they chosen? What are the time/space complexity trade-offs?

graph TD
    A[Input] --> B{Decision Point}
    B -->|Case 1| C[Fast Path]
    B -->|Case 2| D[Complex Path]
    C --> E[Output]
    D --> F[Sub-step] --> E
    style C fill:#e8f5e9
    style D fill:#fff3e0

Hot Paths

The most performance-sensitive code paths in this module:

• Path 1: Description — O(n) / O(1) — why this matters
• Path 2: Description — complexity — trade-off made

Resource Usage

• Memory: What's allocated, when it's freed, and any caching strategies
• I/O: What external resources are accessed and how often