Nodes and the canvas

Use a node when the work may need a follow-up, a report, a child, or time without a caller holding a request open. A node is a durable unit of agent work: it has an identity, a goal, graph relationships, a context directory for artifacts, and a broker that hosts its agent engine. It is not an HTTP request with an LLM response attached.

The canvas is the durable graph of those nodes. It makes an agent's work and its relationship to other work visible after the process that created it has returned. This is why client.nodes.create returns a node you can retrieve, message, stream, or wait on instead of only returning generated text. An application can create a root node, show its progress, and later call nodes.message when a person or an external event has more work for it.

flowchart TD
  App[Application] -->|creates or messages| Daemon[crtrd]
  Daemon --> Node[Durable node]
  Node --> Broker[Broker and agent engine]
  Node --> Context[Context directory and artifacts]
  Child[Child node] -->|pushes a report| Node
  Node -->|pushes a report| Parent[Subscriber]

A graph edge is not just a visual parent-child line. The management relationship records who owns a child, while subscriptions carry report delivery. On normal child creation, the parent subscribes to the child, so the child’s final report wakes the parent. A node can have other subscribers too; report delivery is intentionally separate from hierarchy.

The one way work reports upward is a push. A push writes a durable report and puts a reference in each subscriber’s feed. Nothing is reported merely because a node stopped producing text. That makes a report an explicit claim a subscriber can inspect, rather than an inference from terminal output. The parent can then integrate the child’s result instead of repeating the work.

A node owns an outcome, not merely an artifact. It may write files and reports while working, but its terminal result is credible only when it has evidence that the requested goal was met. The canvas supports that responsibility: it preserves the goal, durable artifacts, reports, and relationships across fresh contexts and broker replacement.

Use a one-shot SDK call such as nodes.parse when work is bounded and its only useful output is a typed result. Use nodes.create when the application needs a continuing conversation or must observe work while it runs. For the operational graph and report model, run crtr memory read internal/nodes-and-canvas.