Skip to content

Build a workflow in the viewer

Instrumenting an agent you already have is a few lines. Starting one from nothing is more typing than that, and most of it is the same every time: a client, a tool loop, tool schemas, a .env for the key, a manifest. The Build page does that part for you, in the language and framework you work in, with GraphMind already wired in, so the first run of a new agent is also its first debugging session.

You work on a canvas. Each node is one thing you can test, and an edge means “this agent can use that”:

NodeWhat it becomes
AgentThe run itself: the model, the system prompt, the task, the step cap. Exactly one.
ToolA function the model can call, with typed parameters. Starts as a stub returning a fixed value.
MCP serverA connection to an MCP server (stdio or HTTP). Its tools join the agent’s list as server_tool. Test connection connects and lists them before anything is generated.
Sub-agentA nested agent the root can delegate to. It takes one task string and runs its own loop with its own tools.

Wire a tool to the agent and the agent can call it; wire it to a sub-agent instead and only the sub-agent can. Everything on the canvas is one node per code location, which is the same unit the debugger draws a run in — so the graph you build and the run you get look like the same object.

Each tool starts as a stub that returns a fixed value, so the project runs end to end before you have written any code, and you replace the stubs in your editor. After that GraphMind has nothing to do with the code: it is plain files in a plain directory, instrumented with the public adapters, and the Build page never edits them again unless you ask it to.

Start the debugger as usual and open the viewer from the link it prints:

Terminal window
npx graphmind-ai

Then click Build a workflow in the run list (or press ⌘K and type “build”, or open http://127.0.0.1:4747/#/build).

  1. Place the nodes. The page opens on an agent with two stub tools. Add a Tool, an MCP server or a Sub-agent from the palette — each arrives wired to the agent you had selected — and drag from a card’s right edge to wire it somewhere else. Click a card to edit it in the Node tab: the agent card also carries the project-level choices (name, language and framework, provider, model). Adding a node wires it to the agent your selection belongs to — select a sub-agent, or anything it owns, and the next + Tool lands on that sub-agent. Names share one namespace and must be valid identifiers in both languages, so a workflow can switch target without renaming anything; a card that has a problem is outlined and says what it is.

    An MCP node has Test connection: the server spawns the command (or calls the URL) exactly as the generated project will, lists the tools it publishes, and disconnects. The tools come back as chips; click one to allow only it. For an HTTP server that needs a bearer token, the field next to the button takes it for that one test — it is used for the connection, scrubbed from anything that comes back, and kept nowhere.

  2. Read what it becomes. The Code tab is the project, file by file, produced in the page by the same generator the CLI uses, so what you read is byte for byte what Create writes — and it is there whether or not a server is running. Copy a file, or everything, if you would rather paste it into a repository of your own and never press Create.

  3. Create the project. By default it goes to ~/.graphmind/workflows/<name> ($GRAPHMIND_HOME if you set one), or an absolute path you type. A directory that already has files is refused unless you tick overwrite generated files, and even then only the generated files are rewritten: your .env and anything you added stay as they were.

  4. Add your key, and say where it may rest. The credentials fields are password fields. What you type is sent once, to the loopback server, with the viewer token. It is never stored in the browser, never written into the spec file next to the code, and never sent back: the page only ever learns that a variable is set. Two choices for where it goes:

    • This session only (the default): the server holds it in memory, hands it to the run’s child process, and forgets it when it exits — or sooner, with Forget, or after eight hours. Nothing is written to disk anywhere, so a key you use once leaves no trace to clean up afterwards.
    • Save to .env: written to the project’s .env with owner-only permissions (0600, git-ignored), so the project also runs from your own terminal later.

    An MCP server over HTTP that needs a bearer token names the variable it should come from (never the token), and the token is asked for here like any other key.

    An Anthropic key that is not scoped to a workspace needs one named: put the workspace’s ID in the optional ANTHROPIC_WORKSPACE_ID field (or .env line) and the generated code sends it as the anthropic-workspace-id header. A workspace-scoped key leaves it empty.

  5. Run it. Install & run does the install once (npm install, or a virtualenv plus pip install) and then starts the project with GRAPHMIND_URL pointing at this server. Its output streams into the page with every .env value, and every secret-named variable the process inherited, replaced by __REDACTED__ before a line is kept. The run itself appears in the run list as it happens; Open the run takes you to it. Errors pause before your code sees them, exactly as for an agent you instrumented by hand.

pnpm dev serves the viewer from Vite on port 5199 while graphmind serve runs on 4747, so the Build page is talking to another origin for the few things that need one (Create, Run, Test connection — the canvas and the code need nothing). One thing makes those work:

  • graphmind serve answers an allow-listed origin’s requests with the CORS header its browser needs (GRAPHMIND_ALLOWED_ORIGINS, which pnpm dev sets for the Vite origin). Without it a browser discards every builder answer. A server with nothing allow-listed sends that header to nobody, which is the default. (The dev server also hands the viewer the running server’s token, so inject and edit work from the hot-reload viewer too.)
ProviderKeyReached by
AnthropicANTHROPIC_API_KEYthe Anthropic SDK targets; the AI SDK target
OpenAIOPENAI_API_KEYthe OpenAI SDK targets; the AI SDK target
Google (Gemini), Mistral, xAI, Groq, DeepSeekGOOGLE_GENERATIVE_AI_API_KEY, MISTRAL_API_KEY, XAI_API_KEY, GROQ_API_KEY, DEEPSEEK_API_KEYthe OpenAI SDK targets, over each one’s OpenAI-compatible endpoint; the AI SDK target, through its first-party @ai-sdk/* package
OpenRouterOPENROUTER_API_KEYthe OpenAI SDK targets (endpoint); the AI SDK target through @ai-sdk/openai-compatible
Ollama (local)none needed (OLLAMA_API_KEY only if yours asks)the OpenAI SDK targets at http://127.0.0.1:11434/v1; the AI SDK target through @ai-sdk/openai-compatible

The provider sets the key the Run tab asks for and the default model; the model is a free field. A target offers the providers its SDK can reach, so switching to the Anthropic SDK moves an OpenAI-family provider back to Anthropic and tells you. The table lives in packages/cli/src/builder/providers.ts; a new provider is one row.

TargetFiles
TypeScript, any frameworkpackage.json, tsconfig.json, src/main.ts, src/tools.ts (+ src/schemas.ts and src/loop.ts for the Anthropic and OpenAI SDKs)
TypeScript, with MCP nodessrc/mcp.ts — one connection per server, its tools listed at startup and exposed as server_tool
TypeScript, with sub-agent nodessrc/agents.ts — one tool per sub-agent, each running its own loop over the tools you wired to it
Pythonrequirements.txt, main.py, tools.py
Every targetREADME.md, .gitignore, .env.example, graphmind.workflow.json (the spec, so the page can list the project; never a secret)

The GraphMind adapter is pinned at the CLI’s own version (^0.6.0 from a 0.6.x CLI), so a project and the server that made it speak the same wire protocol. The provider SDKs are pinned at the floors the adapters are tested against. Node 22.13 or newer; Python 3.10 or newer.

Two things the page handles for you:

  • A server running from a GraphMind checkout has a version that may not be published yet, so its projects would fail at npm install. In that case the adapters come from local tarballs of the checkout’s built packages ($GRAPHMIND_HOME/workflows/.packages/) and the Python SDK from file://<checkout>/python; the preview and the generated README say so. GRAPHMIND_BUILDER_REGISTRY=1 forces the registry pins.
  • Python 3.10 or newer is found, not assumed. macOS ships 3.9 as python3. Run uses GRAPHMIND_PYTHON if you set it, else uv (which finds or fetches an interpreter under its own directory, never touching the system one), else the newest python3.X on your PATH that qualifies. With none, the job fails before anything is spawned and tells you what to install. The page shows which interpreter it will use.

Everything the engineer typed (prompts, descriptions, the stub result) is emitted as a string literal of the language, never interpolated into code, and the generated TypeScript is checked by the test suite against the real ai, @ai-sdk/*, @anthropic-ai/sdk and openai packages.

  • Local only. The Build page talks to the graphmind serve that served it, on loopback, with the viewer token. Nothing is sent anywhere else; there is no account and no hosted side.
  • One level of delegation. The root agent, its tools and MCP servers, and sub-agents with tools and MCP servers of their own. Deeper graphs, routing and retrieval are things you write in the generated code. The page is a starting point, not an editor for what you built from it.
  • An MCP node runs what you typed. A stdio server is a program the generated project spawns — and Test connection spawns it too, from the debugger, under the viewer token, with the MCP SDK’s default environment rather than the debugger’s own. Argv array, no shell, in both places. That is the same trust boundary as Run itself (your machine, your viewer token), but it is worth saying out loud: do not paste a command you would not run in your own terminal.
  • Run runs only what it wrote. The job route starts the fixed install and start commands of a directory that carries graphmind.workflow.json; a directory the builder did not create is refused, and the commands are chosen by the target, not by the request.
  • The key is yours to manage. It lives either in the server’s memory for the session or in the project’s .env, and nowhere else. Rotate it by typing a new one; clear a session key with Forget (or by stopping the server), and a .env key with an empty value or by deleting the line. No response from any route ever carries a value, and the job log is scrubbed of every .env value, every session key and every secret-named variable the process inherited before a line is kept.

Every route is under /api/builder; none needs a credential unless the server was started with GRAPHMIND_BUILDER_REQUIRE_TOKEN=1:

RouteDoes
GET /api/builder/targetsThe targets, the default spec, where projects go
POST /api/builder/preview{spec} → the files Create would write, plus the commands and the variables they need
GET /api/builder/projectsProjects the builder made (and running jobs); variable names only
POST /api/builder/projects{spec, dir?, secrets?, persistSecrets?, overwrite?} → writes the project (and .env, unless persistSecrets: false)
GET /api/builder/projects/env?dir= · POSTWhich variables are set, in .env and in memory (names only) · store new values (persist: false = memory only)
POST /api/builder/projects/env/forgetDrop the session-only keys for a project, now
POST /api/builder/mcp/probe{server, bearer?} → connect to an MCP node as the project would, list its tools, disconnect; the bearer is used once and scrubbed from the answer
POST /api/builder/jobs · GET /api/builder/jobs/:id?after= · POST …/stopRun a project; page its scrubbed output; stop it

The spec’s validation lives in packages/cli/src/builder/spec.ts, the generators under packages/cli/src/builder/codegen/, and the session key store in packages/cli/src/builder/secret-store.ts. The first two are pure TypeScript with no node imports, and the viewer imports them directly (the @workflow alias in apps/viewer/vite.config.ts) so the page can generate and validate without a round trip — there is one definition of a spec, not a server copy and a browser copy. A new target is one generator file plus one entry in the target table; the canvas compiles to a spec in apps/viewer/src/builder/graph.ts.