feat: add suspend/resume sample for RPA invocations

[Chibionos]

Overview

This PR adds a comprehensive sample demonstrating the suspend/resume pattern for agents that invoke RPA processes using LangGraph's interrupt() function.

What's New

🎬 Interactive Demo

• demo_suspend_resume.py: Single consolidated script demonstrating complete lifecycle
  • Run full demo or individual suspend/resume steps
  • Clear visual logging with emojis showing execution flow
  • Simulates process restart between suspend and resume
  • Quick start: uv run python demo_suspend_resume.py

📖 Comprehensive README

• Clear Quick Start section with demo command
• Visual lifecycle diagram showing suspend/resume phases
• Organized file listings with purpose explanations
• Multiple usage examples (demo, step-by-step, eval runtime)
• Common patterns with code examples
• Troubleshooting guide for common issues
• Integration details with UiPath evaluation runtime

🔧 Core Agent Files

• graph.py: LangGraph agent with InvokeProcess for real RPA integration
• graph_simple.py: Simplified variant using dict payload (no auth required)
• langgraph.json: Graph entrypoint definitions

🧪 Testing Support

• test_suspend_resume_with_validation.py: Comprehensive test with checkpoint assertions
• test_suspend_step1.py & test_suspend_step2.py: Separate suspend/resume steps
• inspect_state.py: Utility to decode and inspect checkpoint database
• Evaluation sets: JSON files for testing with uipath eval

📦 Dependencies

• Added proper dependencies matching other samples (uipath>=2.5.4, uipath-langchain>=0.4.3)
• Includes uipath-dev in dev dependency group
• Updated minimum uipath version to 2.5.4 for suspend/resume fixes

Key Features

1. Easy to Run: Single demo command shows complete suspend/resume flow
2. Two Graph Variants:
   • Production-ready with InvokeProcess for RPA
   • Development-friendly with simple dict for testing
3. Comprehensive Documentation: Step-by-step guide with visual diagrams
4. Testing Tools: Multiple test scripts and inspection utilities
5. Proper Architecture: LangGraph-specific code stays in uipath-langchain-python

Quick Start

cd samples/tool-calling-suspend-resume

# Run the interactive demo
uv run python demo_suspend_resume.py

# Or test with evaluation runtime
uv run uipath eval agent-simple evaluations/eval-sets/test_simple_no_auth.json

What You'll See

The demo shows:

1. 🔴 Agent executes and calls interrupt() → SUSPENDS
2. 💾 State saves to SQLite (__uipath/state.db)
3. ⏸️ Simulates process exit/restart
4. 🟢 Agent resumes from checkpoint → COMPLETES
5. ✅ Final result with resume data

Related Work

• Requires uipath-python 2.5.4 with status propagation fixes
• Demonstrates proper framework-specific suspend/resume patterns
• Reference implementation for RPA process invocations with interrupt()

Files Structure

samples/tool-calling-suspend-resume/
├── demo_suspend_resume.py          🎬 START HERE! Interactive demo
├── README.md                       📖 Comprehensive guide
├── graph.py                        🔧 Production agent with InvokeProcess
├── graph_simple.py                 🔧 Development agent (no auth)
├── test_suspend_resume_with_validation.py  🧪 Full test with assertions
├── test_suspend_step1.py           🧪 Suspend step only
├── test_suspend_step2.py           🧪 Resume step only
├── inspect_state.py                🔍 Checkpoint inspector
├── pyproject.toml                  📦 Dependencies
├── langgraph.json                  ⚙️ Graph configuration
└── evaluations/                    📋 Evaluation sets

[cristipufu]

we need to add uipath & uipath-langchain deps, same as the other samples