我如何让 Agent 直接跑在 React Flow 画布上，而不只是画图

[ EXECUTIVE TEARDOWN // TL;DR ] React Flow can be the control plane for a running agent system, not just a diagram of one. Reframe nodes as capabilities (trigger, agent, tool, output) and edges as typed contracts between them. Typed ports let the canvas reject invalid graphs at draw time, eliminating a class of runtime errors. Keep the render graph (React Flow state) separate from the derived run graph the executor consumes. On IntegrateX I stopped treating the React Flow canvas as a place to sketch workflows and started running the agents directly off it — as the control plane for a running agent system. The same graph a PM drags to say "when a ticket comes in, search the docs, then either answer or escalate" is the exact spec the runtime executes — no shadow YAML, no parallel DSL. The moment you wire it this way, the diagram stops being decoration and becomes the program. Nodes are capabilities, edges are contracts Treat the canvas like a system, not clip art. A node is a capability: trigger, agent, tool, output. An edge is a typed contract that says one capability's output is valid input to the next. React Flow already gives you the primitives you need: custom node components and typed handles (ports). You're not fighting the library; you're finally using the part most demos skip. Nodes are agents and tools; typed ports are the contract; the lit edge is the run actually executing. Typed ports are the whole trick The gap between a pretty drawing and a real orchestrator is whether connections carry meaning. Put a type on each handle — document stream, tool result, terminal "done" — and reject bad edges while the user is drawing. Entire categories of runtime bugs disappear, and your on-call future self stops diffing logs to learn someone piped a string into a tool port. If the port doesn't accept the edge, it can't ship broken. ports.ts // 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; } // Enter fullscreen mode Exit fullscreen mode Separate the render graph from the run graph Keep one invariant or you'll drown in state-synchronization lag: React Flow state is the render model — positions, selection, pan/zoom, visual edges. The executor consumes a derived run graph — capabilities and typed wiring, no UI fluff. I package this as the pattern I call Trinity Architecture: (1) Presentation — the canvas renders and dispatches events; (2) Reactive State / Orchestration — a client store owns the source of truth and optimistic updates; (3) Data / Serialization Adapter — a boundary that compiles rich in-memory state into lean wire payloads. On IntegrateX, that Serialization Adapter stripped React Flow metadata before persistence and cut payload size 94%, which killed a whole class of sync stalls and payload bloat. Boundary rule: the UI never formats DB schemas; the adapter never pokes UI state directly — only through the orchestrator. Why managers care A visual, typed graph is readable to a PM, tweakable by support, and debuggable by engineers watching the active path light up in real time. You stop spelunking imperative glue and start pointing at a living artifact. Keep the overlay cheap and state isolated, and you avoid render thrash while the system streams results; hard-won habit from streamerOS, where 60fps mattered. The payoff here is clarity the whole team can ship against. 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 . Shipping IntegrateX solo taught me that the architecture a whole team can read and change is worth more than the clever one only its author can — the judgment I bring is choosing the version that survives contact with the rest of the team. ~/keep-reading 7 min readSerialization Adapters: How I Cut Payloads by 94%Rich UI objects make terrible database records. A Serialization Adapter I built for IntegrateX split render model from transport record and cut payloads by 94%. 8 min readHow I Compile a React Flow Graph So It Actually RunsOn IntegrateX a React Flow canvas stayed inert until I compiled it: a dependency map, a topological sort into a runnable plan, and cycle detection before it runs. 8 min readCompressing the Wire: A 94% Payload Reduction in React FlowNode-graph editors serialize enormous JSON. A custom Serialization Adapter pattern that separates the React Flow render model from the transport record cut IntegrateX payloads by 94%. YK Yaseen Khatib · AI Architect Ships autonomous AI products solo — five in the last twelve months. More about Yaseen → Need an engineer who can build this? I'm Yaseen Khatib — a Senior Full-Stack AI Engineer (MERN + TypeScript) who ships production AI systems solo. Open to senior and lead roles, remote or on-site. Get in touch →See what I've shipped Originally published at yaseenkhatib.streamerosai.com/blog/react-flow-agent-orchestration-canvas/.