Graph Module — Experimental Feature Notice & Scope of Responsibility

This document must be read before using the euleragent graph module. Please use it only after clearly understanding the characteristics of experimental features and the scope of user responsibility.

1. Experimental Feature Notice

The euleragent graph module is currently provided in an Experimental state. This means the following.

1.1 API Stability

• The Graph module's CLI commands (graph list, graph show, graph validate, graph compile) work in the current version, but may change without notice even in minor version updates.
• The field names, structure, and behavior of the Graph YAML schema may change. In particular, state_schema, parallel_groups, and interrupt_before/after fields are still under design.
• The IR (Intermediate Representation) JSON format generated by euleragent graph compile has not yet been stabilized. Do not build external tools that depend on this format.

1.2 Feature Completeness

Current implementation status (as of 2026-02-23):
  graph list     ✓ Working
  graph show     ✓ Working
  graph validate ✓ Working (includes 14 parallel error codes)
  graph compile  ✓ Working (generates LangGraph StateGraph IR)
  graph run      ⚠ Experimental — unverified in some scenarios
  Parallel exec  ⚠ Experimental — potential race conditions
  interrupt hooks ⚠ Experimental — depends on LangGraph checkpointing

1.3 Backward Compatibility

Experimental modules do not guarantee backward compatibility. It is recommended to re-validate and re-compile Graph YAML files when upgrading versions.

# Always re-validate after version upgrade
euleragent graph validate your_graph.yaml
euleragent graph compile your_graph.yaml --out compiled.json

2. Developer Responsibility Principles

2.1 Non-deterministic Nature of Parallel Execution

Parallel fan-out/fan-in using parallel_groups inherently involves non-deterministic execution.

Branch A ──→ ┐
Branch B ──→ ┤ Join Node
Branch C ──→ ┘

In the structure above, the completion order of branches A, B, and C is not guaranteed. Since each branch runs independently within LangGraph, the order may vary depending on network latency, LLM response speed, and system load.

User Responsibilities: - Do not place order-dependent logic in parallel branches - Do not use the last_write reducer for the same key across multiple branches (non-deterministic results) - Perform sufficient repeated testing before using parallel execution results in production

2.2 Race Condition

LangGraph StateGraph uses shared state. If you do not correctly declare reducers in state_schema, an INVALID_CONCURRENT_GRAPH_UPDATE exception may occur, or data loss may happen.

# Wrong example — last_write is non-deterministic when multiple branches write simultaneously
state_schema:
  findings:
    type: list
    merge: last_write   # Dangerous! Results vary depending on branch completion order

# Correct example — append_list deterministically collects all results
state_schema:
  findings:
    type: list
    merge: append_list  # Safe: all branch results are appended to the list

2.3 Side Effects Prohibited

The following tools are prohibited within parallel branches.

This constraint is enforced by graph validate. If file writing is needed in parallel branches, perform it after the join node.

2.4 Audit Responsibility

euleragent generates audit logs (input.json, messages.jsonl, tool_calls.jsonl, approvals.jsonl) for every execution. However, in parallel execution environments, the order of these logs may be interleaved. When analyzing logs, sort and interpret them by timestamp.

3. LangGraph Version Dependency

The Graph module requires LangGraph 1.0.9 or higher. With lower versions, the StateGraph API behaves differently, causing compilation failure or runtime errors.

3.1 How to Check Version

pip show langgraph | grep Version
# Example output: Version: 1.0.9

3.2 Differences by Version

3.3 euleragent and LangGraph Version Mapping

# Check the LangGraph version required by euleragent
pip show euleragent | grep -A 20 "Requires"

# Or check pyproject.toml / setup.cfg
cat pyproject.toml | grep langgraph

3.4 LANGGRAPH_COMPILE_FAILED Error

When Graph YAML is valid but compilation fails due to LangGraph version mismatch, a LANGGRAPH_COMPILE_FAILED error occurs. This is an environment configuration issue, not a problem with the Graph YAML, so check the LangGraph version first.

# Diagnosis steps when error occurs
euleragent doctor            # Full environment diagnosis
pip show langgraph           # Check LangGraph version
pip install "langgraph>=1.0.9"  # Upgrade if needed
euleragent graph compile your_graph.yaml  # Retry

4. Recommended Use Scenarios

4.1 Suitable Scenarios

Feel free to use the euleragent graph module in the following situations.

4.2 Scenarios Requiring Caution

Use with sufficient validation in the following situations.

4.3 Unsuitable Scenarios

In the following situations, use euleragent pattern instead of euleragent graph.

• When absolute reproducibility is required (e.g., legal audits)
• Simple sequential tasks that do not actually require parallel execution
• Environments where execution without LangGraph is required

5. Safe Usage Methods

5.1 Pre-validation Required

Before executing Graph YAML, you must run graph validate first.

# Step 1: Validate
euleragent graph validate my_graph.yaml

# Step 2: Detailed validation in JSON format
euleragent graph validate my_graph.yaml --format json | python -m json.tool

# Step 3: Verify compilation
euleragent graph compile my_graph.yaml --out compiled.json

# Step 4: Review compilation result
cat compiled.json | python -m json.tool | head -50

5.2 Minimize Parallel Branch Count

As the number of parallel branches increases, debugging difficulty and non-deterministic risk increase.

Recommended: 2-3 branches
Caution: 4-6 branches (thorough testing required)
Risky: 7-8 branches (reconsider if truly necessary)
Limit: Cannot exceed 8 (PARALLEL_BRANCH_LIMIT_EXCEEDED error)

5.3 Careful State Schema Design

state_schema is a core element that determines the safety of parallel execution.

# Recommended design patterns
state_schema:
  # When multiple branches collect results → append_list
  findings:
    type: list
    merge: append_list

  # When multiple branches sum numbers → sum_int
  result_count:
    type: integer
    merge: sum_int

  # When only one branch writes → last_write (single branch only)
  summary:
    type: string
    merge: last_write

  # When two branches write to the same string key → consider concat_str
  combined_text:
    type: string
    merge: concat_str

5.4 Gradual Adoption

When first introducing the Graph module, expand gradually in the following order.

Step 1: Linear graph (no parallel_groups)
   → Works the same as Pattern, only adds LangGraph integration
Step 2: 2-branch parallel (simple state schema)
   → Basic fan-out/fan-in validation
Step 3: Add interrupt hooks
   → Pause at critical nodes, inspect state
Step 4: 3+ branches, complex state (after thorough testing)

6. Support Scope

6.1 Community Support

The euleragent graph module welcomes community contributions.

• Bug reports: Submit to GitHub Issues with the following information
• euleragent version (euleragent --version)
• LangGraph version (pip show langgraph)
• Graph YAML where the problem occurred (with sensitive information removed)
• euleragent graph validate --format json output

• Full error message

• Feature requests: Submit to GitHub Issues with the enhancement label

• Pull Requests: Refer to the contribution guidelines (CONTRIBUTING.md)

6.2 Items Not Supported

The following items are currently outside the support scope.

• Compensation for production failures caused by experimental features
• Compatibility with LangGraph version 0.x
• Complete stability guarantee for the graph run command within the Graph module (currently experimental)
• Nested parallel_groups (only flat structure is supported)

6.3 Issue Submission Template

## Environment
- euleragent version:
- LangGraph version:
- Python version:
- OS:

## Problem Description

## Steps to Reproduce
1.
2.
3.

## Expected Behavior

## Actual Behavior

## Graph YAML (sensitive information removed)
```yaml
...

Error Message

...

```

Summary: 5 Key Principles

1. Validate first — Do not execute Graph YAML without running graph validate.
2. Design reducers carefully — For all state keys shared by parallel branches, prioritize reviewing append_list or sum_int.
3. No side effects — Do not use file.write or shell.exec in parallel branches.
4. Minimize branch count — Start with 2-3 branches and only increase when absolutely necessary.
5. Always verify results — Since parallel execution results can be non-deterministic, include a step in your workflow where a human directly reviews the final output.

Next tutorial: 01_concepts.md — Graph vs Pattern: What's Different?