Twenty-three examples, each with the graph it compiles to

The pattern

The only straight line in the gallery — no branch, no cycle, no tool, no mount. It exercises exactly one thing: an agent's prompt port accepting an upstream agent's result, which is the port-level widening every longer chain is built on.

Behind the scenes

Each agent.llm compiles to a create_agent loop added with add_node, wired by four static edges — no conditional edge is emitted because nothing decides anything. The compiler adds LangGraph's __start__/__end__ terminals and a default error handler.

True and worth knowing: the smoke run kept both stages in the run's outputs map, at 532 characters and 134 characters. A chain does not throw the intermediate away, which is what makes a chain debuggable and a single mega-prompt not.

Use it

$ openstategraph examples copy chained-summarizer
$ openstategraph run ./workflows/chained-summarizer "Summarise what a state machine is, then cut it to one sentence."

Asked

“Summarise what a state machine is, then cut it to one sentence.”

Answered

One sentence, no preamble — “A state machine is a model that defines a system's possible states and the rules for transitioning between them in response to inputs.”

from openstategraph import load_workflow

wf = load_workflow("workflows/chained-summarizer")
print(wf.ask("Summarise what a state machine is, then cut it to one sentence."))

The pattern

Fan-out with a single worker archetype: the same role run several times in parallel, once per subtask the supervisor planned. The join is deterministic and costs nothing, because no model runs in it — contrast example 5, which fans out to different roles.

Behind the scenes

orchestrate.supervisor compiles to a conditional edge returning a list of Send objects, one per subtask, so LangGraph schedules the worker node several times in one superstep. function.format_report is a plain Python node that reads state["worker_results"] keyed by subtask id — it never looks at its incoming edges at all.

An honest finding this example produced: the supervisor splits a brief with a regex, not a model. Asked for “two arguments for and against daily standups”, it cut on the word “and”, so subtask 1 was “Give me two arguments for” and the worker asked what about. The report's shape was exactly right and its content was not — which is why this example exists at the front rather than buried in something larger.

Use it

$ openstategraph examples copy parallel-workers-join
$ openstategraph run ./workflows/parallel-workers-join "Give me two arguments for and against daily standups."

Asked

“Give me two arguments for and against daily standups.”

Answered

A # Standup arguments report with exactly two ### sections, in task-id order — the join is ordered, and it is ordered without a model.

The pattern

The only pure-routing example: three mutually exclusive terminal branches, no grader and no loop. One router call plus exactly one agent call per run, which makes it the cheapest way to see what a conditional edge actually costs.

Behind the scenes

route.classifier compiles to add_conditional_edges with a path map from branch id to node name — the three dotted edges above. Each branch gets its own output.formatted on purpose: an input port is maxConnections: 1, so two branches converging on one output is a graph you can load but cannot redraw.

The smoke run is the demonstration: asked the time in Tokyo it routed to b-world and said it has no clock. decisions came back as {"router1": "b-world"} and outputs held one agent entry — the other two branches were never scheduled, so you pay for one model call, not three.

Use it

$ openstategraph examples copy classifier-router-qa
$ openstategraph run ./workflows/classifier-router-qa "What time is it in Tokyo?"

Asked

“What time is it in Tokyo?”

Answered

A short answer explaining it has no clock, on the world_facts branch — and answer.decisions naming the branch it took.

The pattern

The canonical two-node cycle, and the gallery's reference for the claim that a loop here is two edges rather than a different kind of tool. A drafter produces, a grader judges, and grader.revise lands on agent.feedback.

Behind the scenes

The grader compiles to a conditional edge with two destinations — the output on pass, the drafter on revise — so the cycle is a cycle in the StateGraph itself, not a wrapper around one. A loop is drawable only because revise is a feedback-typed port: the acyclic rule returns early for exactly that type, which keeps an accidental cycle inexpressible while this one is two clicks.

What the smoke run recorded is the case people forget to test: the first draft passed. attempts: 1, decisions {"grader1": "pass"} — the revise edge was available and unused. A revision loop that never revises is still the right graph.

Use it

$ openstategraph examples copy evaluator-optimizer
$ openstategraph run ./workflows/evaluator-optimizer "Write a two-sentence release note for a bug fix."

Asked

“Write a two-sentence release note for a bug fix.”

Answered

Two sentences — the defect, then the fix — with no marketing language, passed on the first attempt.

The pattern

Heterogeneous workers: the supervisor labels each subtask with an archetype and the Send dispatch picks the matching worker node. A subtask it leaves unlabelled degrades to the default worker — and that degradation is part of the demo, not an accident.

Behind the scenes

One conditional edge emits a list of Sends addressed to different node names; both worker nodes write into the same worker_results state key, which is why that key carries a named reducer rather than being a bare field. Two writers in one superstep is precisely the situation a plain LastValue field cannot survive.

The most useful thing this example produced is a gap, recorded rather than hidden: the run came back with decisions {}. Which archetype handled which subtask is not surfaced anywhere in a run result — on a graph like this one, that is the difference between an answer from the researcher and one from the writer, and you currently cannot tell.

Use it

$ openstategraph examples copy archetype-orchestrator-report
$ openstategraph run ./workflows/archetype-orchestrator-report "Plan a 30-minute onboarding session for a new engineer."

Asked

“Plan a 30-minute onboarding session for a new engineer.”

Answered

A usable # Onboarding plan — but from a single subtask, because the brief carried no separator for the splitter to cut on. Recorded as it happened.

The pattern

Two independent cycles in series, each grader with its own criteria and its own ceiling — an engineer's changelog graded on accuracy, then a customer rewrite graded on readability. Serial by necessity rather than taste: agent.feedback takes one link, so two revise edges onto one agent would swap rather than stack.

Behind the scenes

Two conditional edges, two cycles, and the second stage's entry is the first grader's pass destination — so “stage one is finished” and “stage two begins” are the same edge. Nothing sequences them but the graph.

This example falsified its own design note, which is why it is worth reading. It was written expecting two counters advancing independently; the run returned attempts: 4 from one graph-wide counter. So two maxAttempts values are two ceilings on a single number, not two budgets — a distinction that only shows up when both loops actually run.

Use it

$ openstategraph examples copy two-stage-double-loop
$ openstategraph run ./workflows/two-stage-double-loop "Draft a changelog entry, then make it customer-readable."

Asked

“Draft a changelog entry, then make it customer-readable.”

Answered

Two customer-facing sentences with no component name and no use of the word “bug”; both graders passed, each cycle having run once.

The pattern

The only example whose grader never passes: its criteria contradict each other on purpose. It terminates on the graph's own attempt counter and ships the last candidate anyway, which is what a loop must do when the work is not good enough and stopping is still the right answer.

Behind the scenes

The same two-destination conditional edge as example 4. What stops the run is the attempt counter in graph state, not LangGraph's recursion_limit — which is the point. Revisions and supersteps are different units, and only one of them is yours to set.

It terminated cleanly with attempts: 2 == maxAttempts and no GraphRecursionError. It also exposed something worth knowing before you trust a verdict: the forced stop records decisions {"grader1": "pass"} with warnings: [] — indistinguishable, from the outside, from a draft that genuinely passed.

Use it

$ openstategraph examples copy budget-exhaustion
$ openstategraph run ./workflows/budget-exhaustion "Answer in exactly seven words: why is version control useful?"

Asked

“Answer in exactly seven words: why is version control useful?”

Answered

“Tracks changes, enables collaboration, prevents data loss.” — the last candidate, shipped after the budget ran out rather than after a pass.

The pattern

The one loop whose revise edge reshapes the question instead of the answer, so the cycle re-enters retrieval rather than generation. Wiring order is load-bearing: the rewriter must sit upstream of the retriever, because an agent's prompt port takes exactly one edge.

Behind the scenes

A knowledge-lookup tool atom binds to the retriever's tools bus, and the grader's conditional edge points back two nodes rather than one. Nothing in the compiler asks whether the target of a revise edge produced the candidate — which is what makes this shape legal.

It was an open design question whether that should be legal, and the live run answered it: yes. Lap one asked a question aimed at a topic that does not hold the figure and got “the handbook does not”; the rewrite re-aimed it, and lap two came back grounded in the escalation-paths document with a quoted value. Feeding the feedback to the answer's producer would have re-run the same lookups against the same framing.

Use it

$ openstategraph examples copy agentic-rag-rewrite
$ openstategraph run ./workflows/agentic-rag-rewrite "How do I get something fixed fast?"

Asked

“How do I get something fixed fast?” — deliberately vague, and unanswerable as phrased.

Answered

Two laps, one rewrite: an answer grounded in the store's escalation-paths topic, quoting a value that exists only in the package's own knowledge/ directory.

The pattern

A grader that rejects the joined report sends the whole plan back to the supervisor, not the prose back to a writer. It is the teaching example for the superstep-versus-lap distinction, and the only one that uses the supervisor's feedback input.

Behind the scenes

Two conditional edges in one cycle: the supervisor's Send dispatch and the grader's verdict. The join and the grader are separate nodes on purpose — the join has no model in it, so a rejected lap re-plans and re-runs the workers without re-paying for the assembly.

Measured, not estimated: 14 supersteps for two laps. That is the four-per-lap arithmetic the example exists to show, and the reason the step budget must never be labelled “max iterations” — you would set it to 2 and it would stop halfway through the first lap.

Use it

$ openstategraph examples copy fanout-in-a-loop
$ openstategraph run ./workflows/fanout-in-a-loop "Compare two ways to deploy a Python service, then judge which is safer."

Asked

“Compare two ways to deploy a Python service, then judge which is safer.”

Answered

A # Deployment comparison with three task-id-ordered sections, the last opening “Managed container platform is safer to operate.” — one re-plan, then a genuine pass.

The pattern

The only cycle a person closes. human.approval.rejected is a feedback-typed output, so a rejection routes to agent.feedback exactly as a grader's revise would — the port type is the whole reason the two are interchangeable here.

Behind the scenes

The approval node compiles to LangGraph's interrupt(), so a paused run is a durable checkpoint rather than a thread parked in memory. The resume payload is approve or reject plus optional feedback, and the graph continues from the checkpoint — including across a process restart.

Smoked through the HTTP API rather than the CLI, because a pause needs an answer: POST /api/runs refused with the documented 409, /api/runs/stream paused with an interrupt frame carrying {message, candidate}, a resume with reject plus feedback produced a redraft and paused again, and a resume with approve shipped it. Today the CLI can watch an approval but not answer one.

Use it

$ openstategraph examples copy approval-in-the-loop
$ openstategraph run ./workflows/approval-in-the-loop "Draft a one-line apology to a customer whose order was late."

Asked

“Draft a one-line apology to a customer whose order was late.”

Answered

The run pauses with the candidate in the interrupt payload. Reject with a note and the drafter tries again; approve and the answer ships.

The pattern

The only example where neither the agent's rules nor the grader's criteria are typed on a card: both arrive over the skill port from one Markdown file. One input.skill output feeding two skill inputs is the shape that proves the skill layer is a layer rather than an agent field.

Behind the scenes

The skill contributes the rules section of each node's composed prompt — the only editable section. The preamble that says what the node is, the generated context, and the output contract are the base's, and the contract goes last so a rule like “explain your reasoning” cannot countermand the shape of the answer. Both nodes are in replace mode, so the file is the source and nothing else contributes.

The control run is the real evidence, and it points the other way: the same question against a copy with the skill node deleted came back with bullets, a **Title:** label, <module/component> placeholders and a Closes: #<issue> footer — four of the skill's explicit prohibitions — and the grader passed it. Unwiring the rules removes the check in the same move.

Use it

$ openstategraph examples copy skill-driven-rubric
$ openstategraph run ./workflows/skill-driven-rubric "Write a commit message for a fix to a null-pointer crash."

Asked

“Write a commit message for a fix to a null-pointer crash.”

Answered

A message obeying rules that exist nowhere but the skill file — an imperative subject line under fifty characters with no full stop, three prose sentences, no bullets, no footer.

The pattern

Retrieval as a plain tool binding, with the package's own knowledge/ directory as the store and no loop around it. It pairs with example 8, which grades what this one merely fetches.

Behind the scenes

A tool atom is not a node in the compiled graph — it binds to the agent, so the whole retrieval happens inside one create_agent loop and the diagram stays four boxes. Deliberately not vector search: the store is three-tier progressive disclosure over Markdown topic docs, one index line per topic, the full document fetched only once the agent commits to that direction.

The store is fictional on purpose — a seed vault that does not exist — so no figure can arrive from the model's weights. It answered “every 20 years” and “below 70 %”, both correct and both unguessable, and threads show replays the two tool calls behind them without calling a model to reconstruct the story.

Use it

$ openstategraph examples copy knowledge-lookup-qa
$ openstategraph run ./workflows/knowledge-lookup-qa "How often is seed viability tested, and what triggers a regeneration?"

Asked

A question only the package's own topic docs can answer.

Answered

“every 20 years” and “below 70 %”, naming the topic it read them from — with the tool calls visible in the run rather than a confident recollection.

The pattern

Find what is trending right now, read the top video's actual transcript, and hand both to a different provider for a three-sentence synthesis. The only multi-provider example, and the only one whose acceptance test is external reachability rather than a shape.

Behind the scenes

A chain of three create_agent loops with different tool bindings — search and fetch on the first, the transcript atom on the second, none on the third — and a model string on one node that names Anthropic while the graph's setting names Ollama. Provider is a field on a node, so a two-provider graph needs no second runtime, no adapter and no special node type.

End to end, measured with an in-process usage callback rather than estimated: a live trend found, a 1 140-character transcript fetched, and a Claude synthesis that quoted two phrases from the captions and named a character who appears nowhere but them. 9 221 tokens on gpt-oss:120b plus 1 627 on claude-haiku-4-5 — $0.0022, in 23.8 seconds.

And the honest half: an earlier run found nothing, because the single search backend was answering every request with a challenge, and two of the three rungs of this workflow are that tool. It burned 61 832 tokens producing no digest. That is recorded as a gap with an evidenced fallback, not smoothed over with a stub.

Use it

$ openstategraph examples copy youtube-trend-digest
$ openstategraph run ./workflows/youtube-trend-digest "What is trending on YouTube right now?"

Asked

“What is trending on YouTube right now?”

Answered

Three sentences about a specific video that was two hours old, grounded in phrases from its transcript — not a generic essay about the topic.

The pattern

Natural language to SQL over a real database, using the generic prebuilt SQL atoms: list the tables, read one schema, run one read-only SELECT. Nothing in it is specific to the sample database except the file the three nodes point at.

Behind the scenes

Three tool atoms bind to a single agent, so the list-then-schema-then-query sequence is the agent's own tool-calling loop rather than three graph steps — the compiled graph is four boxes for a job people usually draw as a pipeline. The package carries its own copy of the database under data/, and paths are resolved relative to whichever workflows root holds the package, so the copy works wherever you put it.

This is the one example a machine grades. Its evals/ directory holds five cases scored by execution accuracy — the answer's result set compared with a gold query's, not its wording — and it scored 100.0%: four of four on execution accuracy and exact set match, one of one on a question it was right to refuse, p50 5.04 seconds. The hard two-join case returned the gold row USA, 523.06.

Grading a run and grading a dataset are different jobs done by the same machinery — a grader's verdict is an edge, an eval's verdict is a destination. The difference is written up in docs/evaluation.md.

Use it

$ openstategraph examples copy sql-qa
$ openstategraph run ./workflows/sql-qa "How many customers are in the database?"
$ python -m pytest ./workflows/sql-qa

Asked

“How many customers are in the database?”

Answered

59, with SELECT COUNT(*) … FROM Customer shown underneath it.

The pattern

The only example whose tools leave the machine, and therefore the only one with a documented network-failure shape. One agent loops over search and fetch until it has a source it actually read; a grader that can tell a digest from a recollection sends it back when it has not.

Behind the scenes

Two tool atoms on one agent plus one grader cycle — contrast example 20, which spends more calls to reach several sources at once. The interesting compile detail is what is not here: retry and timeout are parameters of graph assembly, available to every node of every family, so a flaky fetch is not a reason for a tool base class to grow a retry field.

Two runs, two things proven. The first named Python 3.14.7, released 8 August 2026, with two fetched URLs and a count of 499 bug fixes — a figure that exists on the page and in no model's weights — after one revise lap. The second was the real test: asked to read an unresolvable host, it quoted “That host is not reachable from here” and answered nothing. A readable tool error, never a silent stub.

Use it

$ openstategraph examples copy web-research-digest
$ openstategraph run ./workflows/web-research-digest "What changed in the most recent Python release?"

Asked

“What changed in the most recent Python release?”

Answered

A short digest naming the release, its date and its bug-fix count, with the URLs it fetched — and attempts: 2, so the first draft was sent back.

The pattern

The longest control chain the vocabulary can express: a classifier picks a desk, the desk answers, a grader checks the reply, and a person decides whether it is sent. Nothing reaches a customer without the gate.

Behind the scenes

Two conditional edges and an interrupt(), with two terminal outputs — one for sent, one for held. It is also as close as the current vocabulary gets to a handoff, and the boundary is worth naming: a router picks a branch and the branch runs; an agent cannot hand a live conversation to another agent.

One limit this example cannot design around, and one it exposed. Three desks fanning into one grader means the grader has no expressible revision loop — agent.feedback takes one link, so a revise verdict falls through to the first declared destination. The second is fixed: the person at the gate used to be shown the draft alone, so the interrupt payload now carries verdict and reason from the grader that produced the candidate — the judgement it reached, not the branch it routed down.

Use it

$ openstategraph examples copy support-triage
$ openstategraph run ./workflows/support-triage "My invoice is wrong and nobody has replied for a week."

Asked

“My invoice is wrong and nobody has replied for a week.”

Answered

Routed to billing, drafted, graded, and stopped at the gate. Rejecting with a note produced the held-ticket record; approving on a fresh thread sent it.

The pattern

The only fan-out whose workers carry tools: the open web, this package's own handbook, and the platform's own workflow list. Distinct from example 5, where the archetypes differ by role rather than capability, and from example 18, where one agent loops over tools instead of several agents each owning one.

Behind the scenes

A Send dispatch to three differently-equipped workers, each also reading its rules from one shared input.skill — a worker has no authorable prompt of its own, so a single skill file steers all three. They land in one worker_results key and a model-free join assembles the brief.

The smoke question is a bare numbered list, and that is not a stylistic choice: the planner splits on a regex, so the question's shape decides the plan. All three workers ran with their own tool. The section that stayed honest when a tool misbehaved was the section the skill was steering.

Use it

$ openstategraph examples copy morning-brief
$ openstategraph run ./workflows/morning-brief "1. What changed in Python recently? 2. What is our release checklist? 3. What workflows are installed?"

Asked

Three numbered questions, one per source.

Answered

A # Morning brief with three task-id sections, each visibly produced by its own tool — web, handbook, platform.

The pattern

A user gives an email address so a customer can be looked up. Inbound, that address must pass — the tool matches on the exact string, and a redacted one finds nothing. Outbound, the same entity is redacted, because what comes back is data the user never supplied. Nothing on either guard.policy card knows which direction it is; the wire does. A credit_card → block row on the inbound card is the other half: a refusal leaves by its own blocked port and reaches a dedicated Output, and no model is called at all.

Behind the scenes

Detection is borrowed, never written: LangChain's own RedactionRule shapes — email, credit_card (Luhn-checked), url — plus a hand-written regex for phone, which LangChain does not ship. pass is the one strategy the library has no opinion about, added so an inbound entity the product needs can be named rather than silently unhandled. A guard's verdict is a value, not an exception: the compiler turns it into a conditional edge, so a block short-circuits before the agent ever runs.

True and worth knowing: the redact run took 2.4 s and left outputs["in1"] holding the address exactly as typed, while outputs["agent1"] shows [REDACTED_EMAIL] in its place — proof the tool saw the real address and only the agent's answer was scrubbed. The block run took 0.0 s: no model runs, and the card number is gone from every outputs entry, including in1, which a redaction would have left alone.

Use it

$ openstategraph examples copy guarded-lookup
$ openstategraph run ./workflows/guarded-lookup "What plan is bjorn.hansen@yahoo.no on, and how do I reach him?"

Asked

“…full contact details on file for ftremblay@gmail.com, including their email address.”

Answered

“François Tremblay lives in Montréal, Canada, is on the Premium plan, and can be reached at **** 721‑4711. Their support ticket is [REDACTED_URL] and their email is [REDACTED_EMAIL].”

The pattern

A memory.segment node sits between the question and the agent. Every time flow reaches it, it does three things in this order: furnishes the entries the segment already holds into what flows onward, records what just arrived, verbatim, and passes both on. Furnish before record, deliberately — the other order hands the agent its own question back inside the block it is reading, which looks like a duplicate and is really a lie about when the line was written. Wire the same node off to one side and it records nothing, because nothing crosses it. Position is the mechanism.

Behind the scenes

The ledger is keyed by the segment's name (what-you-told-me) and by the workflow, in the durable Store — not the checkpointer, which is the thing that carries a conversation and is exactly what this example does without. Two tollbooths carrying the same name are one ledger, read and appended at both positions. retention is 20: bounded on purpose, because this package gets copied into somebody's own workflows root and grows in their Store. Blank means unbounded and is perfectly legal; a shipped example is the wrong place to demonstrate it.

True and worth knowing: no model is reachable from the write path, so a crossing costs zero tokens — by construction, not by discipline. And the card deliberately shows no entry count: the ledger is server-side, so a card cannot know its size before a run. It shows the name and the retention, both true with nothing having happened, and the count is furnished by the run itself.

Use it

$ openstategraph examples copy remembers-across-runs
$ openstategraph run ./workflows/remembers-across-runs "My favourite composer is Sibelius, and I always take my coffee black." --thread-id run-one
$ openstategraph run ./workflows/remembers-across-runs "Who is my favourite composer, and how do I take my coffee?" --thread-id a-completely-different-thread

Run 1 · empty ledger

“Thanks for sharing!”

Run 2 · a thread that has never seen run 1

“Your favourite composer is Sibelius, and you always take your coffee black.”

The thread ids differ, so the checkpointer holds nothing from run 1. Everything the second answer knows arrived in the block the memory node furnished. Recorded 2026-08-15 on ollama:gpt-oss:120b-cloud.