Graph Module Tutorial — Table of Contents

⚠️ Experimental Warning

The euleragent graph module is currently in an experimental state. The API, YAML schema, and behavior of this module may change without notice even in minor version updates. You are free to use it for research and prototyping purposes, but if applying it to production mission-critical systems, please ensure thorough testing and validation before use.

⚠️ Parallel Execution Caution

Parallel fan-out/fan-in execution using parallel_groups can lead to race conditions, non-deterministic results, and unexpected LangGraph internal behavior. When parallel branches access shared state keys, you must declare appropriate reducers. Complete pre-validation using the euleragent graph validate command before execution. The responsibility for verifying all parallel execution results lies with the user.

Tutorial List

Tutorial Descriptions

00_disclaimer.md — Experimental Feature Notice (Must Read)

This is a mandatory notice document that must be read before using the Graph module. It explains the scope of experimental features, developer responsibility principles, LangGraph version dependencies, and safe usage methods.

01_concepts.md — Graph vs Pattern Concepts

Explains the relationship between Pattern and Graph. Graph is a complete superset of Pattern, covering what has been added (state_schema, parallel_groups, interrupt hooks, LangGraph integration) and the YAML-to-LangGraph compilation pipeline.

02_linear_graph.md — Linear Graph

Write the simplest Graph YAML without parallel features. Verify the LangGraph compilation result and compare with Pattern.

03_judge_route.md — Judge Routing

Implement 2-route and 3-route judge patterns in Graph. Understand the process of compiling to LangGraph's add_conditional_edges.

04_bounded_loop.md — Bounded Loops

Learn how to safely bound loops with max_iterations. Demonstrates the UNBOUNDED_CYCLE error.

05_interrupt_hooks.md — Interrupt Hooks

Pause execution at specific nodes using interrupt_before and interrupt_after. Understand the difference from the HITL force_tool approach.

06_state_schema.md — State Schema Details

Fully understand the combinations of 5 types and 5 merge strategies. Covers the compilation process to LangGraph reducers and the type+strategy compatibility table.

07_parallel_basics.md — Parallel Execution Basics

Create the simplest fan-out/fan-in pattern with 2 branches. Directly demonstrates parallel-related error codes.

08_parallel_advanced.md — Advanced Parallel Patterns

Covers 3 or more branches and complex state design. Master the use of independent state keys per branch and safe merge strategies for shared keys.

09_parallel_with_quality.md — Comprehensive Example (Capstone)

Create a production-level graph combining parallel fan-out/fan-in with a Judge quality loop. Integrates all concepts learned so far.

10_reference.md — Complete Reference

Provides the complete Graph YAML field table, error code list, type+merge compatibility matrix, and safe parallel design checklist.

Recommended Learning Path

Must Read: 00_disclaimer.md
        ↓
Concepts: 01_concepts.md
        ↓
Basic Practice: 02_linear_graph.md → 03_judge_route.md → 04_bounded_loop.md
        ↓
Intermediate: 05_interrupt_hooks.md → 06_state_schema.md
        ↓
Parallel Execution: 07_parallel_basics.md → 08_parallel_advanced.md
        ↓
Comprehensive: 09_parallel_with_quality.md
        ↓
Reference: 10_reference.md (refer as needed)

If you are a complete beginner, we recommend following the files in order, one at a time. If you have already completed the Pattern tutorials, you can check the differences in 01_concepts.md and then start from 06_state_schema.md.

Prerequisites

Before starting the Graph module tutorials, make sure you have completed the following.

Required Tutorials

• docs/tutorials/basic/01_*.md — Basic euleragent installation and CLI usage
• docs/tutorials/pattern/01_*.md — Understanding Pattern concepts
• docs/tutorials/pattern/02_*.md — Writing Pattern YAML
• docs/tutorials/pattern/03_*.md — Pattern validate and execution

Required Software

# Python 3.10 or higher
python --version

# Install euleragent (editable mode)
pip install -e .

# Check LangGraph version (1.0.9 or higher required)
pip show langgraph | grep Version

# Verify graph module availability
euleragent graph --help

LangGraph Version Information

This tutorial is written based on LangGraph 1.0.9 or higher. LangGraph's StateGraph API may vary by version, and the following methods in particular may have different signatures across versions.

# Install/upgrade LangGraph
pip install "langgraph>=1.0.9"

# Verify installation
python -c "import langgraph; print(langgraph.__version__)"

Graph Module CLI Quick Reference

# List available graphs
euleragent graph list

# View graph structure
euleragent graph show <path_or_ID>

# Validate graph
euleragent graph validate <path_or_ID>
euleragent graph validate <path_or_ID> --format json

# Compile to LangGraph IR
euleragent graph compile <path_or_ID>
euleragent graph compile <path_or_ID> --out compiled.json

Example File Locations Used in This Tutorial

YAML files written in the tutorials are organized under examples/graphs/ in the working directory.

examples/graphs/
  linear/        # Linear graph examples
  loops/         # Loop pattern examples
  parallel/      # Parallel pattern examples
  capstone/      # Comprehensive examples

Each tutorial specifies file paths, so you can create them as instructed.