React Flow as an Agent Orchestration Canvas

React Flow is the canvas everyone reaches for to draw a workflow. Far fewer people use it for what it is quietly perfect at: being the control plane for a running agent system. The same graph that a non-engineer drags around to describe "when a ticket comes in, search the docs, then either answer or escalate" can be the literal definition the runtime executes. The diagram stops being documentation and becomes the program.

Nodes are capabilities, edges are contracts

The reframing is small but total. A node is no longer a shape — it is a capability: a trigger, an agent, a tool, an output. An edge is no longer a line — it is a typed contract that the output of one capability is a valid input to the next. React Flow already gives you the two primitives this needs: custom node components and typed handles (ports). You are not bending the library; you are using the part of it most demos ignore.

Typed ports are the whole trick

The difference between a pretty canvas and a real orchestration tool is whether the connections mean anything. Give each handle a type — a document stream, a tool result, a terminal response — and reject connections that violate it at draw time. Now the canvas itself prevents an entire class of invalid graphs before anything runs. The user cannot wire a string output into a node that expects a tool call, because the port simply will not accept the edge.

// a handle carries a type; the canvas refuses incompatible edges
type PortType = "trigger" | "tool" | "text" | "done";

function isValidConnection(c: Connection, nodes: AgentNode[]) {
  const from = portType(nodes, c.source, c.sourceHandle);
  const to   = portType(nodes, c.target, c.targetHandle);
  return COMPATIBLE[from]?.includes(to) ?? false;
}

// <ReactFlow isValidConnection={isValidConnection} />

Separate the render graph from the run graph

Keep one rule and this stays clean: the React Flow state is the render model — positions, selection, the visual edges. The runtime consumes a derived graph — capabilities and their typed wiring, stripped of all view state. The canvas owns how it looks; the executor owns what it does. Compiling one into the other is its own topic — toposort, cycle detection, scheduling — covered in the companion post.

Why managers care

An agent system defined as a visual graph is one a product manager can read, a support lead can adjust, and an engineer can debug by watching the active path light up. The orchestration stops living in a thousand lines of imperative glue and starts living in an artifact the whole team can point at. That legibility is worth more than any individual clever prompt.

The best agent architecture is the one a non-author can read. A typed node graph turns "trust me, the orchestration works" into something you can point at.

Next: compiling that canvas into a runnable pipeline, and the related pattern of routing between specialised agents.