Merge pull request #299 from microsoft/james-dev

add documentation

Author: james-tn

README.md

@@ -68,7 +68,44 @@ Welcome to the official repository for the Microsoft AI Agentic Workshop! This r
 2. Explore the [Business Scenario and Agent Design](./SCENARIO.md) to understand the workshop challenge.  
 3. Check out the **[Agent Framework Implementation Patterns](agentic_ai/agents/agent_framework/README.md)** to choose the right multi-agent approach (single-agent, Magentic orchestration, or handoff pattern).
 4. Dive into [System Architecture](./ARCHITECTURE.md) before building and customizing your agent solutions.  
-5. Utilize the [Support Guide](./SUPPORT.md) for troubleshooting and assistance.  
+5. Explore **[Workflow Examples & Production Demos](agentic_ai/workflow/)** to learn advanced orchestration patterns.
+6. Utilize the [Support Guide](./SUPPORT.md) for troubleshooting and assistance.  
+  
+---  
+  
+## Workflow Orchestration  
+  
+The workshop includes comprehensive **workflow orchestration** capabilities built on the Microsoft Agent Framework's Pregel-style execution engine. Workflows enable complex multi-agent coordination with type-safe messaging, checkpointing, and real-time observability.  
+  
+### 🎯 Featured Demo: Fraud Detection System  
+  
+A production-ready fraud detection workflow showcasing enterprise-grade patterns:  
+  
+- **Real-time React dashboard** with live workflow visualization  
+- **Fan-out/fan-in patterns** for parallel specialist agent analysis  
+- **Human-in-the-loop** analyst review with checkpointing  
+- **MCP tool integration** for customer data access  
+- **WebSocket streaming** for live event updates  
+  
+**[→ Try the Fraud Detection Demo](agentic_ai/workflow/fraud_detection/)**  
+  
+### 📚 Learning Resources  
+  
+| Resource | Description |  
+|----------|-------------|  
+| **[Workflow Architecture Guide](agentic_ai/workflow/README.md)** | Core concepts, execution model, and API reference |  
+| **[Human-in-the-Loop Patterns](agentic_ai/workflow/human-in-the-loop.md)** | Comprehensive guide to approval workflows |  
+| **[Fraud Detection Demo](agentic_ai/workflow/fraud_detection/)** | Production-ready workflow with real-time UI |  
+  
+### Key Capabilities  
+  
+✅ **Control Flow**: Switch/case routing, conditional edges, dynamic branching  
+✅ **Parallelism**: Fan-out/fan-in, concurrent execution, aggregation patterns  
+✅ **Checkpointing**: Pause/resume workflows, long-running processes, crash recovery  
+✅ **Human-in-the-Loop**: External approvals, RequestInfoExecutor, response handling  
+✅ **State Management**: Executor-local state, shared state, persistence  
+✅ **Observability**: OpenTelemetry tracing, event streaming, real-time monitoring  
+✅ **Composition**: Nested workflows, workflow-as-agent, modular design  
 
 ---  
 

agentic_ai/workflow/ARCHITECTURE.md renamed to agentic_ai/workflow/README.md

@@ -145,3 +145,51 @@ workflow.run() returns WorkflowRunResult([WorkflowOutputEvent("DLROW OLLEH"), ..
 - Magentic multi-agent orchestration: `_magentic.py`.
 
 This architecture balances **expressiveness** (flexible routing, composition), **type safety** (runtime contract enforcement), **observability** (OpenTelemetry spans, event streams), and **durability** (checkpointing for long-running workflows), making it suitable for both simple pipelines and complex multi-agent systems.
+
+---
+
+## Demo: Fraud Detection Workflow
+
+### 🎯 Production-Ready Implementation
+
+A comprehensive fraud detection system showcasing enterprise workflow patterns:
+
+| Feature | Description |
+|---------|-------------|
+| **Architecture** | Fan-out/fan-in pattern with parallel specialist agents |
+| **Human-in-the-Loop** | Analyst review for high-risk cases with checkpointing |
+| **Real-Time UI** | React + FastAPI dashboard with WebSocket streaming |
+| **MCP Integration** | Filtered tool access for domain-specific analysis |
+| **Persistence** | Checkpoint storage for pause/resume workflows |
+
+**[→ Explore the Fraud Detection Demo](fraud_detection/)**
+
+---
+
+## Quick Start
+
+**Try the Fraud Detection Demo:**
+
+```bash
+# Terminal 1: Start MCP Server
+cd mcp
+uv run mcp_service.py
+
+# Terminal 2: Start Backend
+cd agentic_ai/workflow/fraud_detection
+uv run --prerelease allow backend.py
+
+# Terminal 3: Start Frontend
+cd agentic_ai/workflow/fraud_detection/ui
+npm install && npm run dev
+
+# Open browser: http://localhost:3000
+```
+
+---
+
+## Additional Resources
+
+- **[Human-in-the-Loop Guide](human-in-the-loop.md)** - Comprehensive HITL patterns
+- **[Agent Framework GitHub](https://github.com/microsoft/agent-framework)** - Official framework repository
+- **[API Documentation](https://github.com/microsoft/agent-framework/tree/main/docs)** - Detailed API reference

agentic_ai/workflow/fraud_detection/README.md

@@ -267,6 +267,16 @@ instructions=(
 8. **Type-Safe Messaging**: Pydantic models for all messages
 9. **Event Streaming**: Real-time workflow event monitoring
 
+## Recent Improvements
+
+### ✅ Fixed Issues (Latest)
+
+1. **Analyst Review Data Rendering**: Fixed dataclass serialization in `_serialize_analyst_request()` to properly display Risk Score, Recommended Action, Alert ID, and other assessment details in the UI.
+
+2. **Event Ordering**: Corrected event broadcast sequence so Analyst Review completion appears before Fraud Action execution, maintaining proper workflow visualization order.
+
+These fixes ensure the UI accurately reflects the workflow state and displays all relevant fraud assessment information during analyst review.
+
 ## Troubleshooting
 
 ### MCP Connection Fails
@@ -285,6 +295,13 @@ echo $AZURE_OPENAI_CHAT_DEPLOYMENT
 echo $AZURE_OPENAI_ENDPOINT
 ```
 
+### Analyst Review Panel Not Showing Data
+
+This should now be fixed. If you still see issues:
+- Restart the backend server to load the updated code
+- Check browser console for WebSocket errors
+- Verify the MCP server is responding
+
 ### Workflow Hangs
 
 Check logs for executor errors. Each executor logs its progress.