Agent Canvas/Canvas & Execution/ — Canvas & Execution

Contents

Architecture

graph TB
    JSON["JSON DSL
Input"] --> MIGRATE["dsl_migration
Schema Normalize"]
    MIGRATE --> GRAPH["Graph
Base Class"]
    GRAPH --> CANVAS["Canvas
DSL Loader"]
    CANVAS --> LOAD["load()
Parse & Instantiate"]
    LOAD --> VALIDATE["Validate
DAG Integrity"]
    VALIDATE --> SCHEDULE["Topological
Sort"]
    SCHEDULE --> EXEC["execute()
Greedy Run"]
    EXEC --> RESOLVE["Variable
Resolution"]
    RESOLVE --> CACHE["Output
Cache"]
    CACHE --> HISTORY["History
Tracking"]

flowchart LR
    DSL["DSL JSON
Input"] -->|load| Components["Components
Instantiated"]
    Components -->|execute| Sort["Topological
Sort"]
    Sort -->|greedy| Exec["Execute
Ready Nodes"]
    Exec -->|resolve| Vars["Variables
Resolved"]
    Vars -->|cache| Outputs["Outputs
Cached"]
    Outputs -->|history| History["History
Recorded"]
    style DSL fill:#e8f5e9
    style Outputs fill:#fff3e0
    style History fill:#e8f5e9

Key Classes

Data Structures

Interactions

Configuration

Directory Map

submod_name/
├── file_a.ext                 ← Role: brief annotation
├── file_b.ext                 ← Role: brief annotation
├── file_c.ext                 ← Role: brief annotation
└── index.ext                  ← Role: entry point

📑 Annotated Code Walkthrough

The most important code in this sub-module, annotated with WHY each piece exists:

// Replace with actual code from the source
void key_function() {
    // ← WHY: Explain the purpose of this line
    // ← WHY: What constraint or requirement drives this?
}

⚠️ Edge Cases & Boundaries

Deep-Dive Highlights

Core mechanisms from this sub-module have been extracted into dedicated focus pages for in-depth exploration. Each page covers one algorithm, protocol, or subsystem with diagrams, code walks, and configuration details.

Deep-Dive Pages

Code Examples

Example: Typical Usage

// Replace with actual code example
void example() {
    // ...
}

Execution Algorithm Details

The Canvas.execute() method follows a specific algorithm to schedule and run components. Understanding this is critical for debugging complex workflows.

Topological Scheduling Algorithm

The topological sort ensures that components with dependencies execute only after their dependencies complete. This is implemented using Kahn's algorithm (iterative BFS-based):

1. Compute in-degrees: For each node, count how many edges point to it (incoming dependencies).
2. Initialize queue: Add all nodes with in-degree 0 to a queue. These have no dependencies and can run immediately.
3. Process queue: While queue is not empty:
   • Dequeue node N
   • Add N to sorted order
   • For each outgoing edge from N: decrement destination node's in-degree. If in-degree becomes 0, enqueue destination.
4. Detect cycles: If sorted order length < graph size, a cycle exists. Raise ValidationError.
5. Time complexity: O(V + E) where V = components, E = edges. Linear in graph size; very fast even for large workflows.

Greedy Execution Model

After topological sort, Canvas uses a greedy single-threaded execution model:

• Nodes are processed in topological order
• For each node: check if all dependencies have completed (in_degree == 0)
• If yes, call component.run(); store result in _outputs[node_id]
• If no, skip (will retry in next pass)
• Record execution step in history: {node_id, inputs, outputs, error, timestamp, duration_ms}
• On error: apply retry logic (exponential backoff, max 5 attempts), then exception_default_value or exception_goto
• Continue until all nodes executed or error unrecoverable

Variable Resolution Trace Example

When a component parameter contains a variable reference (e.g., "search_query": "{{llm_1@output.text}}"), Canvas resolves it at runtime:

1. Parameter value: "llm_1@output.text"
2. Split on @: component_id="llm_1", path="output.text"
3. Look up llm_1 in _outputs: {output: {text: "Hello", choices: [...]}}
4. Traverse path "output.text": _outputs["llm_1"]["output"]["text"]
5. Result: "Hello" → pass to component parameter
6. Component receives concrete value, not template

This lazy evaluation allows workflows to handle non-deterministic LLM outputs without requiring re-compilation or DAG reconstruction.

Performance Characteristics

The Canvas execution engine is optimized for real-world workflows with variable-length DAGs. Key performance considerations:

Hot Paths & Optimization

• Execute Phase (60-80%): Component run() methods dominate. If slow, profile component logic (LLM timeouts, API latency, loop iterations).
• Variable Resolution (10-20%): Deep scopes (iterations inside loops) are costlier. Cache variable references if accessed repeatedly.
• Topological Sort (1-5%): Only on load(); negligible for re-execution. Use cached DAG for production workflows.
• Retry Logic: Exponential backoff can add seconds per failure. For flaky tools, raise timeouts or add circuit breaker logic.