Get started with AI agents in React Flow using Liveblocks and Next.js

Liveblocks is a realtime collaboration infrastructure for building performant collaborative experiences. Follow the following steps to add an AI agent that can read and edit a collaborative React Flow diagram from your Next.js /app directory application using mutateFlow from @liveblocks/react-flow, the Vercel AI SDK, and OpenAI.

Live example

See the finished result in the Collaborative Flowchart AI example.

Quickstart

Have a React Flow app ready
To let an AI edit your diagram, you first need a Liveblocks React Flow app set up with secret key authentication. Open up your app, or set up React Flow if you haven’t already.
Get started with React Flow
Install dependencies
Install @liveblocks/node and the Node-side @liveblocks/react-flow entry point, along with the Vercel AI SDK, the OpenAI provider, and zod to validate tool inputs.
Terminal
npm install @liveblocks/node @liveblocks/react-flow ai @ai-sdk/openai zod
Add your environment variables
Create a .env.local file and add your Liveblocks secret key from the dashboard, and your OpenAI API key from the OpenAI dashboard.
.env.local
LIVEBLOCKS_SECRET_KEY=""OPENAI_API_KEY="sk-..."

Create the AI agent

Create a server action that uses mutateFlow to open the room’s flow on the server and let the AI add and update nodes and edges. Each Vercel AI SDK tool maps to one of the MutableFlow methods like flow.addNode, flow.updateNodeData, or flow.addEdge.

app/run-flow-agent.ts

"use server";
import { Liveblocks } from "@liveblocks/node";import { mutateFlow } from "@liveblocks/react-flow/node";import { generateText, stepCountIs, tool } from "ai";import { openai } from "@ai-sdk/openai";import { nanoid } from "nanoid";import { z } from "zod";
const liveblocks = new Liveblocks({  secret: process.env.LIVEBLOCKS_SECRET_KEY!,});
export async function runFlowAgent(formData: FormData) {  const roomId = String(formData.get("roomId") ?? "").trim();  const prompt = String(formData.get("prompt") ?? "").trim();  if (!roomId || !prompt) return;
  await mutateFlow({ client: liveblocks, roomId }, async (flow) => {    await generateText({      model: openai("gpt-4.1-mini"),      system: `You edit a live collaborative React Flow diagram.- Each node has: { id, position: { x, y }, data: { label } }.- Each edge has: { id, source, target }.- Make small, deliberate changes that are easy to follow.- Use 150px horizontal and 100px vertical spacing between nodes.`,      prompt: `<diagram>${JSON.stringify(flow.toJSON(), null, 2)}</diagram><user-message>${prompt}</user-message>`,      tools: {        addNode: tool({          description: "Add a node to the diagram.",          inputSchema: z.object({            label: z.string(),            position: z.object({ x: z.number(), y: z.number() }),          }),          execute: ({ label, position }) => {            const id = `node-${nanoid(6)}`;            flow.addNode({ id, position, data: { label } });            return { ok: true, id };          },        }),        updateNodeData: tool({          description: "Update one node’s label.",          inputSchema: z.object({            id: z.string(),            label: z.string(),          }),          execute: ({ id, label }) => {            if (!flow.getNode(id)) return { ok: false, missing: true };            flow.updateNodeData(id, { label });            return { ok: true, id };          },        }),        addEdge: tool({          description: "Connect two existing nodes with an edge.",          inputSchema: z.object({            source: z.string(),            target: z.string(),          }),          execute: ({ source, target }) => {            if (!flow.getNode(source) || !flow.getNode(target)) {              return { ok: false, missing: true };            }            const id = `e-${source}-${target}-${nanoid(4)}`;            flow.addEdge({ id, source, target });            return { ok: true, id };          },        }),      },      stopWhen: stepCountIs(20),    });  });}

mutateFlow opens the room’s flow for reading and mutating. Any changes made through the flow object are intelligently synced to all connected clients via Storage, so the diagram updates in realtime as the AI works.

Add a prompt form to the page

Now add a small form that lets users describe what the agent should do. It uses useRoom to get the current room ID and passes it to the server action.

app/FlowAgentForm.tsx

"use client";
import { useRoom } from "@liveblocks/react/suspense";import { useState } from "react";import { runFlowAgent } from "./run-flow-agent";
export function FlowAgentForm() {  const roomId = useRoom().id;  const [prompt, setPrompt] = useState("");
  return (    <form action={runFlowAgent} onSubmit={() => setPrompt("")}>      <input type="hidden" name="roomId" value={roomId} />      <textarea        name="prompt"        placeholder="Create a flowchart about…"        value={prompt}        onChange={(event) => setPrompt(event.target.value)}      />      <button type="submit" disabled={prompt.trim() === ""}>        Apply      </button>    </form>  );}

Then render it next to your existing Flow component:

app/page.tsx

import { Room } from "./Room";import { Flow } from "./Flow";import { FlowAgentForm } from "./FlowAgentForm";
export default function Page() {  return (    <Room>      <FlowAgentForm />      <Flow />    </Room>  );}

Next: show the agent in the room
Your AI agent now reads and writes to your React Flow diagram in realtime. Next, give the agent a face—show its avatar in the avatar stack and highlight the nodes it’s editing using Liveblocks presence.
Add AI presence