WaniWani vs LangGraph

Documentation Index

Fetch the complete documentation index at: https://docs.waniwani.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

TL;DR

​

What each one is

​

When LangGraph is the better choice

• You need an agent that plans, picks tools, and loops over its own output.
• You want multiple LLM calls inside the graph itself, not just a single tool surface.
• You need retrievers, parallel branches, or supervisor patterns.
• Your team is Python-first and the rest of your stack lives in LangChain.
• You are not building for MCP, or MCP is one surface among many.

​

When createFlow is the better choice

• You are building a multi-step MCP tool: sales funnel, lead generation, booking, quote, intake.
• You want deterministic step order with typed validation, not agent improvisation.
• You want to skip the work of wiring an MCP tool around your graph.
• You want state persistence keyed to the MCP session, not a homegrown checkpointer.
• You want widget cards for confirmation steps without inventing a protocol.

​

Side by side: a two-question funnel

from langgraph.graph import StateGraph, START, END
from typing import TypedDict

class State(TypedDict, total=False):
    name: str
    email: str

def ask_name(state):
    # You implement: pause the graph, expose a question to whatever UI is
    # driving, parse the response, validate, re-ask on failure, write to state.
    ...

def ask_email(state):
    # Same again. Validation, re-ask, persistence: all on you.
    ...

graph = StateGraph(State)
graph.add_node("ask_name", ask_name)
graph.add_node("ask_email", ask_email)
graph.add_edge(START, "ask_name")
graph.add_edge("ask_name", "ask_email")
graph.add_edge("ask_email", END)
app = graph.compile()
# You still have to: expose this as an MCP tool, route the MCP session id to
# the checkpointer, decide how interrupts are rendered to the model, etc.

import { createFlow, END, MemoryKvStore, START } from "@waniwani/sdk/mcp";
import { z } from "zod";

const flow = createFlow({
  id: "intake",
  title: "Intake",
  description: "Collect name and email.",
  state: {
    name: z.string().describe("Full name"),
    email: z.string().email().describe("Email address"),
  },
})
  .addNode({
    id: "ask_name",
    run: ({ interrupt }) => interrupt({ name: { question: "What's your name?" } }),
  })
  .addNode({
    id: "ask_email",
    run: ({ interrupt }) => interrupt({ email: { question: "What's your email?" } }),
  })
  .addEdge(START, "ask_name")
  .addEdge("ask_name", "ask_email")
  .addEdge("ask_email", END)
  .compile({ store: new MemoryKvStore() });

await flow.register(server);

​

What you would re-implement on top of LangGraph

1. MCP tool surface. Declare the tool, marshal arguments, route results.
2. Session-keyed state. Map the MCP session id to a checkpointer thread id.
3. Interrupt semantics. Pause the graph, emit a structured question, resume on the next tool call.
4. Validation loop. Re-ask on schema failure without advancing the graph.
5. Auto-skip filled fields. If state already has email, skip ask_email.
6. Widget signals. If you want non-text rendering (cards, pickers), invent a protocol.
7. Multi-field interrupts. Ask several questions in one turn when the model can fill them at once.

​

What createFlow does not do

• No agent loop. A flow is a deterministic graph driven by tool calls, not an LLM-controlled agent.
• No retrieval. Use @waniwani/sdk/kb or your own retriever inside a node.
• No Python. TypeScript only.
• No graph composition primitives (subgraphs, supervisors). A flow is a single graph compiled to a single tool.

​

Migration sketch

1. Replace TypedDict state with a Zod schema map.
2. Replace each node body with either interrupt({...}), a state-returning function, or a widget signal.
3. Replace add_edge and add_conditional_edges with .addEdge and .addConditionalEdge.
4. Replace the checkpointer with a KV store adapter.
5. Call .register(server) instead of wiring an MCP tool by hand.

​

Next