EZGraph developer guide
EZGraph is a TypeScript layer for durable LangGraph applications, including
one-request extraction workflows, multi-turn chat, and internal model work.
Use the same LlmNode for conversation, nested calls, and sequential or parallel
workers. Each node owns its prompt, tools, configuration, entry/response/error hooks,
and local state; its graph or caller owns execution and continuation.
LangGraph owns execution; EZGraph supplies the contracts that keep a conversation
resumable and auditable.
The node contract has one rule worth remembering:
A node saves the state it owns, then returns an outcome permitted by its execution placement.
Conversational handlers select replies, transitions, or completion. Internal
workers save accepted output in onResponse() and leave continuation to their
caller. await this.runNode(Child1Node, Child2Node) returns child results to the
parent’s current method. fanout(Child1Node, Child2Node) selects concurrent
graph branches; an explicit array-source edge joins them before the next stage.
Read the guide by topic. Start with Nodes and execution, or use the first-graph tutorial for a small complete example.
Nodes and execution
Use one LlmNode contract for conversation, batch input, nested calls, and parallel work, with shared entry, response, and error hooks.
- The node contract
- Choose a node base class
- Prepare input with onEnter
- Handle accepted output with onResponse
- Execution ownership
- Await registered children with runNode
- Nested calls
- LlmRunner and custom execution
State, context, and history
Initialize database clients in your application, choose the initial node, route history, and manage durable node state and graph context.
- Application-owned database initialization
- Initial node and history routing
- Graph-wide runtime context
- State belongs to the node that owns it
Tool responses and transitions
Choose conversational responses, conditional fan-out, or typed task output, and attach explicit state, messages, and usage.
Models, retries, and error handling
Validate model candidates, configure retries, handle blocked responses, and recover with a temporary alternate model.
- Error handling
- Validate candidates before tools run
- Set retry and graph-wide recovery policy
- Inspect failure context and choose a response
- Recover with one temporary alternate model
Graph topology and deterministic policy
Register conversation ownership, schedule internal LLM work, and use conditional fan-out with an explicit join.
- Build topology explicitly
- Conditional fan-out and join
- Await children with runNode
- runNode versus fanout
- Sequential and fixed-entry workers
- Keep policy deterministic
Decision nodes
Declare decision questions, route typed answers in code, and configure Jev providers, fallbacks, and usage.
- Decision nodes with Jev
- Declare questions, then route in code
- What Jev receives
- Configure and register the provider
- Failures, retries, and fallbacks
- Usage and audit
- Porting a PicoFlow DecisionStep
Attachments and testing
Handle temporary file attachments and verify graphs with deterministic tests and opt-in provider evaluation.