feat: add tool-calling suspend/resume sample

[Chibionos]

Summary

Add comprehensive sample demonstrating the suspend/resume pattern for LangGraph agents that need to pause execution for external work (RPA processes, human-in-the-loop, external APIs, etc.).

What's Included

Core Agent Variants

• graph.py - Production agent with RPA process invocation using interrupt()
• graph_simple.py - Simplified variant for testing without authentication
• graph_calculator.py - 🆕 Calculator agent demonstrating RPA process invocation with bindings
• demo_suspend_resume.py - Interactive demo showing complete suspend/resume cycle

Process Bindings 🆕

• bindings.json - Process bindings for Add.Two.Number.API.Workflow.Tool
• Environment-agnostic design using release keys
• Production-ready workflow orchestration pattern

Documentation

• README.md - Comprehensive usage guide with architecture explanation
• MANUAL_TEST_GUIDE.md - Step-by-step testing instructions
• SUSPEND_RESUME_FIX.md - Technical details on the implementation
• AGENTS.md - Agent variants overview

Testing & Evaluation

• test_full_cycle.py - End-to-end suspend/resume validation
• test_suspend_step1.py / test_suspend_step2.py - Split-phase testing
• test_resume_direct.py - Direct resume testing
• test_suspend_resume_with_validation.py - Comprehensive validation with assertions
• evaluations/eval-sets/ - Test evaluation sets for all agent variants
  • test_simple_no_auth.json - For agent-simple variant
  • test_calculator_process.json - For agent-calculator with RPA
  • test_calculator_single.json - Single test case for calculator
• evaluations/evaluators/ - Contains ContainsEvaluator for validation

Configuration

• pyproject.toml - Dependencies (requires uipath>=2.5.4)
• langgraph.json - Agent configuration with 3 entry points
• uipath.json - Runtime configuration
• entry-points.json - 🆕 Entry point metadata with unique IDs for each variant

Key Features

✅ Three Agent Variants - Production RPA, development-friendly, and calculator demonstrations
✅ Process Bindings - 🆕 Real RPA process integration with bindings.json
✅ Proper Suspend/Resume Pattern - Uses LangGraph's interrupt() for clean suspension points
✅ Checkpoint Persistence - State saved to SQLite for reliable resume
✅ Comprehensive Testing - Full test suite with validation and evaluations
✅ Rich Documentation - README, guides, and inline documentation
✅ Inspection Utilities - inspect_state.py for checkpoint database analysis

Use Cases

This sample is essential for:

• Long-running RPA automations - Don't block agent while process executes
• Human-in-the-loop workflows - Pause for human input, resume after
• External API callbacks - Suspend while waiting for async responses
• Multi-step cross-system processes - Coordinate work across platforms
• Calculator operations via RPA - 🆕 Demonstrates structured input/output with processes

Testing

Run the interactive demo:

cd samples/tool-calling-suspend-resume
uv run python demo_suspend_resume.py

This demonstrates:

1. Agent suspends at interrupt() → SUSPENDS
2. State persists to SQLite
3. New process loads checkpoint
4. Agent resumes → COMPLETES

Test with evaluations:

# Test simple agent (no auth needed)
uv run uipath eval agent-simple evaluations/eval-sets/test_simple_no_auth.json

# Test calculator agent with RPA process
uv run uipath eval agent-calculator evaluations/eval-sets/test_calculator_process.json

Architecture

The suspend/resume pattern enables:

• Stateful execution across process boundaries
• Reliable recovery from checkpoints
• Clean separation between agent logic and external work
• Scalable long-running automations
• Environment-agnostic process invocation via bindings

Recent Updates

• ✅ Added calculator agent variant with RPA process invocation
• ✅ Configured process bindings for Add.Two.Number.API.Workflow.Tool
• ✅ Added evaluation sets for all agent variants
• ✅ Registered agent-calculator entry point in langgraph.json
• ✅ Updated documentation to cover all three variants

🤖 Generated with Claude Code