Give every workflow a contract your team can share.
Your application needs more than graph execution. It needs a consistent way to organize model work, validate tool calls, manage context, recover from errors, and inspect a saved session. EZGraph supplies that application layer.
Seven reasons to use the layer.
These benefits come from how the contracts work together. You can build the same policies directly on LangGraph; EZGraph gives your team a supplied convention to reuse.
Reusable nodes with a predictable lifecycle.
An LlmNode keeps a stage's prompt, tools, accepted output, and state behavior together. Entry, response, exit, and recovery hooks provide explicit places to customize the lifecycle.
That structure gives code review and maintenance a repeated pattern: learn where one node puts its responsibilities, then find them in the next.
onEnter(), checkResponse(), onResponse(), and onExit() have distinct timing and responsibilities.
Tools scoped to the current job.
Declare a node's tool schemas and bind its handlers. A collector can expose collection tools; another stage can expose confirmation tools. The model works within the actions offered by the active stage.
Schema checks run before dispatch. Your handler then applies domain validation and authorization, saves accepted facts, and returns an explicit outcome. Narrower tool scope reduces the choices the model must make; evaluate the effect on your own scenarios.
Invalid arguments become corrective feedback and diagnostics. stay() lets a handler ask the model to repair a rejected input.
A human-readable session document.
Inspect the active stage, saved business facts, shared context, named histories, usage, warnings, errors, and decision records in one application document.
It gives debugging and incident triage a consistent starting point. An AI assistant can analyze a selected record alongside the node code. Model behavior and external effects still need their own evidence.
The document is an application session snapshot. LangGraph checkpoints provide a different execution and recovery boundary.
Sessions and checkpoints →Model policy declared with the graph.
Set a graph's default model and supported parameters through ModelCatalog. Nodes can override the model or patch parameters when a stage needs a different policy.
Catalog validation catches unsupported configuration early. Model selection, retries, timeouts, and recovery settings have established homes instead of being spread across unrelated call sites.
A parameter patch updates inherited parameters. A full model replacement brings its own parameters. The contract makes the distinction visible.
Models and error handling →History sharing defined deliberately.
historySpaces declares which nodes share a conversation history. Keep intake, review, and confirmation isolated, or assign related stages to the same space.
Facts remain in typed node state and graph context, so the application can carry accepted data forward without relying on a model to rediscover it from the dialogue.
Node state owns accepted facts. Graph context owns shared facts. Named histories supply the dialogue each stage sees.
State, context, and history →Guided conversations with less plumbing.
A common turn contract handles model/tool rounds, corrections, handoffs, direct replies, and completion. You write the stages and their business rules; the engine coordinates sessions around each user turn.
go() enters another stage in the current turn. direct() returns exact content while the node stays active. directTo() replies now and chooses where the next turn resumes. finish() completes the graph.
QuoteGraph collects facts, handles ambiguity and revisions, calculates a quote in code, and records explicit acceptance.
QuoteGraph walkthrough →Local recovery with shared graph policy.
Handle provider errors, blocked responses, retry decisions, and empty candidates through standardized hooks and configuration. A node can recover locally; a graph fallback supplies shared behavior.
checkResponse() can reject a candidate before tool dispatch. Keep retry and recovery decisions reviewable, and use scripted providers to exercise failure paths reproducibly.
onLlmError() and onLlmBlocked() let stages specialize the graph's policy. Returning true from checkResponse() rejects the candidate.
Fifteen decisions your team can standardize.
Several of these concerns already have LangGraph or LangChain helpers. EZGraph's value is a coherent convention spanning the application lifecycle.
| Application decision | Supplied convention | Contract reference |
|---|---|---|
| 1. Organize an LLM stage | Prompt, tools, state, and lifecycle behavior in an LlmNode. | Node contract |
| 2. Select stage tools | Explicit tool definitions and bound handlers for each node. | Tool handling |
| 3. Reject invalid arguments | Schema validation, corrective tool feedback, and warnings. | Validation example |
| 4. Set model policy | Graph defaults and node overrides. | Model policy |
| 5. Validate parameters | Catalog profiles and supported-parameter checks. | Catalog validation |
| 6. Share dialogue | Declarative historySpaces. | History spaces |
| 7. Own application facts | Typed node state, graph context, and staged writes. | State ownership |
| 8. Reply, hand off, or finish | Common response and transition builders. | Response builders |
| 9. Reject a model candidate | checkResponse() before tool dispatch. | Response lifecycle |
| 10. Recover from LLM errors | Node recovery with graph fallback. | Recovery hooks |
| 11. Turn classifications into decisions | Typed DecisionNode answers; policy stays in code. | Decision nodes |
| 12. Obtain worker or judge results | Typed runNode() results with caller-owned publication. | Child execution |
| 13. Inspect an incident | A common session document with state and diagnostics. | Session record |
| 14. Evolve saved sessions | Schema versions, migrations, and restore hooks. | Session evolution |
| 15. Test a complete turn | Scripted providers and a real-engine turn harness. | Testing contracts |
Make the first change small and reviewable.
Try a new workflow, or adapt a focused part of an existing application. Keep the business rules you trust, then test the node and session contracts around them.
Put the stage in a node.
Move its system prompt to getPrompt(), tools to defineTool(), and domain validation into bound handlers. Map accepted fields to typed node state.
Make the policies visible.
Set model defaults, history sharing, response outcomes, and graph registration. Adapt session storage and restore behavior to the application's actual needs.
Run real engine turns.
Script the happy path, malformed tool arguments, corrections, and failures. Inspect the saved document, then evaluate the same journey with a live model.
The current default uses request/response turns and application session snapshots. Check requirements for streaming, checkpoint continuation, and custom topology in the architecture comparison.
Give your next LangGraph application a consistent foundation.
Run the starter, inspect the session, and decide whether the node contract fits your team.