AgentCanvas / Pages / Developer Guide / Core / Major Versions

Major Versions

A living declaration of what each major version of AgentCanvas is about — the paradigm-level framing.

This file captures the paradigm-level framing — what a version means and what earns the major-number bump. Tactical open work (TODOs, features, env/method implementations) lives in roadmap; detailed subsystem design lives in design-docs/.

§1AgentCanvas v1 — Bounded Static-Topology Canvas active

Thesis Agent behaviour is a bounded static-topology dataflow graph. One JSON = one agent = one graph. Every node, edge, and tool that could fire is declared before the run starts; the graph executor fires them when their inputs arrive. Within that bound the agent can do plenty at runtime — pick which branch to walk, when to terminate, how many iterations to spend — but it cannot introduce nodes, tools, or node-types the graph did not already know about. The graph remains a topology the researcher can see, diff, and share.

Paradigm: Bounded, pre-declared topology — whatever the agent does at runtime, the set of fireable nodes / tools is fully known before the run starts. Runtime decisions are selections over a predeclared set, never extensions of it.

Agent forms v1 covers

All of the following can be expressed as bounded static topology and therefore belong in v1 — either as graph-visible patterns or hidden inside a single BaseCanvasNode subclass:

What ships in v1 (paradigm building blocks)

v1 ships when: the public API is declared stable and frozen under SemVer — open-source-ready (LICENSE / install docs / CONTRIBUTING), the agent-forms list above each exercised by a canonical graph, and the graph-JSON / nodeset / CLI-HTTP surfaces documented. Until then, tags are v0.x — the API is still moving with research iteration and external-integration friction. Paper submission is deliberately not a v1.0 trigger.

Out of scope for v1: anything that requires the set of nodes / tools / node-types to grow at runtime — that's v2.

Deployable / packaging concerns The old "Deployable Product" thesis (packaging as Docker / pip / installer, optional auth, multi-tenant, cloud deployment) lives in v1.x minor versions as polish, not as a separate paradigm shift. If multi-tenant cloud deployment ever becomes a serious external ask that genuinely demands a different runtime model, revisit whether it deserves its own major — but the default expectation is "v1.x picks it up incrementally".

§2AgentCanvas v2 — Topology-Growing Canvas future

Thesis The agent can grow its own topology at runtime — spawn new node instances from runtime data, register new tool types it did not know about at graph-design time, or rewrite its own graph mid-run. The v1 invariant "graph JSON is a complete spec of what can run" weakens: the graph is the source of truth at each instant, but the graph itself becomes runtime-mutable.

Paradigm: Topology-mutating execution — the set of fireable nodes / tools / edges can change during a run. Runtime decisions can be extensions of the predeclared set, not only selections within it.

What v2 covers (and v1 does not)

Why this earns a major version bump

Non-goals

Open questions — deliberately unresolved
  • Does v2 get a second executor, or does GraphExecutor generalise to handle mid-run mutation?
  • How does the canvas show a mutating graph without confusing the user?
  • What does state-container lifetime mean for a scope spawned at step N and removed at step M?
  • Tool availability scoping: all loaded tools? A runtime-declared subset? Per-scope gating?
  • Does PortBench's structural-inspectability claim degrade gracefully or require a v2-specific audit pass?

§3Versioning Discipline

AgentCanvas docs