1Graph-Expressible Agents

AgentCanvas supports workflow DAGs, cyclic agent loops, and compositions of both on the same canvas. This page explains how each form works and how the executor handles them uniformly.

Design docs: Graph Executor · Loop Control

1. Three Forms

All three are expressed as the same GraphDefinition JSON and executed by the same GraphExecutor. The executor doesn't distinguish between forms — it simply fires nodes when their inputs arrive.

2. DAG Workflow

A DAG workflow is a graph with no cycles. Nodes fire in topological order (inputs before outputs), and execution ends when all reachable nodes have fired.

  [VLMCaption] → [Summarize] → [GraphOut]

Executor behavior: Entry nodes (no required inputs, no incoming edges) fire first. Outputs propagate forward. No IterIn/IterOut needed — the graph runs once and completes.

2.1 Example JSON

{
  "name": "Caption Pipeline",
  "nodes": [
    { "id": "cap", "type": "vlmCall", "label": "VLM Call", "config": {} },
    { "id": "sum", "type": "llmCall",    "label": "Summarize",   "config": {} },
    { "id": "out", "type": "graphOut", "label": "Output",      "config": {} }
  ],
  "edges": [
    { "id": "e1", "source": "cap", "target": "sum", "sourceHandle": "text", "targetHandle": "text" },
    { "id": "e2", "source": "sum", "target": "out", "sourceHandle": "text", "targetHandle": "text" }
  ],
  "step_budget": 1
}

3. Agent Loop

An agent loop is a cyclic graph using two pivot nodes: a two-sided IterIn whose left/input side receives run-start seeds (declared in config.initPorts, wired as ordinary canvas edges into init_<name> handles) and whose right/output side broadcasts the per-iteration loop-carry bundle, and IterOut, which collects end-of-step data and feeds it back. The loop transfer uses a single pairedWith config field linking IterOut → IterIn; no canvas wire joins the pivots.

  [entry nodes] ──init_*──→ [IterIn] → [EnvObserve] → [LLMCall] → [Decision] → [EnvStep] → [IterOut]
                               ▲                                                              │
                               └────────────────── pairedWith (loop transfer) ────────────────┘

3.1 Two Pivots

The GraphExecutor handles the cycle explicitly:

1. IterIn (ports_mode="source") is not seed-eligible — the executor explicitly excludes type == "iterIn" from the seed rule (graph_executor.py). Run-start seed edges land in its init_<name> port slots; it fires once any slot is populated (iter 1) and again on each IterOut transfer (iter 2+). Slots with persist=true re-emit every iteration; persist=false slots clear after the fire (one-shot).
2. Downstream body nodes fire as data flows forward.
3. IterOut fires once per iteration, at the end: - Increments the per-scope step_counter (mirrored to self.step_counter on the outermost scope for backward compat); - Broadcasts step_end signal so lifetime="step" state containers clear; - Checkpoints state containers at root-scope iter boundaries; - Flushes the execution log to JSONL; - Calls _broadcast_step() to consolidate output-viewer data into the nav_step WebSocket event; - Transfers its outputs into the paired IterIn's iterout_<name> port slots and pushes IterIn back onto the ready queue.
4. The loop repeats until the paired IterOut's stop input is truthy (checked once per iteration at the boundary) or step_budget is reached; node code may also raise StopExecution as an escape hatch.

Current IterOut handling (abridged from agent_loop/graph_executor.py):

if node.type == "iterOut":
    _io_scope_id = node.config.get("pairedWith", "") or self._outermost_scope_id
    _io_scope = self.scope_state.get(_io_scope_id)
    _io_scope.step_counter += 1
    self.broadcast_signal("step_end", {"step": _io_scope.step_counter, "scope_id": _io_scope_id})
    # ... checkpoint, log flush, _broadcast_step, multi-scope settle ...
    paired = self.nodes[_io_scope_id]   # the iterIn
    paired.pending_inputs.update(result)
    ready_queue.append(paired.id)

3.2 Multi-Scope Loops

A single flat graph can contain N coexisting (IterIn, IterOut) pairs — each defines a scope with its own iteration cadence (ADR-dataflow-007, ADR-executor-003). The executor computes a scope forest at run-start via analyze_scopes(); each scope keeps its own step_counter; graphOut nodes inside inner scopes buffer their value into state["latched_value"] and flush on scope termination (_propagate_graphout_latches). The outermost scope's termination ends the run.

3.3 Termination

A loop ends when the paired iterOut's stop BOOL input is truthy — the executor reads it once per iteration at the boundary, ends that scope, and fires the terminal iteration's values out on the iterOut's final_* handles (the after-loop verdict stage). The standalone Termination node type was removed 2026-06-11; node code may still raise StopExecution as an escape hatch to abort mid-iteration. In multi-scope graphs the stop is per-scope — an inner scope's stop ends only that scope; only the root scope's stop ends the run.

4. Mixed Composition

Because the executor is form-agnostic, DAGs and loops can be freely mixed:

• Loop inside DAG: A graph node containing an agent loop can be placed in a larger workflow DAG. The flattener expands it, and the executor handles the inner IterIn/IterOut cycle while the outer DAG nodes fire normally.
• DAG inside loop: A composite node containing a linear pipeline (caption → summarize) can be placed inside an agent loop. Each iteration expands and runs the inner DAG.

This composability comes from two mechanisms: 1. Nested graph system — composite nodes with subgraphs (see Nested Graph System) 2. Flatten before execute — flatten.py recursively expands all composites, so the executor always sees a flat graph

5. Key Files

Status

All items fully implemented.