[recipe] fix: make LangGraph agent example runnable out-of-the-box

[philippnormann]

What does this PR do?

Fixes the LangGraph agent recipe so it runs out-of-the-box across different environments. The original example had undefined variables and brittle error handling that caused failures. This PR makes it portable, robust, and self-contained. No breaking API changes.

Checklist Before Starting

• Search for similar PRs: https://github.com/search?q=repo%3Avolcengine%2Fverl+langgraph++&type=pullrequests&state=open

• Format PR title as [recipe] fix: make LangGraph agent example runnable out-of-the-box

  • {modules}: recipe
  • {type}: fix
  • No breaking API changes

Test

✅ End-to-end validation:

# 1. Generate dataset (parameterized)
python recipe/langgraph_agent/example/create_dataset.py --train_size 1000 --test_size 100

# 2. Run training (no modifications needed)
bash recipe/langgraph_agent/example/run_qwen2.5_3b.sh

# 3. SLURM submission (headers included)
sbatch recipe/langgraph_agent/example/run_qwen2.5_3b.sh

Note on GPUS_PER_NODE and NNODES:

• GPUS_PER_NODE: GPUs per node.
  Detection order: SLURM_GPUS_ON_NODE (if set) → GPUS_PER_NODE → 2.
• NNODES: number of nodes.
  Detection order: SLURM_JOB_NUM_NODES (if set) → NNODES → 1.
• Total GPUs = GPUS_PER_NODE × NNODES (must be ≥ 2).

Local override (no SLURM_* set):

GPUS_PER_NODE=4 NNODES=2 bash recipe/langgraph_agent/example/run_qwen2.5_3b.sh

Results:

• Model converged to 100% validation accuracy (val-core/lighteval/MATH/reward/mean@4: 1.0)
• Stable metrics: policy loss, entropy, critic scores all normal
• No crashes or hangs during run
• Robust handling of malformed tool-call JSON (logs warnings)
• Model path fallback works when local model missing
• SLURM detection + fallbacks confirmed

API and Usage Example

No breaking API changes. Dataset generator now has a CLI interface:

# Defaults: 5000 train, 500 test → data/math_expression_tool/
python recipe/langgraph_agent/example/create_dataset.py

# Custom sizes & output dir
python recipe/langgraph_agent/example/create_dataset.py \
  --train_size 10000 \
  --test_size 1000 \
  --output_dir my_custom_path

# Training
bash recipe/langgraph_agent/example/run_qwen2.5_3b.sh

# SLURM
sbatch recipe/langgraph_agent/example/run_qwen2.5_3b.sh

Design & Code Changes

Core runability fixes:

• run_qwen2.5_3b.sh:

  • Replace undefined ARNOLD_* vars with SLURM detection + fallbacks
  • Fix dataset paths
  • Add HF hub model fallback
  • Apply performance tuning from GSPO recipe

• chat_model.py: Harden tool-call parsing for malformed JSON

• create_dataset.py: Add CLI args (--train_size, --test_size, --output_dir) with defaults

Docs & polish:

• Update README.md with CLI params and SLURM example
• Sort imports to satisfy ruff linting

Impact: Example now works out-of-the-box in local and cluster environments without edits.

Checklist Before Submitting

• Read the [Contribute Guide](https://github.com/volcengine/verl/blob/main/CONTRIBUTING.md)
• Pre-commit checks: pre-commit install && pre-commit run --all-files --show-diff-on-failure --color=always
• Documentation updated (README.md)
• Manual end-to-end test with convergence results
• CI request to be sent in Slack once PR is opened

[CLAassistant]

All committers have signed the CLA.

[gemini-code-assist]

Code Review

This pull request significantly improves the LangGraph agent example by making it runnable out-of-the-box. The changes, including adding CLI arguments, SLURM support, and more robust error handling, are well-executed. My review focuses on enhancing portability and maintainability. I've identified a critical portability issue in the run script due to a hardcoded network configuration and a high-severity maintainability issue in the chat model from duplicated error-handling code. Addressing these points will further solidify the example's robustness and ease of use across different environments.

[gemini-code-assist]

The UCX_NET_DEVICES variable is hardcoded to a specific configuration with 8 Mellanox network interfaces. This will cause the script to fail on most systems that do not match this exact hardware setup, which undermines the goal of making the example runnable out-of-the-box. To ensure portability, this line should be removed to allow UCX to use default settings, or the device list should be generated dynamically based on the available hardware.

[philippnormann]

This setting is copied from the GSPO recipe (see test_gspo_3b_math.sh:L26) and has worked across multiple hardware configs in my tests. I’m not a UCX expert and open to feedback if there’s a more portable approach.