Added the healthcare example

Dockerfile

@@ -1,20 +1,28 @@
+# Build argument to specify which example to use
+ARG EXAMPLE_NAME=voice_agent_webrtc_langgraph
+
 # Build UI assets
 FROM node:18-alpine AS ui-builder
+ARG EXAMPLE_NAME
 
 WORKDIR /ui
 # Install UI dependencies
-COPY examples/voice_agent_webrtc_langgraph/ui/package*.json ./
+COPY examples/${EXAMPLE_NAME}/ui/package*.json ./
 RUN npm ci --no-audit --no-fund && npm cache clean --force
 # Build UI
-COPY examples/voice_agent_webrtc_langgraph/ui/ .
+COPY examples/${EXAMPLE_NAME}/ui/ .
 RUN npm run build
 
 # Base image
 FROM python:3.12-slim
 
+# Build argument needs to be repeated in this stage
+ARG EXAMPLE_NAME=voice_agent_webrtc_langgraph
+
 # Environment setup
 ENV PYTHONUNBUFFERED=1
 ENV UV_NO_TRACKED_CACHE=1
+ENV EXAMPLE_NAME=${EXAMPLE_NAME}
 
 # System dependencies
 RUN apt-get update && apt-get install -y --no-install-recommends \
@@ -46,13 +54,13 @@ COPY --chown=user pyproject.toml uv.lock \
      LICENSE README.md NVIDIA_PIPECAT.md \
      ./
 COPY --chown=user src/ ./src/
-COPY --chown=user examples/voice_agent_webrtc_langgraph/ ./examples/voice_agent_webrtc_langgraph/
+COPY --chown=user examples/${EXAMPLE_NAME} ./examples/${EXAMPLE_NAME}
 
 # Copy built UI into example directory so FastAPI can serve it
-COPY --from=ui-builder --chown=user /ui/dist /app/examples/voice_agent_webrtc_langgraph/ui/dist
+COPY --from=ui-builder --chown=user /ui/dist /app/examples/${EXAMPLE_NAME}/ui/dist
 
 # Example app directory
-WORKDIR /app/examples/voice_agent_webrtc_langgraph
+WORKDIR /app/examples/${EXAMPLE_NAME}
 
 # Dependencies
 RUN uv sync --frozen
@@ -64,7 +72,7 @@ RUN chmod +x start.sh
 # Fix ownership so runtime user can read caches and virtualenv
 RUN mkdir -p /home/user/.cache/uv \
     && chown -R 1000:1000 /home/user/.cache \
-    && if [ -d /app/examples/voice_agent_webrtc_langgraph/.venv ]; then chown -R 1000:1000 /app/examples/voice_agent_webrtc_langgraph/.venv; fi
+    && if [ -d /app/examples/${EXAMPLE_NAME}/.venv ]; then chown -R 1000:1000 /app/examples/${EXAMPLE_NAME}/.venv; fi
 
 # Port configuration (single external port for app)
 EXPOSE 7860
@@ -72,7 +80,7 @@ EXPOSE 7860
 # Healthcheck
 HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=60s CMD curl -f http://localhost:7860/get_prompt || exit 1
 
-# Start command
-CMD ["/app/examples/voice_agent_webrtc_langgraph/start.sh"]
+# Start command (using sh to expand EXAMPLE_NAME variable)
+CMD sh -c "/app/examples/${EXAMPLE_NAME}/start.sh"
 
 

README.md

@@ -35,7 +35,7 @@ Optional but useful:
 - Starts the Pipecat pipeline (`pipeline.py`) exposing:
   - HTTP: `http://<host>:7860` (health, RTC config)
   - WebSocket: `ws://<host>:7860/ws` (audio + transcripts)
-- Serves the built UI at `http://<host>:9000/` (via Docker).
+  - Static UI: `http://<host>:7860/` (served by FastAPI)
 
 Defaults:
 - ASR: NVIDIA Riva (NIM) via `RIVA_API_KEY` and built-in `NVIDIA_ASR_FUNCTION_ID`
@@ -52,9 +52,32 @@ From `examples/voice_agent_webrtc_langgraph/`:
 docker compose up --build -d
 ```
 
-Then open `http://<machine-ip>:9000/`.
+Then open `http://<machine-ip>:7860/`.
 
-Chrome on http origins: enable “Insecure origins treated as secure” at `chrome://flags/` and add `http://<machine-ip>:9000`.
+Chrome on http origins: enable "Insecure origins treated as secure" at `chrome://flags/` and add `http://<machine-ip>:7860`.
+
+#### Building for Different Examples
+The Dockerfile in the repository root is generalized to work with any example. Use the `EXAMPLE_NAME` build argument to specify which example to use:
+
+**For voice_agent_webrtc_langgraph (default):**
+```bash
+docker build --build-arg EXAMPLE_NAME=voice_agent_webrtc_langgraph -t my-voice-agent .
+docker run -p 7860:7860 --env-file examples/voice_agent_webrtc_langgraph/.env my-voice-agent
+```
+
+**For voice_agent_multi_thread:**
+```bash
+docker build --build-arg EXAMPLE_NAME=voice_agent_multi_thread -t my-voice-agent .
+docker run -p 7860:7860 --env-file examples/voice_agent_multi_thread/.env my-voice-agent
+```
+
+The Dockerfile will automatically:
+- Build the UI for the specified example
+- Copy only the files for that example
+- Set up the correct working directory
+- Configure the start script to run the correct example
+
+**Note:** The UI is served on the same port as the API (7860). The FastAPI app serves both the WebSocket/HTTP endpoints and the static UI files.
 
 ### Option B: Python (local)
 Requires Python 3.12 and `uv`.
@@ -112,6 +135,54 @@ Notes for Magpie Zero‑shot:
 
 ## 5) Troubleshooting
 - Healthcheck: `curl -f http://localhost:7860/get_prompt`
-- If the UI can’t access the mic on http, use the Chrome flag above or host the UI via HTTPS.
+- If the UI can't access the mic on http, use the Chrome flag above or host the UI via HTTPS.
 - For NAT/firewall issues, configure TURN or provide Twilio credentials.
 
+
+## 6) Multi-threaded Voice Agent (voice_agent_multi_thread)
+
+The `voice_agent_multi_thread` example includes a non-blocking multi-threaded agent implementation that allows users to continue conversing while long-running operations execute in the background.
+
+### Build the Docker image:
+```bash
+docker build -t voice-agent-multi-thread .
+```
+
+### Run the container:
+```bash
+docker run -d --name voice-agent-multi-thread \
+  -p 2024:2024 \
+  -p 7862:7860 \
+  --env-file examples/voice_agent_multi_thread/.env \
+  voice-agent-multi-thread
+```
+
+Then access:
+- **LangGraph API**: `http://localhost:2024`
+- **Web UI**: `http://localhost:7862`
+- **Pipeline WebSocket**: `ws://localhost:7862/ws`
+
+The multi-threaded agent automatically enables for `telco-agent` and `wire-transfer-agent`, allowing the secondary thread to handle status checks and interim conversations while the main thread processes long-running tools.
+
+### Stop and remove the container:
+```bash
+docker stop voice-agent-multi-thread && docker rm voice-agent-multi-thread
+```
+
+
+## 7) Manual Docker Commands (voice_agent_webrtc_langgraph)
+
+If you prefer manual Docker commands instead of docker-compose:
+
+```bash
+docker build -t ace-voice-webrtc:latest \
+  -f examples/voice_agent_webrtc_langgraph/Dockerfile \
+  .
+
+docker run --name ace-voice-webrtc -d \
+  -p 7860:7860 \
+  -p 2024:2024 \
+  --env-file examples/voice_agent_webrtc_langgraph/.env \
+  -e LANGGRAPH_ASSISTANT=healthcare-agent \
+  ace-voice-webrtc:latest
+```

examples/voice_agent_multi_thread/DOCKER_DEPLOYMENT.md

@@ -0,0 +1,322 @@
+# Docker Deployment - Multi-Threaded Voice Agent
+
+## Overview
+
+This Docker container runs the complete multi-threaded telco voice agent stack:
+- **LangGraph Server** (`langgraph dev`) on port 2024
+- **Pipecat Pipeline** (FastAPI + WebRTC) on port 7860
+- **React UI** served at `http://localhost:7860`
+
+## Quick Start
+
+### Build the Image
+
+```bash
+# From project root
+docker build -t voice-agent-multi-thread .
+```
+
+### Run the Container
+
+```bash
+docker run -p 7860:7860 \
+  -e RIVA_API_KEY=your_nvidia_api_key \
+  -e NVIDIA_ASR_FUNCTION_ID=52b117d2-6c15-4cfa-a905-a67013bee409 \
+  -e NVIDIA_TTS_FUNCTION_ID=4e813649-d5e4-4020-b2be-2b918396d19d \
+  voice-agent-multi-thread
+```
+
+### Access the UI
+
+Open your browser to: **http://localhost:7860**
+
+## What Happens Inside the Container
+
+The `start.sh` script orchestrates two processes:
+
+### 1. LangGraph Server (Port 2024)
+```bash
+cd /app/examples/voice_agent_multi_thread/agents
+uv run langgraph dev --no-browser --host 0.0.0.0 --port 2024
+```
+
+This runs the multi-threaded telco agent with:
+- Main thread for long operations
+- Secondary thread for interim queries
+- Store-based coordination
+
+### 2. Pipecat Pipeline (Port 7860)
+```bash
+cd /app/examples/voice_agent_multi_thread
+uv run pipeline.py
+```
+
+This runs the voice pipeline with:
+- WebRTC transport
+- RIVA ASR (speech-to-text)
+- LangGraphLLMService (multi-threaded routing)
+- RIVA TTS (text-to-speech)
+- React UI
+
+## Environment Variables
+
+### Required
+
+```bash
+# NVIDIA API Key for RIVA services
+RIVA_API_KEY=nvapi-xxxxx
+```
+
+### Optional
+
+```bash
+# LangGraph Configuration
+LANGGRAPH_HOST=0.0.0.0
+LANGGRAPH_PORT=2024
+LANGGRAPH_ASSISTANT=telco-agent
+
+# User Configuration
+USER_EMAIL=user@example.com
+
+# ASR Configuration
+NVIDIA_ASR_FUNCTION_ID=52b117d2-6c15-4cfa-a905-a67013bee409
+RIVA_ASR_LANGUAGE=en-US
+RIVA_ASR_MODEL=parakeet-1.1b-en-US-asr-streaming-silero-vad-asr-bls-ensemble
+
+# TTS Configuration
+NVIDIA_TTS_FUNCTION_ID=4e813649-d5e4-4020-b2be-2b918396d19d
+RIVA_TTS_VOICE_ID=Magpie-ZeroShot.Female-1
+RIVA_TTS_MODEL=magpie_tts_ensemble-Magpie-ZeroShot
+RIVA_TTS_LANGUAGE=en-US
+
+# Zero-shot audio prompt (optional)
+ZERO_SHOT_AUDIO_PROMPT_URL=https://github.com/your-repo/audio-prompt.wav
+
+# Multi-threading (default: true)
+ENABLE_MULTI_THREADING=true
+
+# Debug
+LANGGRAPH_DEBUG_STREAM=false
+```
+
+## Docker Compose
+
+Create `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  voice-agent:
+    build: .
+    ports:
+      - "7860:7860"
+    environment:
+      - RIVA_API_KEY=${RIVA_API_KEY}
+      - NVIDIA_ASR_FUNCTION_ID=52b117d2-6c15-4cfa-a905-a67013bee409
+      - NVIDIA_TTS_FUNCTION_ID=4e813649-d5e4-4020-b2be-2b918396d19d
+      - USER_EMAIL=user@example.com
+      - LANGGRAPH_ASSISTANT=telco-agent
+      - ENABLE_MULTI_THREADING=true
+    volumes:
+      # Optional: mount .env file
+      - ./examples/voice_agent_multi_thread/.env:/app/examples/voice_agent_multi_thread/.env:ro
+      # Optional: persist audio recordings
+      - ./audio_dumps:/app/examples/voice_agent_multi_thread/audio_dumps
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:7860/get_prompt"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+```
+
+Run with:
+```bash
+docker-compose up
+```
+
+## Using .env File
+
+Create `.env` in `examples/voice_agent_multi_thread/`:
+
+```bash
+# NVIDIA API Keys
+RIVA_API_KEY=nvapi-xxxxx
+
+# LangGraph
+LANGGRAPH_ASSISTANT=telco-agent
+LANGGRAPH_BASE_URL=http://127.0.0.1:2024
+
+# User
+USER_EMAIL=test@example.com
+
+# ASR
+NVIDIA_ASR_FUNCTION_ID=52b117d2-6c15-4cfa-a905-a67013bee409
+
+# TTS
+NVIDIA_TTS_FUNCTION_ID=4e813649-d5e4-4020-b2be-2b918396d19d
+RIVA_TTS_VOICE_ID=Magpie-ZeroShot.Female-1
+```
+
+The `start.sh` script automatically loads this file.
+
+## Ports
+
+| Service | Internal Port | External Port | Purpose |
+|---------|---------------|---------------|---------|
+| LangGraph Server | 2024 | - | Agent runtime (internal only) |
+| Pipecat Pipeline | 7860 | 7860 | WebRTC + HTTP API |
+| React UI | - | 7860 | Served by pipeline |
+
+**Note**: Only port 7860 is exposed externally. LangGraph runs internally on 2024.
+
+## Healthcheck
+
+The container includes a healthcheck that verifies the pipeline is responding:
+
+```bash
+curl -f http://localhost:7860/get_prompt
+```
+
+Check health status:
+```bash
+docker ps
+# Look for "(healthy)" in STATUS column
+```
+
+## Logs
+
+View all logs:
+```bash
+docker logs -f <container-id>
+```
+
+You'll see both:
+- LangGraph server startup and agent logs
+- Pipeline startup and WebRTC connection logs
+
+## Testing Multi-Threading
+
+1. **Open UI**: http://localhost:7860
+2. **Select Agent**: Choose "Telco Agent"
+3. **Test Long Operation**:
+   - Say: *"Close my contract"*
+   - Confirm: *"Yes"*
+   - Operation starts (50 seconds)
+4. **Test Secondary Thread**:
+   - While waiting, say: *"What's the status?"*
+   - Agent responds with progress
+   - Say: *"How much data do I have left?"*
+   - Agent answers while main operation continues
+
+## Troubleshooting
+
+### Container won't start
+```bash
+# Check logs
+docker logs <container-id>
+
+# Common issues:
+# 1. Missing RIVA_API_KEY
+# 2. Port 7860 already in use
+# 3. Insufficient memory
+```
+
+### LangGraph not starting
+```bash
+# Check if agents directory exists
+docker exec <container-id> ls -la /app/examples/voice_agent_multi_thread/agents
+
+# Check langgraph.json
+docker exec <container-id> cat /app/examples/voice_agent_multi_thread/agents/langgraph.json
+```
+
+### Pipeline not responding
+```bash
+# Check pipeline logs
+docker logs <container-id> 2>&1 | grep pipeline
+
+# Check if port is accessible
+curl http://localhost:7860/get_prompt
+```
+
+### Multi-threading not working
+```bash
+# Verify env var
+docker exec <container-id> env | grep MULTI_THREADING
+
+# Check LangGraph server
+docker exec <container-id> curl http://localhost:2024/assistants
+```
+
+## Development Mode
+
+To develop inside the container:
+
+```bash
+# Run with shell
+docker run -it -p 7860:7860 \
+  -v $(pwd)/examples/voice_agent_multi_thread:/app/examples/voice_agent_multi_thread \
+  voice-agent-multi-thread /bin/bash
+
+# Inside container:
+cd /app/examples/voice_agent_multi_thread
+
+# Start services manually
+cd agents && uv run langgraph dev &
+cd .. && uv run pipeline.py
+```
+
+## Building for Production
+
+### Multi-stage optimization
+The Dockerfile uses a multi-stage build:
+1. **ui-builder**: Compiles React UI
+2. **python base**: Installs Python dependencies
+3. **Final image**: ~2GB (UI + Python + agents)
+
+### Reducing image size
+```dockerfile
+# Use slim Python base (already done)
+FROM python:3.12-slim
+
+# Clean up build artifacts (already done)
+RUN apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Use uv for faster installs (already done)
+RUN pip install uv
+```
+
+## Security Considerations
+
+1. **Non-root user**: Container runs as UID 1000
+2. **No secrets in image**: Use environment variables or mount secrets
+3. **Read-only filesystem**: UI dist is built at image time
+4. **Health checks**: Automatic restart on failure
+
+## Performance
+
+- **Startup time**: ~30-60 seconds
+- **Memory**: ~2GB recommended
+- **CPU**: 2 cores minimum
+- **Storage**: ~3GB for image + runtime
+
+## Related Files
+
+- `Dockerfile` - Container definition
+- `start.sh` - Startup orchestration
+- `agents/langgraph.json` - Agent configuration
+- `pipeline.py` - Pipecat pipeline
+- `langgraph_llm_service.py` - Multi-threaded LLM service
+
+## Support
+
+For issues:
+1. Check logs: `docker logs <container-id>`
+2. Verify environment variables
+3. Test components individually (LangGraph, Pipeline)
+4. Review `PIPECAT_MULTI_THREADING.md` for architecture details
+
+
+

examples/voice_agent_multi_thread/Dockerfile

@@ -0,0 +1,78 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: BSD 2-Clause License
+
+# Build UI assets
+FROM node:18-alpine AS ui-builder
+
+WORKDIR /ui
+# Install UI dependencies
+COPY examples/voice_agent_webrtc_langgraph/ui/package*.json ./
+RUN npm ci --no-audit --no-fund && npm cache clean --force
+# Build UI
+COPY examples/voice_agent_webrtc_langgraph/ui/ .
+RUN npm run build
+
+# Base image
+FROM python:3.12-slim
+
+# Image metadata
+LABEL maintainer="NVIDIA"
+LABEL description="Voice Agent WebRTC using Langgraph"
+LABEL version="1.0"
+
+# Environment setup
+ENV PYTHONUNBUFFERED=1
+
+# System dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgl1 \
+    libglx-mesa0 \
+    curl \
+    ffmpeg \
+    git \
+    net-tools \
+    procps \
+    vim \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/* \
+    && pip install --no-cache-dir --upgrade pip uv
+
+# App directory setup
+WORKDIR /app
+
+# App files
+COPY pyproject.toml uv.lock \
+     LICENSE README.md NVIDIA_PIPECAT.md \
+     ./
+COPY src/ ./src/
+COPY examples/voice_agent_webrtc_langgraph/ ./examples/voice_agent_webrtc_langgraph/
+
+# Copy built UI into example directory
+COPY --from=ui-builder /ui/dist /app/examples/voice_agent_webrtc_langgraph/ui/dist
+
+# Example app directory
+WORKDIR /app/examples/voice_agent_webrtc_langgraph
+
+# Dependencies
+RUN uv sync --frozen
+# RUN uv sync
+# Install all agent requirements recursively into the project's virtual environment
+# RUN if [ -d "agents" ]; then \
+#     find agents -type f -name "requirements.txt" -print0 | xargs -0 -I {} uv pip install -r "{}"; \
+#   fi
+
+RUN uv pip install -r agents/requirements.txt
+# Ensure langgraph CLI is available at build time
+RUN uv pip install -U langgraph
+RUN chmod +x start.sh
+
+# Port configuration
+EXPOSE 7860
+EXPOSE 9000
+EXPOSE 2024
+
+# Healthcheck similar to docker-compose
+HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=60s CMD curl -f http://localhost:7860/get_prompt || exit 1
+
+# Start command
+CMD ["/app/examples/voice_agent_webrtc_langgraph/start.sh"]

examples/voice_agent_multi_thread/PIPECAT_MULTI_THREADING.md

@@ -0,0 +1,295 @@
+# Pipecat Multi-Threading Integration
+
+## Overview
+
+This document explains how the multi-threaded telco agent is integrated with the Pipecat voice pipeline using WebRTC.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  Browser (WebRTC)                        │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ↓ Audio Stream
+┌─────────────────────────────────────────────────────────┐
+│              pipeline.py (FastAPI + Pipecat)             │
+│                                                           │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │   Pipeline:                                      │   │
+│  │   WebRTC → ASR → LangGraphLLMService → TTS →   │   │
+│  └─────────────────────────────────────────────────┘   │
+│                        ↓                                 │
+│                langgraph_llm_service.py                  │
+│                        ↓                                 │
+└────────────────────┬───────────────────────────────────┘
+                     │
+                     ↓ HTTP/WebSocket
+┌─────────────────────────────────────────────────────────┐
+│           LangGraph Server (langgraph dev)               │
+│                                                           │
+│  ┌──────────────────────────────────────────────────┐  │
+│  │  react_agent.py (Multi-threaded)                  │  │
+│  │                                                    │  │
+│  │  Main Thread: Handles long operations             │  │
+│  │  Secondary Thread: Handles interim queries        │  │
+│  │                                                    │  │
+│  │  Store: Coordinates between threads               │  │
+│  └──────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+## How It Works
+
+### 1. **LangGraphLLMService** (`langgraph_llm_service.py`)
+
+This service acts as a bridge between Pipecat's frame-based processing and LangGraph's agent.
+
+#### Key Changes:
+
+**a) Dual Thread Management:**
+```python
+self._thread_id_main: Optional[str] = None      # For long operations
+self._thread_id_secondary: Optional[str] = None  # For interim queries
+```
+
+**b) Operation Status Checking:**
+```python
+async def _check_long_operation_running(self) -> bool:
+    """Check if a long operation is currently running via the store."""
+    # Queries LangGraph store for "running" status
+    # Returns True if a long operation is in progress
+```
+
+**c) Automatic Routing:**
+```python
+# Before each message, check if long operation is running
+long_operation_running = await self._check_long_operation_running()
+
+if long_operation_running:
+    thread_type = "secondary"  # Route to secondary thread
+else:
+    thread_type = "main"       # Route to main thread
+```
+
+**d) Input Format:**
+```python
+# New multi-threaded format
+input_payload = {
+    "messages": [{"type": "human", "content": text}],
+    "thread_type": "main" or "secondary",
+    "interim_messages_reset": bool,
+}
+
+# Config includes namespace for coordination
+config = {
+    "configurable": {
+        "user_email": self.user_email,
+        "thread_id": thread_id,
+        "namespace_for_memory": ["user@example.com", "tools_updates"],
+    }
+}
+```
+
+### 2. **Pipeline Configuration** (`pipeline.py`)
+
+```python
+# Enable multi-threading for specific assistants
+enable_multi_threading = selected_assistant in ["telco-agent", "wire-transfer-agent"]
+
+llm = LangGraphLLMService(
+    base_url=os.getenv("LANGGRAPH_BASE_URL", "http://127.0.0.1:2024"),
+    assistant=selected_assistant,
+    enable_multi_threading=enable_multi_threading,  # NEW
+)
+```
+
+### 3. **React Agent** (`react_agent.py`)
+
+Already updated to handle multi-threaded input format (see `MULTI_THREAD_README.md`).
+
+## Flow Example
+
+### User says: "Close my contract"
+
+```
+1. Browser (WebRTC) → Pipecat Pipeline
+2. ASR converts to text: "Close my contract"
+3. LangGraphLLMService receives text
+4. Service checks store: No long operation running
+5. Service sends to main thread:
+   {
+     "messages": [{"type": "human", "content": "Close my contract"}],
+     "thread_type": "main",
+     "interim_messages_reset": True
+   }
+6. Agent starts 50-second contract closure
+7. Agent writes status to store: {"status": "running", "progress": 10}
+8. TTS speaks: "Processing your contract closure..."
+```
+
+### User says (5 seconds later): "What's the status?"
+
+```
+1. Browser (WebRTC) → Pipecat Pipeline
+2. ASR converts to text: "What's the status?"
+3. LangGraphLLMService receives text
+4. Service checks store: Long operation IS running ✓
+5. Service sends to secondary thread:
+   {
+     "messages": [{"type": "human", "content": "What's the status?"}],
+     "thread_type": "secondary",
+     "interim_messages_reset": False
+   }
+6. Secondary thread checks status tool
+7. Agent responds: "Your request is 20% complete"
+8. TTS speaks response
+9. Main thread continues running in background
+```
+
+### Main operation completes (50 seconds later)
+
+```
+1. Main thread finishes contract closure
+2. Agent synthesizes: result + interim conversation
+3. Agent sets completion flag in store
+4. TTS speaks: "Your contract has been closed..."
+5. Service detects completion on next message
+6. Routes future messages to main thread
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# LangGraph Server
+LANGGRAPH_BASE_URL=http://127.0.0.1:2024
+LANGGRAPH_ASSISTANT=telco-agent
+
+# User identification (for namespace)
+USER_EMAIL=test@example.com
+
+# Enable debug logging
+LANGGRAPH_DEBUG_STREAM=true
+```
+
+### Enable/Disable Multi-Threading
+
+**For specific agents:**
+```python
+# In pipeline.py
+enable_multi_threading = selected_assistant in ["telco-agent", "wire-transfer-agent"]
+```
+
+**Via environment variable (optional):**
+```python
+enable_multi_threading = os.getenv("ENABLE_MULTI_THREADING", "true").lower() == "true"
+```
+
+**Disable for an agent:**
+```python
+llm = LangGraphLLMService(
+    assistant="some-other-agent",
+    enable_multi_threading=False,  # Use simple single-threaded mode
+)
+```
+
+## Store Keys Used
+
+The service queries these store keys for coordination:
+
+| Key | Purpose | Set By |
+|-----|---------|--------|
+| `working-tool-status-update` | Current tool progress | Agent's long-running tools |
+| `main_operation_complete` | Completion signal | Agent's main thread |
+| `secondary_interim_messages` | Interim conversation | Agent's secondary thread |
+
+## Backward Compatibility
+
+When `enable_multi_threading=False`:
+- Uses single thread
+- Sends simple message format: `[HumanMessage(content=text)]`
+- No store coordination
+- Works with non-multi-threaded agents
+
+## Benefits
+
+1. **Non-Blocking Voice UX**: User can continue talking during long operations
+2. **Transparent**: User doesn't need to know about threading
+3. **Automatic Routing**: Service handles main/secondary routing automatically
+4. **Store-Based**: No client-side coordination needed
+5. **Backward Compatible**: Existing agents work without changes
+
+## Testing
+
+### With Web UI
+
+1. Start LangGraph server: `langgraph dev`
+2. Start pipeline: `python pipeline.py`
+3. Open browser to `http://localhost:7860`
+4. Select "Telco Agent"
+5. Say: "Close my contract" → Confirm with "yes"
+6. While processing, say: "What's the status?"
+7. Agent should respond with progress while operation continues
+
+### With Client Script
+
+```bash
+# Terminal 1: Start LangGraph
+cd examples/voice_agent_multi_thread/agents
+langgraph dev
+
+# Terminal 2: Test with client
+cd examples/voice_agent_multi_thread/agents
+python telco_client.py --interactive
+```
+
+## Troubleshooting
+
+### Messages always go to main thread
+- Check that `enable_multi_threading=True`
+- Verify long-running tools are writing status to store
+- Check namespace matches: `("user_email", "tools_updates")`
+
+### Secondary thread not responding
+- Ensure secondary thread has limited tool set
+- Check `SECONDARY_SYSTEM_PROMPT` in `react_agent.py`
+- Verify `check_status` tool is included
+
+### Synthesis not working
+- Check `secondary_interim_messages` in store
+- Verify meaningful messages filter in agent
+- Check synthesis prompt in agent
+
+## Performance
+
+- **Store queries**: ~10-20ms per check
+- **Thread switching**: Negligible (routing decision)
+- **Memory overhead**: Two threads vs one
+- **Latency impact**: Minimal (<50ms added per request)
+
+## Future Enhancements
+
+1. **Session persistence**: Store thread IDs in Redis
+2. **Multiple long operations**: Queue system
+3. **Progress streaming**: Real-time progress updates
+4. **Cancellation**: User can cancel long operations
+5. **Thread pooling**: Reuse secondary threads
+
+## Related Files
+
+- `langgraph_llm_service.py` - Service implementation
+- `pipeline.py` - Pipeline configuration
+- `react_agent.py` - Multi-threaded agent
+- `tools.py` - Long-running tools with progress reporting
+- `helper_functions.py` - Store coordination utilities
+- `telco_client.py` - CLI test client
+
+## Credits
+
+Implementation: Option 1 (Tool-Level Designation)
+Date: September 30, 2025
+
+
+

examples/voice_agent_multi_thread/README.md

@@ -0,0 +1,112 @@
+# Voice Agent WebRTC + LangGraph (Quick Start)
+
+This example launches a complete voice agent stack:
+- LangGraph dev server for local agents
+- Pipecat-based speech pipeline (WebRTC, ASR, LLM adapter, TTS)
+- Static UI you can open in a browser
+
+
+## 1) Mandatory environment variables
+Create `.env` next to this README (or copy from `env.example`) and set at least:
+
+- `NVIDIA_API_KEY` or `RIVA_API_KEY`: required for NVIDIA NIM-hosted Riva ASR/TTS
+- `USE_LANGGRAPH=true`: enable LangGraph-backed LLM
+- `LANGGRAPH_BASE_URL` (default `http://127.0.0.1:2024`)
+- `LANGGRAPH_ASSISTANT` (default `ace-base-agent`)
+- `USER_EMAIL` (any email for routing, e.g. `test@example.com`)
+- `LANGGRAPH_STREAM_MODE` (default `values`)
+- `LANGGRAPH_DEBUG_STREAM` (default `true`)
+
+Optional but commonly used:
+- `RIVA_ASR_LANGUAGE` (default `en-US`)
+- `RIVA_TTS_LANGUAGE` (default `en-US`)
+- `RIVA_TTS_VOICE_ID` (e.g. `Magpie-ZeroShot.Female-1`)
+- `RIVA_TTS_MODEL` (e.g. `magpie_tts_ensemble-Magpie-ZeroShot`)
+- `ZERO_SHOT_AUDIO_PROMPT` if using Magpie Zero‑shot and a custom voice prompt
+- `ZERO_SHOT_AUDIO_PROMPT_URL` to auto-download prompt on startup
+- `ENABLE_SPECULATIVE_SPEECH` (default `true`)
+- TURN/Twilio for WebRTC if needed: `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, or `TURN_SERVER_URL`, `TURN_USERNAME`, `TURN_PASSWORD`
+
+
+## 2) What it does
+- Starts LangGraph dev server to serve local agents from `agents/`.
+- Starts the Pipecat pipeline (`pipeline.py`) exposing:
+  - HTTP: `http://<host>:7860` (health and RTC config)
+  - WebSocket: `ws://<host>:7860/ws` for audio and transcripts
+- Serves the built UI at `http://<host>:9000/` (via the container).
+
+By default it uses:
+- ASR: NVIDIA Riva (NIM) with `RIVA_API_KEY` and `NVIDIA_ASR_FUNCTION_ID`
+- LLM: LangGraph adapter streaming from the selected assistant
+- TTS: NVIDIA Riva Magpie (NIM) with `RIVA_API_KEY` and `NVIDIA_TTS_FUNCTION_ID`
+
+
+## 3) Run
+
+### Option A: Docker (recommended)
+From this directory:
+
+```bash
+docker compose up --build -d
+```
+
+Then open `http://<machine-ip>:9000/`.
+
+Chrome on http origins: enable “Insecure origins treated as secure” at `chrome://flags/` and add `http://<machine-ip>:9000`.
+
+### Option B: Python (local)
+Requires Python 3.12 and `uv`.
+
+```bash
+uv run pipeline.py
+```
+Then start the UI from `ui/` (see `ui/README.md`).
+
+
+## 4) Swap TTS providers (Magpie ⇄ ElevenLabs)
+The default TTS in `pipeline.py` is NVIDIA Riva Magpie via NIM:
+
+```startLine:endLine:examples/voice_agent_webrtc_langgraph/pipeline.py
+tts = RivaTTSService(
+    api_key=os.getenv("RIVA_API_KEY"),
+    function_id=os.getenv("NVIDIA_TTS_FUNCTION_ID", "4e813649-d5e4-4020-b2be-2b918396d19d"),
+    voice_id=os.getenv("RIVA_TTS_VOICE_ID", "Magpie-ZeroShot.Female-1"),
+    model=os.getenv("RIVA_TTS_MODEL", "magpie_tts_ensemble-Magpie-ZeroShot"),
+    language=os.getenv("RIVA_TTS_LANGUAGE", "en-US"),
+    zero_shot_audio_prompt_file=(
+        Path(os.getenv("ZERO_SHOT_AUDIO_PROMPT")) if os.getenv("ZERO_SHOT_AUDIO_PROMPT") else None
+    ),
+)
+```
+
+To use ElevenLabs instead:
+1) Ensure `pipecat` ElevenLabs dependency is available (already included via project deps).
+2) Set environment:
+   - `ELEVENLABS_API_KEY`
+   - Optionally `ELEVENLABS_VOICE_ID` and model settings supported by ElevenLabs
+3) Change the TTS construction in `pipeline.py` to use `ElevenLabsTTSServiceWithEndOfSpeech`:
+
+```python
+from nvidia_pipecat.services.elevenlabs import ElevenLabsTTSServiceWithEndOfSpeech
+
+# Replace RivaTTSService(...) with:
+tts = ElevenLabsTTSServiceWithEndOfSpeech(
+    api_key=os.getenv("ELEVENLABS_API_KEY"),
+    voice_id=os.getenv("ELEVENLABS_VOICE_ID", "Rachel"),
+    sample_rate=16000,
+    channels=1,
+)
+```
+
+That’s it. No other pipeline changes are required. The transcript synchronization already supports ElevenLabs end‑of‑speech events.
+
+Notes for Magpie Zero‑shot:
+- Provide `RIVA_TTS_VOICE_ID` like `Magpie-ZeroShot.Female-1` and `RIVA_TTS_MODEL` like `magpie_tts_ensemble-Magpie-ZeroShot`.
+- If using a custom voice prompt, mount it via `docker-compose.yml` and set `ZERO_SHOT_AUDIO_PROMPT`. You can also set `ZERO_SHOT_AUDIO_PROMPT_URL` to auto-download at startup.
+
+
+## 5) Troubleshooting
+- Healthcheck: `curl -f http://localhost:7860/get_prompt`
+- If UI can’t access mic on http, use Chrome flag above or host UI via HTTPS.
+- For NAT/firewall issues, configure TURN or Twilio credentials.
+

examples/voice_agent_multi_thread/agents/.telco_thread_id

@@ -0,0 +1 @@
+8492eaa4-d086-452d-8f82-2cf2ed819ae1

examples/voice_agent_multi_thread/agents/Dockerfile.langgraph.api

@@ -0,0 +1,39 @@
+FROM langchain/langgraph-api:3.11
+
+RUN pip install --upgrade pip
+COPY ace_base_agent/requirements.txt /tmp/requirements.txt
+RUN pip install -r /tmp/requirements.txt
+
+# -- Adding non-package dependency agents --
+ADD . /deps/__outer_agents/src
+RUN set -ex && \
+    for line in '[project]' \
+                'name = "agents"' \
+                'version = "0.1"' \
+                '[tool.setuptools.package-data]' \
+                '"*" = ["**/*"]' \
+                '[build-system]' \
+                'requires = ["setuptools>=61"]' \
+                'build-backend = "setuptools.build_meta"'; do \
+        echo "$line" >> /deps/__outer_agents/pyproject.toml; \
+    done
+# -- End of non-package dependency agents --
+
+# -- Installing all local dependencies --
+RUN PYTHONDONTWRITEBYTECODE=1 uv pip install --system --no-cache-dir -c /api/constraints.txt -e /deps/*
+# -- End of local dependencies install --
+ENV LANGSERVE_GRAPHS='{"ace-base-agent": "/deps/__outer_agents/src/ace_base_agent/ace_base_agent.py:agent"}'
+
+
+
+# -- Ensure user deps didn't inadvertently overwrite langgraph-api
+RUN mkdir -p /api/langgraph_api /api/langgraph_runtime /api/langgraph_license && touch /api/langgraph_api/__init__.py /api/langgraph_runtime/__init__.py /api/langgraph_license/__init__.py
+RUN PYTHONDONTWRITEBYTECODE=1 uv pip install --system --no-cache-dir --no-deps -e /api
+# -- End of ensuring user deps didn't inadvertently overwrite langgraph-api --
+# -- Removing build deps from the final image ~<:===~~~ --
+RUN pip uninstall -y pip setuptools wheel
+RUN rm -rf /usr/local/lib/python*/site-packages/pip* /usr/local/lib/python*/site-packages/setuptools* /usr/local/lib/python*/site-packages/wheel* && find /usr/local/bin -name "pip*" -delete || true
+RUN rm -rf /usr/lib/python*/site-packages/pip* /usr/lib/python*/site-packages/setuptools* /usr/lib/python*/site-packages/wheel* && find /usr/bin -name "pip*" -delete || true
+RUN uv pip uninstall --system pip setuptools wheel && rm /usr/bin/uv /usr/bin/uvx
+
+WORKDIR /deps/__outer_agents/src

examples/voice_agent_multi_thread/agents/env.example

@@ -0,0 +1,10 @@
+# agents/.env example for local dev (used by `langgraph dev`)
+# Copy to agents/.env and set your keys.
+
+# Required by ace_base_agent (ChatOpenAI)
+OPENAI_API_KEY=
+
+# Optional tracing
+LANGSMITH_API_KEY=
+LANGSMITH_BASE_URL=https://api.smith.langchain.com
+LANGSMITH_PROJECT=ace-controller

examples/voice_agent_multi_thread/agents/helper_functions.py

@@ -0,0 +1,62 @@
+"""Helper functions for multi-threaded agent coordination and progress tracking."""
+
+from typing import Any, Dict
+from langgraph.store.base import BaseStore
+
+
+def write_status(
+    tool_name: str,
+    progress: int,
+    status: str,
+    store: BaseStore,
+    namespace: tuple | list,
+    config: Dict[str, Any] | None = None
+) -> None:
+    """Write tool execution status and progress to the store.
+    
+    Args:
+        tool_name: Name of the tool being executed
+        progress: Progress percentage (0-100)
+        status: Status string ("running", "completed", "failed")
+        store: LangGraph store instance
+        namespace: Namespace tuple for store isolation
+        config: Optional runtime config
+    """
+    if not isinstance(namespace, tuple):
+        try:
+            namespace = tuple(namespace)
+        except (TypeError, ValueError):
+            namespace = (str(namespace),)
+    
+    store.put(
+        namespace,
+        "working-tool-status-update",
+        {
+            "tool_name": tool_name,
+            "progress": progress,
+            "status": status,
+        }
+    )
+
+
+def reset_status(store: BaseStore, namespace: tuple | list) -> None:
+    """Reset/clear tool execution status from the store.
+    
+    Args:
+        store: LangGraph store instance
+        namespace: Namespace tuple for store isolation
+    """
+    if not isinstance(namespace, tuple):
+        try:
+            namespace = tuple(namespace)
+        except (TypeError, ValueError):
+            namespace = (str(namespace),)
+    
+    try:
+        store.delete(namespace, "working-tool-status-update")
+    except Exception:
+        # If key doesn't exist, that's fine
+        pass
+
+
+

examples/voice_agent_multi_thread/agents/langgraph.json

@@ -0,0 +1,15 @@
+{
+    "dependencies": ["."],
+    "graphs": {
+      "telco-agent": "./telco-agent-multi/react_agent.py:agent"
+
+    },
+    "dockerfile_lines": [
+            "RUN pip install --upgrade pip",
+            "COPY ace_base_agent/requirements.txt /tmp/requirements.txt",
+            "RUN pip install -r /tmp/requirements.txt",
+            "COPY ../requirements.txt /tmp/root_requirements.txt",
+            "RUN pip install -r /tmp/root_requirements.txt"
+        ],
+    "env": ".env"
+}

examples/voice_agent_multi_thread/agents/requirements.txt

@@ -0,0 +1,15 @@
+langchain
+langgraph
+langgraph-cli[inmem]
+langgraph-sdk
+langchain_openai
+gradio
+matplotlib
+seaborn
+pytz
+docling
+pymongo
+yt_dlp
+requests
+protobuf==6.31.1
+twilio

examples/voice_agent_multi_thread/agents/telco-agent-multi/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,280 @@
+# Multi-Threaded Telco Agent - Implementation Summary
+
+## Overview
+
+Successfully implemented **Option 1: Tool-Level Designation** for the telco agent, enabling non-blocking multi-threaded execution with intelligent routing based on whether operations are long-running or quick.
+
+## Files Modified/Created
+
+### 1. **Created: `helper_functions.py`**
+   - **Location**: `agents/helper_functions.py`
+   - **Purpose**: Shared utilities for progress tracking and coordination
+   - **Functions**:
+     - `write_status()`: Write tool execution progress to store
+     - `reset_status()`: Clear tool execution status
+
+### 2. **Modified: `tools.py`**
+   - **Location**: `agents/telco-agent-multi/tools.py`
+   - **Changes**:
+     - Added imports for progress tracking (`time`, `get_store`, `get_stream_writer`, etc.)
+     - Updated **4 long-running tools** with progress reporting:
+       1. `close_contract_tool` (10 seconds, 5 steps)
+       2. `purchase_roaming_pass_tool` (8 seconds, 4 steps)
+       3. `change_package_tool` (10 seconds, 5 steps)
+       4. `get_billing_summary_tool` (6 seconds, 3 steps)
+     - Added `check_status()` tool for secondary thread
+     - Marked all tools with `is_long_running` attribute (True/False)
+     - Tools now send immediate feedback via `get_stream_writer()`
+
+### 3. **Modified: `react_agent.py`**
+   - **Location**: `agents/telco-agent-multi/react_agent.py`
+   - **Major Changes**:
+
+#### Imports
+   - Added: `time`, `ChatPromptTemplate`, `BaseStore`, `RunnableConfig`, `ensure_config`, `get_store`
+   - Imported helper functions
+
+#### System Prompts
+   - Added `SECONDARY_SYSTEM_PROMPT` for interim conversations
+   - Kept original `SYSTEM_PROMPT` for main operations
+
+#### LLM Configuration
+   - Split tools into:
+     - `_MAIN_TOOLS`: All 13 telco tools
+     - `_SECONDARY_TOOLS`: 6 safe, quick tools + `check_status`
+   - Created dual LLM bindings:
+     - `_LLM_WITH_TOOLS`: Main thread (temp 0.3)
+     - `_HELPER_LLM_WITH_TOOLS`: Secondary thread (temp 0.7)
+   - Added `_ALL_TOOLS_BY_NAME` dictionary
+
+#### Synthesis Chain
+   - Added `_SYNTHESIS_PROMPT` and `_SYNTHESIS_CHAIN`
+   - Merges tool results with interim conversation
+
+#### Agent Function (Complete Refactor)
+   - **Signature Changed**:
+     ```python
+     # Before
+     def agent(messages: List[BaseMessage], previous: List[BaseMessage] | None, config: Dict[str, Any] | None = None)
+     
+     # After
+     def agent(input_dict: dict, previous: Any = None, config: RunnableConfig | None = None, store: BaseStore | None = None)
+     ```
+
+   - **Input Dictionary**:
+     ```python
+     input_dict = {
+         "messages": List[BaseMessage],
+         "thread_type": "main" | "secondary",
+         "interim_messages_reset": bool
+     }
+     ```
+
+   - **State Format**:
+     ```python
+     # Before: List[BaseMessage]
+     # After: Dict[str, List[BaseMessage]]
+     {
+         "messages": [...],           # Full conversation
+         "interim_messages": [...]    # Interim conversation during long ops
+     }
+     ```
+
+   - **New Features**:
+     1. **Thread Type Routing**: Choose LLM/tools based on thread type
+     2. **Processing Locks**: Secondary thread sets lock at start
+     3. **Abort Handling**: Main can signal secondary to abort
+     4. **Wait & Synthesize**: Main waits for secondary (15s timeout) and synthesizes
+     5. **Progress Tracking**: Reset status after main thread completion
+     6. **Store Coordination**: Uses namespace for thread coordination
+
+### 4. **Created: `MULTI_THREAD_README.md`**
+   - Comprehensive documentation of:
+     - Architecture overview
+     - Long-running vs quick tools
+     - Usage examples
+     - Coordination mechanism
+     - Safety features
+     - Migration guide
+
+### 5. **Created: `example_multi_thread.py`**
+   - Executable demo script
+   - Three scenarios:
+     1. Long operation with status checks
+     2. Quick synchronous query
+     3. Interactive mode
+   - Shows proper threading and routing logic
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         User Request                         │
+└─────────────────────┬───────────────────────────────────────┘
+                      │
+         ┌────────────┴────────────┐
+         │                         │
+    Long Tool?               Quick Tool?
+         │                         │
+         ▼                         ▼
+    Main Thread              Main Thread
+         │                    (synchronous)
+         ├─ Execute Tool           │
+         │  (with progress)        └─ Return
+         │                              
+         ├─ Store progress               
+         │                              
+         ├─ Check Secondary              
+         │                              
+         └─ Synthesize Result            
+                                         
+    While Main Running:                  
+         ▼                               
+    Secondary Thread                     
+         │                               
+         ├─ Handle interim queries       
+         │  (limited tools)              
+         │                               
+         └─ Store interim messages       
+```
+
+## Store Keys Used
+
+| Key | Purpose | Lifecycle |
+|-----|---------|-----------|
+| `working-tool-status-update` | Tool progress (0-100%) | Set by long tools, cleared by main |
+| `secondary_status` | Secondary thread lock | Set at start, cleared at end |
+| `secondary_abort` | Abort signal | Set by main on timeout, cleared by secondary |
+| `secondary_interim_messages` | Interim conversation | Set by secondary, read/cleared by main |
+
+## Tool Classification
+
+### Long-Running Tools (4 tools)
+1. **`close_contract_tool`** - 10 seconds
+   - Simulates contract closure processing
+   - Reports 5 progress steps
+
+2. **`purchase_roaming_pass_tool`** - 8 seconds
+   - Simulates payment processing and activation
+   - Reports 4 progress steps
+
+3. **`change_package_tool`** - 10 seconds
+   - Simulates package provisioning
+   - Reports 5 progress steps
+
+4. **`get_billing_summary_tool`** - 6 seconds
+   - Simulates multi-system billing queries
+   - Reports 3 progress steps
+
+### Quick Tools (9 tools)
+- `start_login_tool`, `verify_login_tool` (auth)
+- `get_current_package_tool` (lookup)
+- `get_data_balance_tool` (lookup)
+- `list_available_packages_tool` (catalog)
+- `recommend_packages_tool` (computation)
+- `get_roaming_info_tool` (reference data)
+- `list_addons_tool` (lookup)
+- `set_data_alerts_tool` (config update)
+
+### Helper Tool
+- `check_status` (progress query for secondary thread)
+
+## Safety Features
+
+1. **Processing Locks**
+   - Secondary thread sets `secondary_status.processing = True` at start
+   - Released when complete or aborted
+   - Prevents race conditions
+
+2. **Abort Signals**
+   - Main thread can set `secondary_abort` flag
+   - Secondary checks flag at start and before writing results
+   - Graceful termination without corrupting state
+
+3. **Timeouts**
+   - Main thread waits max 15 seconds for secondary
+   - Prevents indefinite blocking
+   - Sets abort flag on timeout
+
+4. **Message Sanitization**
+   - Removes orphan `ToolMessage` instances
+   - Prevents OpenAI API 400 errors
+   - Maintains conversation coherence
+
+5. **State Isolation**
+   - Separate thread IDs for main and secondary
+   - Namespace-based store isolation
+   - No cross-contamination
+
+## Testing Recommendations
+
+### Unit Tests
+- Test long tools report progress correctly
+- Test `check_status` returns accurate status
+- Test message sanitization removes orphans
+- Test state merging (messages + interim_messages)
+
+### Integration Tests
+1. **Single long operation**: Verify completion and status reset
+2. **Long operation + status check**: Verify secondary can query progress
+3. **Long operation + multiple queries**: Verify multiple secondary calls
+4. **Synthesis**: Verify main synthesizes interim conversation
+5. **Timeout**: Verify main aborts secondary after 15s
+6. **Quick operation**: Verify no multi-threading overhead
+
+### Load Tests
+- Multiple concurrent users with different namespaces
+- Rapid main/secondary alternation
+- Store performance under load
+
+## Performance Considerations
+
+1. **Store Access**: Each coordination point hits the store
+   - Consider caching for high-frequency access
+   - Monitor store latency
+
+2. **Synthesis LLM Call**: Additional API call for merging
+   - Only happens when interim conversation exists
+   - Uses temperature 0.7 for natural language
+
+3. **Thread Overhead**: Secondary thread runs synchronously
+   - No actual parallelism for safety
+   - Consider async/await for true concurrency
+
+4. **Timeout Waiting**: Main thread sleeps in 0.5s intervals
+   - 15 seconds max = 30 checks
+   - Minimal CPU usage
+
+## Migration Path
+
+For existing deployments:
+
+1. **Update client code** to use new input format
+2. **Add `namespace_for_memory`** to config
+3. **Provide store instance** to agent calls
+4. **Update state handling** to expect dict instead of list
+5. **Test backward compatibility** with quick tools (should work seamlessly)
+
+## Future Enhancements
+
+1. **Dynamic Tool Marking**: Tool duration could be learned/adjusted
+2. **Priority Queue**: Multiple long operations could queue
+3. **True Async**: Replace synchronous secondary with async/await
+4. **Progress UI**: Stream progress updates to frontend
+5. **Cancellation**: User-initiated cancellation of long operations
+6. **Retry Logic**: Automatic retry for failed long operations
+7. **Telemetry**: Track success rates, durations, timeout frequency
+
+## Credits
+
+Implementation based on the multi-threaded agent pattern with:
+- Tool-level designation (Option 1)
+- Store-based coordination
+- Progress tracking and streaming
+- Conversation synthesis
+- Race condition handling
+
+Date: September 30, 2025
+
+
+

examples/voice_agent_multi_thread/agents/telco-agent-multi/MULTI_THREAD_README.md

@@ -0,0 +1,227 @@
+# Multi-Threaded Telco Agent
+
+## Overview
+
+This telco agent now supports **non-blocking multi-threaded execution**, allowing users to continue conversing while long-running operations (like package changes, contract closures, or billing queries) are in progress.
+
+## Key Features
+
+### 1. **Dual Thread Architecture**
+
+- **Main Thread**: Handles primary requests and long-running operations
+- **Secondary Thread**: Handles interim conversations while main thread is busy
+
+### 2. **Long-Running Tools**
+
+The following tools are marked as long-running and will trigger multi-threaded behavior:
+
+- `close_contract_tool` (10 seconds)
+- `purchase_roaming_pass_tool` (8 seconds)
+- `change_package_tool` (10 seconds)
+- `get_billing_summary_tool` (6 seconds)
+
+### 3. **Quick Tools** (for secondary thread)
+
+These tools are available during long operations:
+
+- `check_status` - Query progress of ongoing operation
+- `get_current_package_tool` - Quick lookups
+- `get_data_balance_tool` - Quick queries
+- `list_available_packages_tool` - Browse packages
+- `get_roaming_info_tool` - Roaming information
+- `list_addons_tool` - List addons
+
+### 4. **Progress Tracking**
+
+Long-running tools report progress that can be queried via `check_status` tool during execution.
+
+### 5. **Conversation Synthesis**
+
+When a long operation completes, the agent synthesizes the result with any interim conversation that occurred, providing a natural, coherent response.
+
+## Usage
+
+### Input Format
+
+The agent now expects an `input_dict` instead of a simple message list:
+
+```python
+input_dict = {
+    "messages": [HumanMessage(content="Close my contract")],
+    "thread_type": "main",  # or "secondary"
+    "interim_messages_reset": True  # Reset interim conversation tracking
+}
+```
+
+### Configuration
+
+The agent requires a `namespace_for_memory` in the config for coordination:
+
+```python
+config = {
+    "configurable": {
+        "thread_id": "main-thread-123",
+        "namespace_for_memory": ("user_id", "tools_updates")
+    }
+}
+```
+
+### Example Client Usage
+
+```python
+import uuid
+import threading
+from langchain_core.messages import HumanMessage, AIMessage
+from langgraph.store.memory import InMemoryStore
+
+# Initialize
+store = InMemoryStore()
+thread_id_main = str(uuid.uuid4())
+thread_id_secondary = str(uuid.uuid4())
+namespace = ("user_123", "telco_ops")
+
+config_main = {
+    "configurable": {
+        "thread_id": thread_id_main,
+        "namespace_for_memory": namespace
+    }
+}
+
+config_secondary = {
+    "configurable": {
+        "thread_id": thread_id_secondary,
+        "namespace_for_memory": namespace
+    }
+}
+
+# Main thread (long operation - non-blocking)
+def run_main_operation():
+    result = agent.invoke(
+        {
+            "messages": [HumanMessage(content="Change my package to Premium")],
+            "thread_type": "main",
+            "interim_messages_reset": True
+        },
+        config=config_main,
+        store=store
+    )
+    print(f"Main: {result[-1].content}")
+
+# Start long operation in background
+main_thread = threading.Thread(target=run_main_operation)
+main_thread.start()
+
+# While main is running, handle secondary queries
+time.sleep(2)  # Let main operation start
+
+result = agent.invoke(
+    {
+        "messages": [HumanMessage(content="What's the status?")],
+        "thread_type": "secondary",
+        "interim_messages_reset": False
+    },
+    config=config_secondary,
+    store=store
+)
+print(f"Secondary: {result[-1].content}")
+
+# Wait for main to complete
+main_thread.join()
+```
+
+## Coordination Mechanism
+
+The agent uses the LangGraph store for thread coordination:
+
+### Store Keys
+
+- `working-tool-status-update`: Current tool progress and status
+- `secondary_status`: Lock indicating secondary thread processing state
+- `secondary_abort`: Abort signal for terminating secondary thread
+- `secondary_interim_messages`: Interim conversation to be synthesized
+
+### State Management
+
+The agent maintains two message lists:
+
+1. `messages`: Full conversation history
+2. `interim_messages`: Messages exchanged during long operations (for synthesis)
+
+## Architecture
+
+```
+User Request
+     │
+     ├─ Long Operation? ───► Main Thread
+     │                        │
+     │                        ├─ Execute Tool (with progress reporting)
+     │                        │
+     │                        └─ Wait for Secondary + Synthesize
+     │
+     └─ Quick Query? ──────► Secondary Thread
+                              │
+                              ├─ Handle query (limited tools)
+                              │
+                              └─ Store interim messages
+```
+
+## Safety Features
+
+1. **Processing Locks**: Prevent race conditions during state updates
+2. **Abort Signals**: Gracefully terminate secondary thread if main completes
+3. **Timeouts**: Main thread waits max 15 seconds for secondary to finish
+4. **Message Sanitization**: Removes orphan tool messages to prevent API errors
+
+## Testing
+
+To test the multi-threaded behavior, you can simulate long operations:
+
+```python
+# Test 1: Long operation without interruption
+response = agent.invoke({
+    "messages": [HumanMessage(content="Close my contract")],
+    "thread_type": "main",
+    "interim_messages_reset": True
+}, config=config_main, store=store)
+
+# Test 2: Long operation with status check
+# (Start main in background, then query status)
+
+# Test 3: Multiple secondary queries during long operation
+```
+
+## Environment Variables
+
+- `REACT_MODEL`: Model for main thread (default: gpt-4o)
+- `RBC_FEES_MAX_MSGS`: Max messages to keep in context (default: 40)
+- `TELCO_DEBUG`: Enable debug logging (default: 0)
+
+## Migration Notes
+
+If you have existing code using the old agent format:
+
+**Before:**
+```python
+result = agent.invoke(
+    [HumanMessage(content="Hello")],
+    config=config
+)
+```
+
+**After:**
+```python
+result = agent.invoke(
+    {
+        "messages": [HumanMessage(content="Hello")],
+        "thread_type": "main",
+        "interim_messages_reset": True
+    },
+    config=config,
+    store=store
+)
+```
+
+The state format has also changed from `List[BaseMessage]` to `Dict[str, List[BaseMessage]]` with keys `messages` and `interim_messages`.
+
+
+

examples/voice_agent_multi_thread/agents/telco-agent-multi/README.md

@@ -0,0 +1,57 @@
+# Telco Agent
+
+A mobile operator assistant that verifies callers via SMS OTP, reviews current plan and data usage, answers roaming questions, recommends packages, manages addons and plan changes, and can close contracts (mock).
+
+## How to use
+
+1. Provide your mobile number (MSISDN). The agent will send an SMS OTP.
+2. Provide the 6-digit code to verify.
+3. Ask for:
+   - Current package and contract status
+   - Current data balance/remaining
+   - Roaming details for a country (pricing and passes)
+   - Package recommendations (optionally give preferences: budget, need_5g, travel_country)
+   - Close contract (the agent summarizes any early termination fee and asks for confirmation)
+   - Addons list or purchase a roaming pass
+   - Change package (now or next_cycle)
+   - Billing summary and set data alerts
+
+## Mock data
+
+From `mock_data/`:
+
+- Customers (`customers.json`):
+  - `+15551234567` (Alex Lee): package `P-40` Standard 40GB 5G, billing cycle day 5, current_month used 12.5 GB.
+  - `+447911123456` (Sam Taylor): package `P-10` Lite 10GB 4G.
+- OTPs (`otps.json`):
+  - default: `123456`
+  - by number: `+15551234567` → `246810`, `+447911123456` → `135790`
+- Packages (`packages.json`): 4G/5G plans including Unlimited options with features like EU roaming and data rollover.
+- Roaming rates (`roaming_rates.json`): pay-as-you-go and pass options for `IT`, `FR`, `US`.
+
+## Example conversation
+
+- Agent: Hi! What’s your mobile number?
+- You: +1 555 123 4567
+- Agent: I’ve sent a 6-digit code to ***-***-**67. What’s the code?
+- You: 246810
+- Agent: Verified. Would you like your current package or data balance?
+- You: What’s my data balance?
+- Agent: You’ve used 12.5 GB this cycle on Standard 40GB 5G; 27.5 GB remaining. Anything else?
+- You: I’m traveling to Italy. Roaming?
+- Agent: Italy is included by your plan; passes also available (EU Day 1GB €5, Week 5GB €15). Purchase a pass?
+- You: Recommend a cheaper plan under $50, 5G.
+- Agent: Suggesting Travelers EU 20GB ($45): 5G, EU roaming included. Estimated monthly cost $45.
+
+## Extended actions (tools)
+
+- List addons: active roaming passes
+- Purchase roaming pass: e.g., country `IT`, pass `EU-WEEK-5GB`
+- Change package: `change_package(now|next_cycle)`
+- Billing summary: monthly fee and last bill
+- Set data alerts: by percent and/or GB
+
+## Notes
+
+- OTP is required before any account operations.
+- Recommendations use recent usage history to estimate monthly costs.

examples/voice_agent_multi_thread/agents/telco-agent-multi/__init__.py

@@ -0,0 +1,10 @@
+"""Telco Assistant Agent (ReAct)
+
+This package contains a LangGraph ReAct-based assistant for a mobile operator.
+It verifies callers via SMS OTP, can review current plans and data usage,
+answer roaming questions, recommend packages, and close contracts (mock).
+"""
+
+from .react_agent import agent  # noqa: F401
+
+

examples/voice_agent_multi_thread/agents/telco-agent-multi/example_multi_thread.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+"""
+Example script demonstrating multi-threaded telco agent usage.
+
+This script shows how to:
+1. Start a long-running operation (main thread)
+2. Handle interim queries (secondary thread) while the operation runs
+3. Let the agent synthesize the final response
+
+Usage:
+    python example_multi_thread.py
+"""
+
+import os
+import sys
+import time
+import uuid
+import threading
+import queue
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from langchain_core.messages import HumanMessage, AIMessage
+from langgraph.store.memory import InMemoryStore
+
+# Import the agent
+from react_agent import agent
+
+# Setup
+store = InMemoryStore()
+thread_id_main = str(uuid.uuid4())
+thread_id_secondary = str(uuid.uuid4())
+
+user_id = "demo_user"
+namespace_for_memory = (user_id, "telco_operations")
+
+config_main = {
+    "configurable": {
+        "thread_id": thread_id_main,
+        "namespace_for_memory": namespace_for_memory
+    }
+}
+
+config_secondary = {
+    "configurable": {
+        "thread_id": thread_id_secondary,
+        "namespace_for_memory": namespace_for_memory
+    }
+}
+
+print("=" * 60)
+print("Multi-Threaded Telco Agent Demo")
+print("=" * 60)
+print(f"Main Thread ID: {thread_id_main}")
+print(f"Secondary Thread ID: {thread_id_secondary}")
+print(f"Namespace: {namespace_for_memory}")
+print("=" * 60)
+print()
+
+# Thread-safe printing
+print_lock = threading.Lock()
+
+def safe_print(text: str) -> None:
+    with print_lock:
+        print(text)
+
+def run_agent_stream(user_text: str, thread_type: str, config: dict, interim_reset: bool) -> None:
+    """Run agent and print results."""
+    messages = [HumanMessage(content=user_text)]
+    try:
+        for mode, chunk in agent.stream(
+            {
+                "messages": messages,
+                "thread_type": thread_type,
+                "interim_messages_reset": interim_reset
+            },
+            stream_mode=["custom", "values"],
+            config=config,
+            store=store
+        ):
+            if isinstance(chunk, list) and chunk:
+                ai_messages = [m for m in chunk if isinstance(m, AIMessage)]
+                if ai_messages:
+                    safe_print(f"[{thread_type}] {ai_messages[-1].content}")
+            elif isinstance(chunk, str):
+                safe_print(f"[{thread_type}] {chunk}")
+    except Exception as e:
+        safe_print(f"[{thread_type} ERROR] {e!r}")
+
+# ============================================================================
+# Demo Scenario 1: Long operation with status checks
+# ============================================================================
+
+print("SCENARIO 1: Long operation with interim status checks")
+print("-" * 60)
+
+# Start a long-running operation in the background
+print("\n>>> User: 'Change my package to Premium Plus'")
+print(">>> (Starting main thread in background...)")
+print()
+
+main_job = threading.Thread(
+    target=run_agent_stream,
+    args=("Change my package to Premium Plus", "main", config_main, True),
+    daemon=True
+)
+main_job.start()
+
+# Wait a bit for the operation to start
+time.sleep(3)
+
+# Now user asks about status (secondary thread)
+print("\n>>> User: 'What's the status of my request?'")
+print(">>> (Handled by secondary thread...)")
+print()
+run_agent_stream("What's the status of my request?", "secondary", config_secondary, False)
+
+# Another query while main is still running
+time.sleep(2)
+print("\n>>> User: 'How much data do I have left?'")
+print(">>> (Handled by secondary thread...)")
+print()
+run_agent_stream("How much data do I have left?", "secondary", config_secondary, False)
+
+# Wait for main operation to complete
+main_job.join()
+
+print("\n" + "=" * 60)
+print("Main operation completed and synthesized with interim conversation!")
+print("=" * 60)
+
+# ============================================================================
+# Demo Scenario 2: Quick query (no multi-threading needed)
+# ============================================================================
+
+print("\n\nSCENARIO 2: Quick query (synchronous)")
+print("-" * 60)
+
+print("\n>>> User: 'What's my current package?'")
+print(">>> (Quick query, handled synchronously...)")
+print()
+run_agent_stream("What's my current package?", "main", config_main, True)
+
+# ============================================================================
+# Demo Scenario 3: Interactive mode
+# ============================================================================
+
+print("\n\nSCENARIO 3: Interactive mode")
+print("-" * 60)
+print("Type your messages. Long operations will run in background.")
+print("Type 'exit' to quit.")
+print("-" * 60)
+
+input_queue: "queue.Queue[str]" = queue.Queue()
+stop_event = threading.Event()
+main_job_active = None
+interim_reset = True
+
+def input_reader() -> None:
+    try:
+        while not stop_event.is_set():
+            try:
+                user_text = input("\nYou: ").strip()
+            except (KeyboardInterrupt, EOFError):
+                user_text = "exit"
+            if not user_text:
+                continue
+            input_queue.put(user_text)
+            if user_text.lower() in {"exit", "quit"}:
+                break
+    finally:
+        pass
+
+reader_thread = threading.Thread(target=input_reader, daemon=True)
+reader_thread.start()
+
+try:
+    while True:
+        try:
+            user_text = input_queue.get(timeout=0.1)
+        except queue.Empty:
+            continue
+
+        if not user_text:
+            continue
+
+        if user_text.lower() in {"exit", "quit"}:
+            stop_event.set()
+            break
+
+        # Check if main thread is active
+        main_active = main_job_active is not None and main_job_active.is_alive()
+        
+        # Check store for running status
+        memories = store.search(namespace_for_memory)
+        current_status = None
+        if memories:
+            try:
+                md = list(memories)[-1].value
+                current_status = md.get("status")
+            except Exception:
+                pass
+
+        if current_status == "running" or main_active:
+            # Secondary thread (synchronous)
+            safe_print("\n>>> (Long operation in progress, using secondary thread...)")
+            run_agent_stream(user_text, "secondary", config_secondary, False)
+            interim_reset = False
+        else:
+            # Main thread (background)
+            safe_print("\n>>> (Starting operation in background...)")
+            interim_reset = True
+            t = threading.Thread(
+                target=run_agent_stream,
+                args=(user_text, "main", config_main, interim_reset),
+                daemon=True
+            )
+            main_job_active = t
+            t.start()
+
+except Exception as e:
+    safe_print(f"\n[FATAL ERROR] {e!r}")
+finally:
+    stop_event.set()
+    if main_job_active is not None:
+        main_job_active.join(timeout=5)
+
+print("\n\nDemo completed!")
+
+
+

examples/voice_agent_multi_thread/agents/telco-agent-multi/logic.py

@@ -0,0 +1,1003 @@
+import os
+import json
+import uuid
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+
+# Telco in-memory stores and fixture cache
+_FIXTURE_CACHE: Dict[str, Any] = {}
+_SESSIONS: Dict[str, Dict[str, Any]] = {}
+_OTP_DB: Dict[str, Dict[str, Any]] = {}
+
+
+def _fixtures_dir() -> Path:
+    return Path(__file__).parent / "mock_data"
+
+
+def _load_fixture(name: str) -> Any:
+    if name in _FIXTURE_CACHE:
+        return _FIXTURE_CACHE[name]
+    p = _fixtures_dir() / name
+    with p.open("r", encoding="utf-8") as f:
+        data = json.load(f)
+    _FIXTURE_CACHE[name] = data
+    return data
+
+
+def _normalize_msisdn(msisdn: Optional[str]) -> Optional[str]:
+    if not isinstance(msisdn, str) or not msisdn.strip():
+        return None
+    s = msisdn.strip()
+    digits = ''.join(ch for ch in s if ch.isdigit() or ch == '+')
+    if digits.startswith('+'):
+        return digits
+    return f"+{digits}"
+
+
+def _get_customer(msisdn: str) -> Dict[str, Any]:
+    ms = _normalize_msisdn(msisdn) or ""
+    data = _load_fixture("customers.json")
+    return dict((data.get("customers", {}) or {}).get(ms, {}))
+
+
+def _get_package(package_id: str) -> Dict[str, Any]:
+    pkgs = _load_fixture("packages.json").get("packages", [])
+    for p in pkgs:
+        if str(p.get("id")) == str(package_id):
+            return dict(p)
+    return {}
+
+
+def _get_roaming_country(country_code: str) -> Dict[str, Any]:
+    data = _load_fixture("roaming_rates.json")
+    return dict((data.get("countries", {}) or {}).get((country_code or "").upper(), {}))
+
+
+def _mask_phone(msisdn: str) -> str:
+    s = _normalize_msisdn(msisdn) or ""
+    tail = s[-2:] if len(s) >= 2 else s
+    return f"***-***-**{tail}"
+
+
+# --- Identity via SMS OTP ---
+
+def start_login(session_id: str, msisdn: str) -> Dict[str, Any]:
+    ms = _normalize_msisdn(msisdn)
+    if not ms:
+        return {"sent": False, "error": "invalid_msisdn"}
+    cust = _get_customer(ms)
+    if not cust:
+        return {"sent": False, "reason": "not_found"}
+    static = None
+    try:
+        data = _load_fixture("otps.json")
+        if isinstance(data, dict):
+            byn = data.get("by_number", {}) or {}
+            static = byn.get(ms) or data.get("default")
+    except Exception:
+        static = None
+    code = str(static or f"{uuid.uuid4().int % 1000000:06d}").zfill(6)
+    _OTP_DB[ms] = {"otp": code, "created_at": datetime.utcnow().isoformat() + "Z"}
+    _SESSIONS[session_id] = {"verified": False, "msisdn": ms}
+    resp: Dict[str, Any] = {"sent": True, "masked": _mask_phone(ms), "destination": "sms"}
+    try:
+        if os.getenv("TELCO_DEBUG_OTP", "0").lower() not in ("", "0", "false"):
+            resp["debug_code"] = code
+    except Exception:
+        pass
+    return resp
+
+
+def verify_login(session_id: str, msisdn: str, otp: str) -> Dict[str, Any]:
+    ms = _normalize_msisdn(msisdn) or ""
+    rec = _OTP_DB.get(ms) or {}
+    ok = str(rec.get("otp")) == str(otp)
+    sess = _SESSIONS.get(session_id) or {"verified": False}
+    if ok:
+        rec["used_at"] = datetime.utcnow().isoformat() + "Z"
+        _OTP_DB[ms] = rec
+        sess["verified"] = True
+        sess["msisdn"] = ms
+    _SESSIONS[session_id] = sess
+    return {"session_id": session_id, "verified": ok, "msisdn": ms}
+
+
+# --- Customer and package information ---
+
+def get_current_package(msisdn: str) -> Dict[str, Any]:
+    cust = _get_customer(msisdn)
+    if not cust:
+        return {"error": "not_found"}
+    pkg = _get_package(cust.get("package_id", ""))
+    return {
+        "msisdn": _normalize_msisdn(msisdn),
+        "package": pkg,
+        "contract": cust.get("contract"),
+        "addons": list(cust.get("addons", [])),
+    }
+
+
+def get_data_balance(msisdn: str) -> Dict[str, Any]:
+    cust = _get_customer(msisdn)
+    if not cust:
+        return {"error": "not_found"}
+    pkg = _get_package(cust.get("package_id", ""))
+    usage = (cust.get("usage", {}) or {}).get("current_month", {})
+    included = float(pkg.get("data_gb", 0)) if not bool(pkg.get("unlimited", False)) else None
+    used = float(usage.get("data_gb_used", 0.0))
+    remaining = None if included is None else max(0.0, included - used)
+    return {
+        "msisdn": _normalize_msisdn(msisdn),
+        "unlimited": bool(pkg.get("unlimited", False)),
+        "included_gb": included,
+        "used_gb": round(used, 2),
+        "remaining_gb": (None if remaining is None else round(remaining, 2)),
+        "resets_day": int((cust.get("billing", {}) or {}).get("cycle_day", 1)),
+    }
+
+
+def list_available_packages() -> List[Dict[str, Any]]:
+    return list(_load_fixture("packages.json").get("packages", []))
+
+
+def _estimate_monthly_cost_for_usage(pkg: Dict[str, Any], avg_data_gb: float, avg_minutes: int, avg_sms: int) -> float:
+    if bool(pkg.get("unlimited", False)):
+        return float(pkg.get("monthly_fee", 0.0))
+    fee = float(pkg.get("monthly_fee", 0.0))
+    data_over = max(0.0, avg_data_gb - float(pkg.get("data_gb", 0.0)))
+    min_over = max(0, avg_minutes - int(pkg.get("minutes", 0)))
+    sms_over = max(0, avg_sms - int(pkg.get("sms", 0)))
+    rates = pkg.get("overage", {}) or {}
+    over = data_over * float(rates.get("per_gb", 0.0)) + min_over * float(rates.get("per_min", 0.0)) + sms_over * float(rates.get("per_sms", 0.0))
+    return round(fee + over, 2)
+
+
+def recommend_packages(msisdn: str, preferences: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    cust = _get_customer(msisdn)
+    if not cust:
+        return {"error": "not_found"}
+    prefs = preferences or {}
+    hist = (cust.get("usage", {}) or {}).get("history", [])
+    if hist:
+        last = hist[-3:]
+        avg_data = sum(float(m.get("data_gb", 0)) for m in last) / len(last)
+        avg_min = int(sum(int(m.get("minutes", 0)) for m in last) / len(last))
+        avg_sms = int(sum(int(m.get("sms", 0)) for m in last) / len(last))
+    else:
+        avg = (cust.get("usage", {}) or {}).get("monthly_avg", {})
+        avg_data = float(avg.get("data_gb", 10.0))
+        avg_min = int(avg.get("minutes", 300))
+        avg_sms = int(avg.get("sms", 100))
+    wants_5g = bool(prefs.get("need_5g", False))
+    travel_country = (prefs.get("travel_country") or "").upper()
+    budget = float(prefs.get("budget", 9999))
+
+    pkgs = list_available_packages()
+    scored: List[Tuple[float, Dict[str, Any], Dict[str, Any]]] = []
+    for p in pkgs:
+        if wants_5g and not bool(p.get("fiveg", False)):
+            continue
+        if budget < float(p.get("monthly_fee", 0.0)):
+            continue
+        est = _estimate_monthly_cost_for_usage(p, avg_data, avg_min, avg_sms)
+        feature_bonus = 0.0
+        if travel_country:
+            if travel_country in set(p.get("roam_included_countries", [])):
+                feature_bonus -= 5.0
+        if bool(p.get("data_rollover", False)):
+            feature_bonus -= 1.0
+        score = est + feature_bonus
+        rationale = f"Estimated monthly cost {est:.2f}; {'5G' if p.get('fiveg') else '4G'}; "
+        if travel_country:
+            rationale += ("roam-included" if travel_country in (p.get("roam_included_countries") or []) else "roam-paygo")
+        scored.append((score, p, {"estimated_cost": est, "rationale": rationale}))
+
+    scored.sort(key=lambda x: x[0])
+    top = [
+        {
+            "package": pkg,
+            "estimated_monthly_cost": meta.get("estimated_cost"),
+            "rationale": meta.get("rationale"),
+        }
+        for _, pkg, meta in scored[:3]
+    ]
+    return {
+        "msisdn": _normalize_msisdn(msisdn),
+        "based_on": {
+            "avg_data_gb": round(avg_data, 2),
+            "avg_minutes": avg_min,
+            "avg_sms": avg_sms,
+            "wants_5g": wants_5g,
+            "travel_country": travel_country or None,
+            "budget": budget
+        },
+        "recommendations": top,
+    }
+
+
+def get_roaming_info(msisdn: str, country_code: str) -> Dict[str, Any]:
+    cust = _get_customer(msisdn)
+    if not cust:
+        return {"error": "not_found"}
+    pkg = _get_package(cust.get("package_id", ""))
+    country = _get_roaming_country(country_code)
+    included = country_code.upper() in set((pkg.get("roam_included_countries") or [])) or (bool(pkg.get("eu_roaming", False)) and country.get("region") == "EU")
+    info = {
+        "country": country_code.upper(),
+        "included": bool(included),
+        "paygo": country.get("paygo"),
+        "passes": country.get("passes", []),
+    }
+    return {"msisdn": _normalize_msisdn(msisdn), "package": {"id": pkg.get("id"), "name": pkg.get("name")}, "roaming": info}
+
+
+def close_contract(msisdn: str, confirm: bool = False) -> Dict[str, Any]:
+    cust = _get_customer(msisdn)
+    if not cust:
+        return {"error": "not_found"}
+    contract = dict(cust.get("contract", {}))
+    if contract.get("status") == "closed":
+        return {"status": "already_closed"}
+    try:
+        end = contract.get("end_date")
+        future = datetime.fromisoformat(end) if isinstance(end, str) and end else datetime.max
+    except Exception:
+        future = datetime.max
+    fee = float(contract.get("early_termination_fee", 0.0)) if future > datetime.utcnow() else 0.0
+    summary = {
+        "msisdn": _normalize_msisdn(msisdn),
+        "current_status": contract.get("status", "active"),
+        "early_termination_fee": round(fee, 2),
+        "will_cancel": bool(confirm),
+    }
+    if confirm:
+        contract["status"] = "closed"
+        contract["closed_at"] = datetime.utcnow().isoformat() + "Z"
+        cust["contract"] = contract
+        data = _load_fixture("customers.json")
+        ms = _normalize_msisdn(msisdn)
+        try:
+            data.setdefault("customers", {})[ms] = cust
+            _FIXTURE_CACHE["customers.json"] = data
+        except Exception:
+            pass
+        summary["new_status"] = "closed"
+    return summary
+
+
+# --- Extended utilities ---
+
+def list_addons(msisdn: str) -> Dict[str, Any]:
+    cust = _get_customer(msisdn)
+    if not cust:
+        return {"error": "not_found"}
+    return {"msisdn": _normalize_msisdn(msisdn), "addons": list(cust.get("addons", []))}
+
+
+def purchase_roaming_pass(msisdn: str, country_code: str, pass_id: str) -> Dict[str, Any]:
+    cust = _get_customer(msisdn)
+    if not cust:
+        return {"error": "not_found"}
+    country = _get_roaming_country(country_code)
+    passes = country.get("passes", [])
+    sel = None
+    for p in passes:
+        if str(p.get("id")) == str(pass_id):
+            sel = p
+            break
+    if not sel:
+        return {"error": "invalid_pass"}
+    valid_days = int(sel.get("valid_days", 1))
+    addon = {
+        "type": "roaming_pass",
+        "country": (country_code or "").upper(),
+        "data_mb": int(sel.get("data_mb", 0)),
+        "price": float(sel.get("price", 0.0)),
+        "purchased_at": datetime.utcnow().isoformat() + "Z",
+        "expires": (datetime.utcnow() + timedelta(days=valid_days)).date().isoformat()
+    }
+    try:
+        cust.setdefault("addons", []).append(addon)
+        data = _load_fixture("customers.json")
+        ms = _normalize_msisdn(msisdn)
+        data.setdefault("customers", {})[ms] = cust
+        _FIXTURE_CACHE["customers.json"] = data
+    except Exception:
+        pass
+    return {"msisdn": _normalize_msisdn(msisdn), "added": addon}
+
+
+def change_package(msisdn: str, package_id: str, effective: str = "next_cycle") -> Dict[str, Any]:
+    cust = _get_customer(msisdn)
+    if not cust:
+        return {"error": "not_found"}
+    new_pkg = _get_package(package_id)
+    if not new_pkg:
+        return {"error": "invalid_package"}
+    effective_when = (effective or "next_cycle").lower()
+    if effective_when not in ("now", "next_cycle"):
+        effective_when = "next_cycle"
+    summary = {
+        "msisdn": _normalize_msisdn(msisdn),
+        "current_package_id": cust.get("package_id"),
+        "new_package_id": new_pkg.get("id"),
+        "effective": effective_when,
+    }
+    data = _load_fixture("customers.json")
+    ms = _normalize_msisdn(msisdn)
+    if effective_when == "now":
+        cust["package_id"] = new_pkg.get("id")
+        summary["status"] = "changed"
+    else:
+        contract = dict(cust.get("contract", {}))
+        contract["pending_change"] = {"package_id": new_pkg.get("id"), "requested_at": datetime.utcnow().isoformat() + "Z"}
+        cust["contract"] = contract
+        summary["status"] = "scheduled"
+    try:
+        data.setdefault("customers", {})[ms] = cust
+        _FIXTURE_CACHE["customers.json"] = data
+    except Exception:
+        pass
+    return summary
+
+
+def get_billing_summary(msisdn: str) -> Dict[str, Any]:
+    cust = _get_customer(msisdn)
+    if not cust:
+        return {"error": "not_found"}
+    pkg = _get_package(cust.get("package_id", ""))
+    bill = dict(cust.get("billing", {}))
+    monthly_fee = float(pkg.get("monthly_fee", 0.0))
+    return {
+        "msisdn": _normalize_msisdn(msisdn),
+        "last_bill_amount": bill.get("last_bill_amount"),
+        "cycle_day": bill.get("cycle_day"),
+        "monthly_fee": monthly_fee,
+    }
+
+
+def set_data_alerts(msisdn: str, threshold_percent: Optional[int] = None, threshold_gb: Optional[float] = None) -> Dict[str, Any]:
+    if threshold_percent is None and threshold_gb is None:
+        return {"error": "invalid_threshold"}
+    cust = _get_customer(msisdn)
+    if not cust:
+        return {"error": "not_found"}
+    alerts = dict(cust.get("alerts", {}))
+    if isinstance(threshold_percent, int):
+        alerts["data_threshold_percent"] = max(1, min(100, threshold_percent))
+    if isinstance(threshold_gb, (int, float)):
+        alerts["data_threshold_gb"] = max(0.1, float(threshold_gb))
+    cust["alerts"] = alerts
+    try:
+        data = _load_fixture("customers.json")
+        ms = _normalize_msisdn(msisdn)
+        data.setdefault("customers", {})[ms] = cust
+        _FIXTURE_CACHE["customers.json"] = data
+    except Exception:
+        pass
+    return {"msisdn": _normalize_msisdn(msisdn), "alerts": alerts}
+
+import os
+import json
+import uuid
+from datetime import datetime
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from langchain_openai import ChatOpenAI
+
+
+_FIXTURE_CACHE: Dict[str, Any] = {}
+_DISPUTES_DB: Dict[str, Dict[str, Any]] = {}
+_SESSIONS: Dict[str, Dict[str, Any]] = {}
+_OTP_DB: Dict[str, Dict[str, Any]] = {}
+_QUOTES: Dict[str, Dict[str, Any]] = {}
+_BENEFICIARIES_DB: Dict[str, List[Dict[str, Any]]] = {}
+
+
+def _fixtures_dir() -> Path:
+    return Path(__file__).parent / "mock_data"
+
+
+def _load_fixture(name: str) -> Any:
+    if name in _FIXTURE_CACHE:
+        return _FIXTURE_CACHE[name]
+    p = _fixtures_dir() / name
+    with p.open("r", encoding="utf-8") as f:
+        data = json.load(f)
+    _FIXTURE_CACHE[name] = data
+    return data
+
+
+def _parse_iso_date(text: Optional[str]) -> Optional[datetime]:
+    if not text:
+        return None
+    try:
+        return datetime.strptime(text, "%Y-%m-%d")
+    except Exception:
+        return None
+
+
+def _get_customer_blob(customer_id: str) -> Dict[str, Any]:
+    data = _load_fixture("accounts.json")
+    return dict(data.get("customers", {}).get(customer_id, {}))
+
+
+def get_accounts(customer_id: str) -> List[Dict[str, Any]]:
+    cust = _get_customer_blob(customer_id)
+    if isinstance(cust, list):
+        # backward-compat: old format was a list of accounts
+        return list(cust)
+    return list(cust.get("accounts", []))
+
+
+def get_profile(customer_id: str) -> Dict[str, Any]:
+    cust = _get_customer_blob(customer_id)
+    if isinstance(cust, dict):
+        return dict(cust.get("profile", {}))
+    return {}
+
+
+def find_customer_by_name(first_name: str, last_name: str) -> Dict[str, Any]:
+    data = _load_fixture("accounts.json")
+    customers = data.get("customers", {})
+    fn = (first_name or "").strip().lower()
+    ln = (last_name or "").strip().lower()
+    for cid, blob in customers.items():
+        prof = blob.get("profile") if isinstance(blob, dict) else None
+        if isinstance(prof, dict):
+            pfn = str(prof.get("first_name") or "").strip().lower()
+            pln = str(prof.get("last_name") or "").strip().lower()
+            if fn == pfn and ln == pln:
+                return {"customer_id": cid, "profile": prof}
+    return {}
+
+
+def find_customer_by_full_name(full_name: str) -> Dict[str, Any]:
+    data = _load_fixture("accounts.json")
+    customers = data.get("customers", {})
+    target = (full_name or "").strip().lower()
+    for cid, blob in customers.items():
+        prof = blob.get("profile") if isinstance(blob, dict) else None
+        if isinstance(prof, dict):
+            fn = f"{str(prof.get('first_name') or '').strip()} {str(prof.get('last_name') or '').strip()}".strip().lower()
+            ff = str(prof.get("full_name") or "").strip().lower()
+            if target and (target == fn or target == ff):
+                return {"customer_id": cid, "profile": prof}
+    return {}
+
+
+def _normalize_dob(text: Optional[str]) -> Optional[str]:
+    if not isinstance(text, str) or not text.strip():
+        return None
+    t = text.strip().lower()
+    # YYYY-MM-DD
+    try:
+        if len(t) >= 10 and t[4] == '-' and t[7] == '-':
+            d = datetime.strptime(t[:10], "%Y-%m-%d")
+            return d.strftime("%Y-%m-%d")
+    except Exception:
+        pass
+    # YYYY MM DD or YYYY/MM/DD or YYYY.MM.DD (loosely)
+    try:
+        import re as _re
+        parts = _re.findall(r"\d+", t)
+        if len(parts) >= 3 and len(parts[0]) == 4:
+            y, m, d = int(parts[0]), int(parts[1]), int(parts[2])
+            if 1900 <= y <= 2100 and 1 <= m <= 12 and 1 <= d <= 31:
+                dt = datetime(y, m, d)
+                return dt.strftime("%Y-%m-%d")
+    except Exception:
+        pass
+    # Month name DD YYYY
+    MONTHS = {
+        "jan": 1, "january": 1, "feb": 2, "february": 2, "mar": 3, "march": 3,
+        "apr": 4, "april": 4, "may": 5, "jun": 6, "june": 6, "jul": 7, "july": 7,
+        "aug": 8, "august": 8, "sep": 9, "sept": 9, "september": 9,
+        "oct": 10, "october": 10, "nov": 11, "november": 11, "dec": 12, "december": 12,
+    }
+    try:
+        parts = t.replace(',', ' ').split()
+        if len(parts) >= 3 and parts[0] in MONTHS:
+            m = MONTHS[parts[0]]
+            day = int(''.join(ch for ch in parts[1] if ch.isdigit()))
+            year = int(parts[2])
+            d = datetime(year, m, day)
+            return d.strftime("%Y-%m-%d")
+    except Exception:
+        pass
+    # DD/MM/YYYY or MM/DD/YYYY
+    try:
+        for sep in ('/', '-'):
+            if sep in t and t.count(sep) == 2:
+                a, b, c = t.split(sep)[:3]
+                if len(c) == 4 and a.isdigit() and b.isdigit() and c.isdigit():
+                    da, db, dy = int(a), int(b), int(c)
+                    # If first looks like month, assume MM/DD
+                    if 1 <= da <= 12 and 1 <= db <= 31:
+                        d = datetime(dy, da, db)
+                    else:
+                        # assume DD/MM
+                        d = datetime(dy, db, da)
+                    return d.strftime("%Y-%m-%d")
+    except Exception:
+        pass
+    return None
+
+
+def _find_account_by_id(account_id: str) -> Optional[Dict[str, Any]]:
+    data = _load_fixture("accounts.json")
+    customers = data.get("customers", {})
+    for _, blob in customers.items():
+        accts = (blob or {}).get("accounts", [])
+        for a in accts or []:
+            if str(a.get("account_id")) == account_id:
+                return a
+    return None
+
+
+def get_account_balance(account_id: str) -> Dict[str, Any]:
+    acc = _find_account_by_id(account_id) or {}
+    return {
+        "account_id": account_id,
+        "currency": acc.get("currency"),
+        "balance": float(acc.get("balance", 0.0)),
+        "daily_wire_limit": float(acc.get("daily_wire_limit", 0.0)),
+        "wire_enabled": bool(acc.get("wire_enabled", False)),
+    }
+
+
+def get_exchange_rate(from_currency: str, to_currency: str, amount: float) -> Dict[str, Any]:
+    if from_currency.upper() == to_currency.upper():
+        return {
+            "from": from_currency.upper(),
+            "to": to_currency.upper(),
+            "mid_rate": 1.0,
+            "applied_rate": 1.0,
+            "margin_bps": 0,
+            "converted_amount": round(float(amount), 2),
+        }
+    data = _load_fixture("exchange_rates.json")
+    pairs = data.get("pairs", [])
+    mid = None
+    bps = 150
+    fc = from_currency.upper()
+    tc = to_currency.upper()
+    for p in pairs:
+        if str(p.get("from")).upper() == fc and str(p.get("to")).upper() == tc:
+            mid = float(p.get("mid_rate"))
+            bps = int(p.get("margin_bps", bps))
+            break
+    if mid is None:
+        # naive inverse lookup
+        for p in pairs:
+            if str(p.get("from")).upper() == tc and str(p.get("to")).upper() == fc:
+                inv = float(p.get("mid_rate"))
+                mid = 1.0 / inv if inv else None
+                bps = int(p.get("margin_bps", bps))
+                break
+    if mid is None:
+        mid = 1.0
+    applied = mid * (1.0 - bps / 10000.0)
+    converted = float(amount) * applied
+    return {
+        "from": fc,
+        "to": tc,
+        "mid_rate": round(mid, 6),
+        "applied_rate": round(applied, 6),
+        "margin_bps": bps,
+        "converted_amount": round(converted, 2),
+    }
+
+
+def calculate_wire_fee(kind: str, amount: float, from_currency: str, to_currency: str, payer: str) -> Dict[str, Any]:
+    fees = _load_fixture("fee_schedules.json")
+    k = (kind or "").strip().upper()
+    payer_opt = (payer or "SHA").strip().upper()
+    if k not in ("DOMESTIC", "INTERNATIONAL"):
+        return {"error": "invalid_type", "message": "type must be DOMESTIC or INTERNATIONAL"}
+    if payer_opt not in ("OUR", "SHA", "BEN"):
+        return {"error": "invalid_payer", "message": "payer must be OUR, SHA, or BEN"}
+    breakdown: Dict[str, float] = {}
+    if k == "DOMESTIC":
+        breakdown["DOMESTIC_BASE"] = float(fees.get("DOMESTIC", {}).get("base_fee", 15.0))
+    else:
+        intl = fees.get("INTERNATIONAL", {})
+        breakdown["INTERNATIONAL_BASE"] = float(intl.get("base_fee", 25.0))
+        breakdown["SWIFT"] = float(intl.get("swift_network_fee", 5.0))
+        breakdown["CORRESPONDENT"] = float(intl.get("correspondent_fee", 10.0))
+        breakdown["LIFTING"] = float(intl.get("lifting_fee", 5.0))
+
+    initiator = 0.0
+    recipient = 0.0
+    for code, fee in breakdown.items():
+        if payer_opt == "OUR":
+            initiator += fee
+        elif payer_opt == "SHA":
+            # Sender pays origin bank fees (base, swift); recipient pays intermediary (correspondent/lifting)
+            if code in ("DOMESTIC_BASE", "INTERNATIONAL_BASE", "SWIFT"):
+                initiator += fee
+            else:
+                recipient += fee
+        elif payer_opt == "BEN":
+            recipient += fee
+    return {
+        "type": k,
+        "payer": payer_opt,
+        "from_currency": from_currency.upper(),
+        "to_currency": to_currency.upper(),
+        "amount": float(amount),
+        "initiator_fees_total": round(initiator, 2),
+        "recipient_fees_total": round(recipient, 2),
+        "breakdown": {k: round(v, 2) for k, v in breakdown.items()},
+    }
+
+
+def screen_sanctions(name: str, country: str) -> Dict[str, Any]:
+    data = _load_fixture("sanctions_list.json")
+    blocked = data.get("blocked", [])
+    nm = (name or "").strip().lower()
+    cc = (country or "").strip().upper()
+    for e in blocked:
+        if str(e.get("name", "")).strip().lower() == nm and str(e.get("country", "")).strip().upper() == cc:
+            return {"cleared": False, "reason": "Sanctions match"}
+    return {"cleared": True}
+
+
+def check_wire_limits(account_id: str, amount: float) -> Dict[str, Any]:
+    acc = _find_account_by_id(account_id) or {}
+    if not acc:
+        return {"ok": False, "reason": "account_not_found"}
+    bal = float(acc.get("balance", 0.0))
+    lim = float(acc.get("daily_wire_limit", 0.0))
+    if not bool(acc.get("wire_enabled", False)):
+        return {"ok": False, "reason": "wire_not_enabled"}
+    if amount > lim:
+        return {"ok": False, "reason": "exceeds_daily_limit", "limit": lim}
+    if amount > bal:
+        return {"ok": False, "reason": "insufficient_funds", "balance": bal}
+    return {"ok": True, "balance": bal, "limit": lim}
+
+
+def get_cutoff_and_eta(kind: str, country: str) -> Dict[str, Any]:
+    cfg = _load_fixture("cutoff_times.json")
+    k = (kind or "").strip().upper()
+    key = "DOMESTIC" if k == "DOMESTIC" else "INTERNATIONAL"
+    info = cfg.get(key, {})
+    return {
+        "cutoff_local": info.get("cutoff_local", "17:00"),
+        "eta_hours": list(info.get("eta_hours", [24, 72])),
+        "country": country
+    }
+
+
+def get_country_requirements(code: str) -> List[str]:
+    data = _load_fixture("country_requirements.json")
+    return list(data.get(code.upper(), []))
+
+
+def validate_beneficiary(country_code: str, beneficiary: Dict[str, Any]) -> Dict[str, Any]:
+    required = get_country_requirements(country_code)
+    missing: List[str] = []
+    for field in required:
+        if not isinstance(beneficiary.get(field), str) or not str(beneficiary.get(field)).strip():
+            missing.append(field)
+    return {"ok": len(missing) == 0, "missing": missing}
+
+
+def save_beneficiary(customer_id: str, beneficiary: Dict[str, Any]) -> Dict[str, Any]:
+    arr = _BENEFICIARIES_DB.setdefault(customer_id, [])
+    bid = beneficiary.get("beneficiary_id") or f"B-{uuid.uuid4().hex[:6]}"
+    entry = dict(beneficiary)
+    entry["beneficiary_id"] = bid
+    arr.append(entry)
+    return {"beneficiary_id": bid}
+
+
+def generate_otp(customer_id: str) -> Dict[str, Any]:
+    # Prefer static OTP from fixture for predictable testing
+    static = None
+    try:
+        data = _load_fixture("otps.json")
+        if isinstance(data, dict):
+            byc = data.get("by_customer", {}) or {}
+            static = byc.get(customer_id) or data.get("default")
+    except Exception:
+        static = None
+    code = str(static or f"{uuid.uuid4().int % 1000000:06d}").zfill(6)
+    _OTP_DB[customer_id] = {"otp": code, "created_at": datetime.utcnow().isoformat() + "Z"}
+    # In real world, send to phone/email; here we mask
+    resp = {"sent": True, "destination": "on-file", "masked": "***-***-****"}
+    try:
+        if os.getenv("WIRE_DEBUG_OTP", "0").lower() not in ("", "0", "false"):  # dev convenience
+            resp["debug_code"] = code
+    except Exception:
+        pass
+    return resp
+
+
+def verify_otp(customer_id: str, otp: str) -> Dict[str, Any]:
+    rec = _OTP_DB.get(customer_id) or {}
+    ok = str(rec.get("otp")) == str(otp)
+    if ok:
+        rec["used_at"] = datetime.utcnow().isoformat() + "Z"
+        _OTP_DB[customer_id] = rec
+    return {"verified": ok}
+
+
+def authenticate_user_wire(session_id: str, customer_id: Optional[str], full_name: Optional[str], dob_yyyy_mm_dd: Optional[str], ssn_last4: Optional[str], secret_answer: Optional[str]) -> Dict[str, Any]:
+    session = _SESSIONS.get(session_id) or {"verified": False, "customer_id": customer_id, "name": full_name}
+    if isinstance(customer_id, str) and customer_id:
+        session["customer_id"] = customer_id
+    if isinstance(full_name, str) and full_name:
+        session["name"] = full_name
+    if isinstance(dob_yyyy_mm_dd, str) and dob_yyyy_mm_dd:
+        session["dob"] = dob_yyyy_mm_dd
+    if isinstance(ssn_last4, str) and ssn_last4:
+        session["ssn_last4"] = ssn_last4
+    if isinstance(secret_answer, str) and secret_answer:
+        session["secret"] = secret_answer
+
+    ok = False
+    cid = session.get("customer_id")
+    if isinstance(cid, str):
+        prof = get_profile(cid)
+        user_dob_norm = _normalize_dob(session.get("dob"))
+        prof_dob_norm = _normalize_dob(prof.get("dob"))
+        dob_ok = (user_dob_norm is not None) and (user_dob_norm == prof_dob_norm)
+        ssn_ok = str(session.get("ssn_last4") or "") == str(prof.get("ssn_last4") or "")
+        def _norm(x: Optional[str]) -> str:
+            return (x or "").strip().lower()
+        secret_ok = _norm(session.get("secret")) == _norm(prof.get("secret_answer"))
+        if dob_ok and (ssn_ok or secret_ok):
+            ok = True
+    session["verified"] = ok
+    _SESSIONS[session_id] = session
+    need: List[str] = []
+    if _normalize_dob(session.get("dob")) is None:
+        need.append("dob")
+    if not session.get("ssn_last4") and not session.get("secret"):
+        need.append("ssn_last4_or_secret")
+    if not session.get("customer_id"):
+        need.append("customer")
+    resp: Dict[str, Any] = {"session_id": session_id, "verified": ok, "needs": need, "profile": {"name": session.get("name")}}
+    try:
+        if isinstance(session.get("customer_id"), str):
+            prof = get_profile(session.get("customer_id"))
+            if isinstance(prof, dict) and prof.get("secret_question"):
+                resp["question"] = prof.get("secret_question")
+    except Exception:
+        pass
+    return resp
+
+
+def quote_wire(kind: str, from_account_id: str, beneficiary: Dict[str, Any], amount: float, from_currency: str, to_currency: str, payer: str) -> Dict[str, Any]:
+    # FX
+    fx = get_exchange_rate(from_currency, to_currency, amount)
+    converted_amount = fx["converted_amount"]
+    # Fees
+    fee = calculate_wire_fee(kind, amount, from_currency, to_currency, payer)
+    # Limits and balance
+    limits = check_wire_limits(from_account_id, amount)
+    if not limits.get("ok"):
+        return {"error": "limit_or_balance", "details": limits}
+    # Sanctions
+    sanc = screen_sanctions(str(beneficiary.get("account_name") or beneficiary.get("name") or ""), str(beneficiary.get("country") or ""))
+    if not sanc.get("cleared"):
+        return {"error": "sanctions", "details": sanc}
+    # ETA
+    eta = get_cutoff_and_eta(kind, str(beneficiary.get("country") or ""))
+
+    payer_opt = (payer or "SHA").upper()
+    initiator_fees = float(fee.get("initiator_fees_total", 0.0))
+    recipient_fees = float(fee.get("recipient_fees_total", 0.0))
+    net_sent = float(amount) + (initiator_fees if payer_opt in ("OUR", "SHA") else 0.0)
+    # recipient side fees reduce the amount received when SHA/BEN
+    net_received = float(converted_amount)
+    if payer_opt in ("SHA", "BEN"):
+        net_received = max(0.0, net_received - recipient_fees)
+
+    qid = f"Q-{uuid.uuid4().hex[:8]}"
+    quote = {
+        "quote_id": qid,
+        "type": kind.upper(),
+        "from_account_id": from_account_id,
+        "amount": float(amount),
+        "from_currency": from_currency.upper(),
+        "to_currency": to_currency.upper(),
+        "payer": payer_opt,
+        "fx": fx,
+        "fees": fee,
+        "net_sent": round(net_sent, 2),
+        "net_received": round(net_received, 2),
+        "eta": eta,
+        "created_at": datetime.utcnow().isoformat() + "Z",
+        "expires_at": (datetime.utcnow().isoformat() + "Z")
+    }
+    _QUOTES[qid] = quote
+    return quote
+
+
+def wire_transfer_domestic(quote_id: str, otp: str) -> Dict[str, Any]:
+    q = _QUOTES.get(quote_id)
+    if not q or q.get("type") != "DOMESTIC":
+        return {"error": "invalid_quote"}
+    # OTP expected: we need customer_id context; skip and assume OTP verified externally
+    conf = f"WD-{uuid.uuid4().hex[:8]}"
+    return {"confirmation_id": conf, "status": "submitted"}
+
+
+def wire_transfer_international(quote_id: str, otp: str) -> Dict[str, Any]:
+    q = _QUOTES.get(quote_id)
+    if not q or q.get("type") != "INTERNATIONAL":
+        return {"error": "invalid_quote"}
+    conf = f"WI-{uuid.uuid4().hex[:8]}"
+    return {"confirmation_id": conf, "status": "submitted"}
+
+
+def list_transactions(account_id: str, start: Optional[str], end: Optional[str]) -> List[Dict[str, Any]]:
+    data = _load_fixture("transactions.json")
+    txns = list(data.get(account_id, []))
+    if start or end:
+        start_dt = _parse_iso_date(start) or datetime.min
+        end_dt = _parse_iso_date(end) or datetime.max
+        out: List[Dict[str, Any]] = []
+        for t in txns:
+            td = _parse_iso_date(t.get("date"))
+            if td and start_dt <= td <= end_dt:
+                out.append(t)
+        return out
+    return txns
+
+
+def get_fee_schedule(product_type: str) -> Dict[str, Any]:
+    data = _load_fixture("fee_schedules.json")
+    return dict(data.get(product_type.upper(), {}))
+
+
+def detect_fees(transactions: List[Dict[str, Any]], schedule: Dict[str, Any]) -> List[Dict[str, Any]]:
+    results: List[Dict[str, Any]] = []
+    for t in transactions:
+        if str(t.get("entry_type")).upper() == "FEE":
+            fee_code = (t.get("fee_code") or "").upper()
+            sched_entry = None
+            for s in schedule.get("fees", []) or []:
+                if str(s.get("code", "")).upper() == fee_code:
+                    sched_entry = s
+                    break
+            evt = {
+                "id": t.get("id") or str(uuid.uuid4()),
+                "posted_date": t.get("date"),
+                "amount": float(t.get("amount", 0)),
+                "description": t.get("description") or fee_code,
+                "fee_code": fee_code,
+                "schedule": sched_entry or None,
+            }
+            results.append(evt)
+    try:
+        results.sort(key=lambda x: x.get("posted_date") or "")
+    except Exception:
+        pass
+    return results
+
+
+def explain_fee(fee_event: Dict[str, Any]) -> str:
+    openai_api_key = os.getenv("OPENAI_API_KEY")
+    code = (fee_event.get("fee_code") or "").upper()
+    name = fee_event.get("schedule", {}).get("name") or code.title()
+    posted = fee_event.get("posted_date") or ""
+    amount = float(fee_event.get("amount") or 0)
+    policy = fee_event.get("schedule", {}).get("policy") or ""
+    if not openai_api_key:
+        base = f"You were charged {name} on {posted} for CAD {amount:.2f}."
+        if code == "NSF":
+            return base + " This is applied when a payment is attempted but the account balance was insufficient."
+        if code == "MAINTENANCE":
+            return base + " This is the monthly account fee as per your account plan."
+        if code == "ATM":
+            return base + " This fee applies to certain ATM withdrawals."
+        return base + " This fee was identified based on your recent transactions."
+
+    llm = ChatOpenAI(model=os.getenv("EXPLAIN_MODEL", "gpt-4o"), api_key=openai_api_key)
+    chain = EXPLAIN_FEE_PROMPT | llm
+    out = chain.invoke(
+        {
+            "fee_code": code,
+            "posted_date": posted,
+            "amount": f"{amount:.2f}",
+            "schedule_name": name,
+            "schedule_policy": policy,
+        }
+    )
+    text = getattr(out, "content", None)
+    return text if isinstance(text, str) and text.strip() else f"You were charged {name} on {posted} for CAD {amount:.2f}."
+
+
+def check_dispute_eligibility(fee_event: Dict[str, Any]) -> Dict[str, Any]:
+    code = (fee_event.get("fee_code") or "").upper()
+    amount = float(fee_event.get("amount", 0))
+    first_time = bool(fee_event.get("first_time_90d", False))
+    eligible = False
+    reason = ""
+    if code in {"NSF", "ATM", "MAINTENANCE", "WITHDRAWAL"} and amount <= 20.0 and first_time:
+        eligible = True
+        reason = "First occurrence in 90 days and small amount"
+    return {"eligible": eligible, "reason": reason}
+
+
+def create_dispute_case(fee_event: Dict[str, Any], idempotency_key: str) -> Dict[str, Any]:
+    if idempotency_key in _DISPUTES_DB:
+        return _DISPUTES_DB[idempotency_key]
+    case = {
+        "case_id": str(uuid.uuid4()),
+        "status": "submitted",
+        "fee_id": fee_event.get("id"),
+        "created_at": datetime.utcnow().isoformat() + "Z",
+    }
+    _DISPUTES_DB[idempotency_key] = case
+    return case
+
+
+def authenticate_user(session_id: str, name: Optional[str], dob_yyyy_mm_dd: Optional[str], last4: Optional[str], secret_answer: Optional[str], customer_id: Optional[str] = None) -> Dict[str, Any]:
+    """Mock identity verification.
+
+    Rules (mock):
+    - If dob == 1990-01-01 and last4 == 6001 or secret_answer == "blue", auth succeeds.
+    - Otherwise, remains pending with which fields are still missing.
+    Persists per session_id.
+    """
+    session = _SESSIONS.get(session_id) or {"verified": False, "name": name, "customer_id": customer_id}
+    if isinstance(name, str) and name:
+        session["name"] = name
+    if isinstance(customer_id, str) and customer_id:
+        session["customer_id"] = customer_id
+    if isinstance(dob_yyyy_mm_dd, str) and dob_yyyy_mm_dd:
+        # Normalize DOB to YYYY-MM-DD
+        norm = _normalize_dob(dob_yyyy_mm_dd)
+        session["dob"] = norm or dob_yyyy_mm_dd
+    if isinstance(last4, str) and last4:
+        session["last4"] = last4
+    if isinstance(secret_answer, str) and secret_answer:
+        session["secret"] = secret_answer
+
+    ok = False
+    # If a specific customer is in context, validate against their profile and accounts
+    if isinstance(session.get("customer_id"), str):
+        prof = get_profile(session.get("customer_id"))
+        accts = get_accounts(session.get("customer_id"))
+        dob_ok = _normalize_dob(session.get("dob")) == _normalize_dob(prof.get("dob")) and bool(session.get("dob"))
+        last4s = {str(a.get("account_number"))[-4:] for a in accts if a.get("account_number")}
+        last4_ok = isinstance(session.get("last4"), str) and session.get("last4") in last4s
+        def _norm_secret(x: Optional[str]) -> str:
+            return (x or "").strip().lower()
+        secret_ok = _norm_secret(session.get("secret")) == _norm_secret(prof.get("secret_answer"))
+        if dob_ok and (last4_ok or secret_ok):
+            ok = True
+    else:
+        # Optional demo fallback (disabled by default)
+        allow_fallback = os.getenv("RBC_FEES_ALLOW_GLOBAL_FALLBACK", "0") not in ("", "0", "false", "False")
+        if allow_fallback and session.get("dob") == "1990-01-01" and (session.get("last4") == "6001" or (session.get("secret") or "").strip().lower() == "blue"):
+            ok = True
+    session["verified"] = ok
+    _SESSIONS[session_id] = session
+    need: list[str] = []
+    if not session.get("dob"):
+        need.append("dob")
+    if not session.get("last4") and not session.get("secret"):
+        need.append("last4_or_secret")
+    if not session.get("customer_id"):
+        need.append("customer")
+    resp: Dict[str, Any] = {"session_id": session_id, "verified": ok, "needs": need, "profile": {"name": session.get("name")}}
+    try:
+        if isinstance(session.get("customer_id"), str):
+            prof = get_profile(session.get("customer_id"))
+            if isinstance(prof, dict) and prof.get("secret_question"):
+                resp["question"] = prof.get("secret_question")
+    except Exception:
+        pass
+    return resp
+
+

examples/voice_agent_multi_thread/agents/telco-agent-multi/mock_data/customers.json

@@ -0,0 +1,66 @@
+{
+  "customers": {
+    "+15551234567": {
+      "profile": {
+        "first_name": "Alex",
+        "last_name": "Lee",
+        "full_name": "Alex Lee",
+        "dob": "1988-05-22",
+        "email": "alex.lee@example.com"
+      },
+      "msisdn": "+15551234567",
+      "package_id": "P-40",
+      "contract": {
+        "status": "active",
+        "start_date": "2024-01-10",
+        "end_date": "2026-01-10",
+        "early_termination_fee": 150.0,
+        "auto_renew": true
+      },
+      "usage": {
+        "current_month": { "data_gb_used": 12.5 },
+        "monthly_avg": { "data_gb": 28.0, "minutes": 600, "sms": 200 },
+        "history": [
+          { "month": "2025-07", "data_gb": 31.2, "minutes": 640, "sms": 210 },
+          { "month": "2025-08", "data_gb": 27.5, "minutes": 580, "sms": 190 },
+          { "month": "2025-09", "data_gb": 25.3, "minutes": 590, "sms": 200 }
+        ]
+      },
+      "addons": [
+        { "type": "roaming_pass", "country": "IT", "expires": "2025-09-30", "data_mb": 1024, "price": 10.0 }
+      ],
+      "billing": { "cycle_day": 5, "last_bill_amount": 45.0 }
+    },
+    "+447911123456": {
+      "profile": {
+        "first_name": "Sam",
+        "last_name": "Taylor",
+        "full_name": "Sam Taylor",
+        "dob": "1992-03-14",
+        "email": "sam.taylor@example.co.uk"
+      },
+      "msisdn": "+447911123456",
+      "package_id": "P-10",
+      "contract": {
+        "status": "active",
+        "start_date": "2024-06-01",
+        "end_date": "2025-12-01",
+        "early_termination_fee": 80.0,
+        "auto_renew": false
+      },
+      "usage": {
+        "current_month": { "data_gb_used": 8.1 },
+        "monthly_avg": { "data_gb": 9.0, "minutes": 300, "sms": 90 },
+        "history": [
+          { "month": "2025-07", "data_gb": 10.2, "minutes": 320, "sms": 100 },
+          { "month": "2025-08", "data_gb": 8.5, "minutes": 280, "sms": 85 },
+          { "month": "2025-09", "data_gb": 8.3, "minutes": 305, "sms": 88 }
+        ]
+      },
+      "addons": [],
+      "billing": { "cycle_day": 12, "last_bill_amount": 29.0 }
+    }
+  }
+}
+
+

examples/voice_agent_multi_thread/agents/telco-agent-multi/mock_data/otps.json

@@ -0,0 +1,17 @@
+{
+  "default": "123456",
+  "by_customer": {
+    "cust_test": "123456",
+    "cust_alice": "123456",
+    "cust_bob": "123456",
+    "cust_carla": "123456",
+    "cust_dave": "123456",
+    "cust_eve": "123456"
+  },
+  "by_number": {
+    "+15551234567": "246810",
+    "+447911123456": "135790"
+  }
+}
+
+

examples/voice_agent_multi_thread/agents/telco-agent-multi/mock_data/packages.json

@@ -0,0 +1,72 @@
+{
+  "packages": [
+    {
+      "id": "P-10",
+      "name": "Lite 10GB 4G",
+      "monthly_fee": 25.0,
+      "data_gb": 10,
+      "minutes": 500,
+      "sms": 500,
+      "fiveg": false,
+      "data_rollover": true,
+      "eu_roaming": false,
+      "roam_included_countries": [],
+      "overage": { "per_gb": 8.0, "per_min": 0.05, "per_sms": 0.02 }
+    },
+    {
+      "id": "P-40",
+      "name": "Standard 40GB 5G",
+      "monthly_fee": 40.0,
+      "data_gb": 40,
+      "minutes": 1000,
+      "sms": 1000,
+      "fiveg": true,
+      "data_rollover": false,
+      "eu_roaming": true,
+      "roam_included_countries": ["AT","BE","BG","HR","CY","CZ","DK","EE","FI","FR","DE","GR","HU","IE","IT","LV","LT","LU","MT","NL","PL","PT","RO","SK","SI","ES","SE"],
+      "overage": { "per_gb": 6.0, "per_min": 0.03, "per_sms": 0.02 }
+    },
+    {
+      "id": "P-UNL-B",
+      "name": "Unlimited Basic 5G (100GB high-speed)",
+      "monthly_fee": 55.0,
+      "unlimited": true,
+      "highspeed_cap_gb": 100,
+      "throttle_mbps": 3,
+      "minutes": 2000,
+      "sms": 2000,
+      "fiveg": true,
+      "eu_roaming": true,
+      "roam_included_countries": ["AT","BE","BG","HR","CY","CZ","DK","EE","FI","FR","DE","GR","HU","IE","IT","LV","LT","LU","MT","NL","PL","PT","RO","SK","SI","ES","SE"],
+      "overage": { "per_gb": 0.0, "per_min": 0.0, "per_sms": 0.0 }
+    },
+    {
+      "id": "P-UNL-P",
+      "name": "Unlimited Premium 5G (300GB high-speed)",
+      "monthly_fee": 70.0,
+      "unlimited": true,
+      "highspeed_cap_gb": 300,
+      "throttle_mbps": 10,
+      "minutes": 5000,
+      "sms": 5000,
+      "fiveg": true,
+      "eu_roaming": true,
+      "roam_included_countries": ["AT","BE","BG","HR","CY","CZ","DK","EE","FI","FR","DE","GR","HU","IE","IT","LV","LT","LU","MT","NL","PL","PT","RO","SK","SI","ES","SE"],
+      "overage": { "per_gb": 0.0, "per_min": 0.0, "per_sms": 0.0 }
+    },
+    {
+      "id": "P-TRAVEL-EU-20",
+      "name": "Travelers EU 20GB",
+      "monthly_fee": 45.0,
+      "data_gb": 20,
+      "minutes": 1000,
+      "sms": 1000,
+      "fiveg": true,
+      "data_rollover": false,
+      "eu_roaming": true,
+      "roam_included_countries": ["AT","BE","BG","HR","CY","CZ","DK","EE","FI","FR","DE","GR","HU","IE","IT","LV","LT","LU","MT","NL","PL","PT","RO","SK","SI","ES","SE"],
+      "overage": { "per_gb": 6.0, "per_min": 0.03, "per_sms": 0.02 }
+    }
+  ]
+}
+

examples/voice_agent_multi_thread/agents/telco-agent-multi/mock_data/roaming_rates.json

@@ -0,0 +1,30 @@
+{
+  "countries": {
+    "IT": {
+      "region": "EU",
+      "paygo": { "data_per_mb": 0.02, "call_per_min": 0.05, "sms": 0.02 },
+      "passes": [
+        { "id": "EU-DAY-1GB", "name": "EU Day Pass 1GB", "price": 5.0, "data_mb": 1024, "valid_days": 1 },
+        { "id": "EU-WEEK-5GB", "name": "EU Week Pass 5GB", "price": 15.0, "data_mb": 5120, "valid_days": 7 }
+      ]
+    },
+    "FR": {
+      "region": "EU",
+      "paygo": { "data_per_mb": 0.02, "call_per_min": 0.05, "sms": 0.02 },
+      "passes": [
+        { "id": "EU-DAY-1GB", "name": "EU Day Pass 1GB", "price": 5.0, "data_mb": 1024, "valid_days": 1 },
+        { "id": "EU-WEEK-5GB", "name": "EU Week Pass 5GB", "price": 15.0, "data_mb": 5120, "valid_days": 7 }
+      ]
+    },
+    "US": {
+      "region": "NA",
+      "paygo": { "data_per_mb": 0.15, "call_per_min": 0.20, "sms": 0.10 },
+      "passes": [
+        { "id": "NA-DAY-500MB", "name": "North America Day 500MB", "price": 7.0, "data_mb": 512, "valid_days": 1 },
+        { "id": "NA-WEEK-2GB", "name": "North America Week 2GB", "price": 20.0, "data_mb": 2048, "valid_days": 7 }
+      ]
+    }
+  }
+}
+
+

examples/voice_agent_multi_thread/agents/telco-agent-multi/prompts.py

@@ -0,0 +1,30 @@
+from langchain_core.prompts import ChatPromptTemplate
+
+# Generic short explanation prompt adapted for telco contexts (kept for parity)
+EXPLAIN_FEE_PROMPT = ChatPromptTemplate.from_messages([
+    (
+        "system",
+        """
+You are a warm, helpful phone assistant. Use a friendly, empathetic tone.
+Guidelines:
+- Keep it concise (2-3 sentences), plain language, no jargon.
+- Offer help-oriented phrasing ("we can check options"), no blame.
+- TTS SAFETY: Output must be plain text. Do not use markdown, bullets, asterisks, emojis, or special typography. Use only ASCII punctuation and straight quotes.
+""",
+    ),
+    (
+        "human",
+        """
+Context:
+- code: {fee_code}
+- posted_date: {posted_date}
+- amount: {amount}
+- schedule_name: {schedule_name}
+- schedule_policy: {schedule_policy}
+
+Write a concise explanation (2-3 sentences) suitable for a phone TTS.
+""",
+    ),
+])
+
+

examples/voice_agent_multi_thread/agents/telco-agent-multi/react_agent.py

@@ -0,0 +1,600 @@
+import os
+import json
+import logging
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List
+
+from langgraph.func import entrypoint, task
+from langgraph.graph import add_messages
+from langchain_openai import ChatOpenAI
+from langchain_core.messages import (
+    SystemMessage,
+    HumanMessage,
+    AIMessage,
+    BaseMessage,
+    ToolCall,
+    ToolMessage,
+)
+from langchain_core.prompts import ChatPromptTemplate
+from langgraph.store.base import BaseStore
+from langgraph.config import RunnableConfig
+from langchain_core.runnables.config import ensure_config
+from langgraph.config import get_store
+
+
+# ---- Tools (telco) ----
+
+try:
+    from . import tools as telco_tools  # type: ignore
+except Exception:
+    import importlib.util as _ilu
+    _dir = os.path.dirname(__file__)
+    _tools_path = os.path.join(_dir, "tools.py")
+    _spec = _ilu.spec_from_file_location("telco_agent_tools", _tools_path)
+    telco_tools = _ilu.module_from_spec(_spec)  # type: ignore
+    assert _spec and _spec.loader
+    _spec.loader.exec_module(telco_tools)  # type: ignore
+
+# Aliases for tool functions
+start_login_tool = telco_tools.start_login_tool
+verify_login_tool = telco_tools.verify_login_tool
+get_current_package_tool = telco_tools.get_current_package_tool
+get_data_balance_tool = telco_tools.get_data_balance_tool
+list_available_packages_tool = telco_tools.list_available_packages_tool
+recommend_packages_tool = telco_tools.recommend_packages_tool
+get_roaming_info_tool = telco_tools.get_roaming_info_tool
+close_contract_tool = telco_tools.close_contract_tool
+list_addons_tool = telco_tools.list_addons_tool
+purchase_roaming_pass_tool = telco_tools.purchase_roaming_pass_tool
+change_package_tool = telco_tools.change_package_tool
+get_billing_summary_tool = telco_tools.get_billing_summary_tool
+set_data_alerts_tool = telco_tools.set_data_alerts_tool
+check_status = telco_tools.check_status
+
+# Import helper functions
+try:
+    from ..helper_functions import write_status, reset_status
+except Exception:
+    import importlib.util as _ilu
+    _dir = os.path.dirname(os.path.dirname(__file__))
+    _helper_path = os.path.join(_dir, "helper_functions.py")
+    _spec = _ilu.spec_from_file_location("helper_functions", _helper_path)
+    _helper_module = _ilu.module_from_spec(_spec)  # type: ignore
+    assert _spec and _spec.loader
+    _spec.loader.exec_module(_helper_module)  # type: ignore
+    write_status = _helper_module.write_status
+    reset_status = _helper_module.reset_status
+
+
+"""ReAct agent entrypoint and system prompt for Telco assistant."""
+
+
+SYSTEM_PROMPT = (
+    "You are a warm, helpful mobile operator assistant. Greet briefly, then ask for the caller's mobile number (MSISDN). "
+    "IDENTITY IS MANDATORY: After collecting the number, call start_login_tool to send a one-time code via SMS, then ask for the 6-digit code. "
+    "Call verify_login_tool with the code. Do NOT proceed unless verified=true. If not verified, ask ONLY for the next missing item and retry. "
+    "AFTER VERIFIED: Support these tasks and ask one question per turn: "
+    "(1) Show current package and contract; (2) Check current data balance; (3) Explain roaming in a country and available passes; (4) Recommend packages with costs based on usage/preferences; (5) Close contract (require explicit yes/no confirmation). "
+    "When recommending, include monthly fees and key features, and keep answers concise. When closing contracts, summarize any early termination fee before asking for confirmation. "
+    "STYLE: Concise (1–2 sentences), friendly, and action-oriented. "
+    "TTS SAFETY: Output must be plain text suitable for text-to-speech. Do not use markdown, bullets, asterisks, emojis, or special typography. Use only ASCII punctuation and straight quotes."
+)
+
+SECONDARY_SYSTEM_PROMPT = (
+    "You are a friendly mobile operator assistant engaging in light conversation while a long-running task is being processed. "
+    "You can: (1) Check status of the ongoing task using check_status tool; (2) Answer general questions about packages, data balance, or roaming; (3) Provide light chit-chat. "
+    "DO NOT attempt to perform any long operations like changing packages, closing contracts, or purchasing passes - explain that another operation is in progress. "
+    "STYLE: Brief (1-2 sentences), friendly, and reassuring. "
+    "TTS SAFETY: Output must be plain text suitable for text-to-speech. Do not use markdown, bullets, asterisks, emojis, or special typography. Use only ASCII punctuation and straight quotes."
+)
+
+
+_MODEL_NAME = os.getenv("REACT_MODEL", os.getenv("CLARIFY_MODEL", "gpt-4o"))
+_LLM = ChatOpenAI(model=_MODEL_NAME, temperature=0.3)
+_HELPER_LLM = ChatOpenAI(model=_MODEL_NAME, temperature=0.7)
+
+# Main thread tools (all tools)
+_MAIN_TOOLS = [
+    start_login_tool,
+    verify_login_tool,
+    get_current_package_tool,
+    get_data_balance_tool,
+    list_available_packages_tool,
+    recommend_packages_tool,
+    get_roaming_info_tool,
+    close_contract_tool,
+    list_addons_tool,
+    purchase_roaming_pass_tool,
+    change_package_tool,
+    get_billing_summary_tool,
+    set_data_alerts_tool,
+]
+
+# Secondary thread tools (limited to safe, quick operations)
+_SECONDARY_TOOLS = [
+    check_status,
+    get_current_package_tool,
+    get_data_balance_tool,
+    list_available_packages_tool,
+    get_roaming_info_tool,
+    list_addons_tool,
+]
+
+_LLM_WITH_TOOLS = _LLM.bind_tools(_MAIN_TOOLS)
+_HELPER_LLM_WITH_TOOLS = _HELPER_LLM.bind_tools(_SECONDARY_TOOLS)
+_ALL_TOOLS_BY_NAME = {t.name: t for t in (_MAIN_TOOLS + [check_status])}
+
+# Synthesis chain for merging tool results with interim conversation
+_SYNTHESIS_PROMPT = ChatPromptTemplate.from_messages(
+    [
+        (
+            "system",
+            "You are a helpful mobile operator assistant. A long-running operation you were executing has just finished. Your goal is to synthesize the result with the conversation that happened while the operation was running.",
+        ),
+        ("user", "Here is the result from the operation:\n\n{tool_result}"),
+        (
+            "user",
+            "While the operation was running, we had this conversation:\n\n{interim_conversation}",
+        ),
+        (
+            "user",
+            "Now, please craft a single, natural-sounding response that seamlessly continues the conversation. Start by acknowledging the last message if appropriate, and then present the operation result. The response should feel like a direct and fluid continuation of the chat, smoothly integrating the outcome. Keep it brief (1-2 sentences) and TTS-safe (no markdown or special formatting).",
+        ),
+    ]
+)
+_SYNTHESIS_LLM = ChatOpenAI(model=_MODEL_NAME, temperature=0.7)
+_SYNTHESIS_CHAIN = _SYNTHESIS_PROMPT | _SYNTHESIS_LLM
+
+# Simple per-run context storage (thread-safe enough for local dev worker)
+_CURRENT_THREAD_ID: str | None = None
+_CURRENT_MSISDN: str | None = None
+
+# ---- Logger ----
+logger = logging.getLogger("TelcoAgent")
+if not logger.handlers:
+    _stream = logging.StreamHandler()
+    _stream.setLevel(logging.INFO)
+    _fmt = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    _stream.setFormatter(_fmt)
+    logger.addHandler(_stream)
+    try:
+        _file = logging.FileHandler(str(Path(__file__).resolve().parents[2] / "app.log"))
+        _file.setLevel(logging.INFO)
+        _file.setFormatter(_fmt)
+        logger.addHandler(_file)
+    except Exception:
+        pass
+logger.setLevel(logging.INFO)
+_DEBUG = os.getenv("TELCO_DEBUG", "0") not in ("", "0", "false", "False")
+
+def _get_thread_id(config: Dict[str, Any] | None, messages: List[BaseMessage]) -> str:
+    cfg = config or {}
+    # Try dict-like and attribute-like access
+    def _safe_get(container: Any, key: str, default: Any = None) -> Any:
+        try:
+            if isinstance(container, dict):
+                return container.get(key, default)
+            if hasattr(container, "get"):
+                return container.get(key, default)
+            if hasattr(container, key):
+                return getattr(container, key, default)
+        except Exception:
+            return default
+        return default
+
+    try:
+        conf = _safe_get(cfg, "configurable", {}) or {}
+        for key in ("thread_id", "session_id", "thread"):
+            val = _safe_get(conf, key)
+            if isinstance(val, str) and val:
+                return val
+    except Exception:
+        pass
+
+    # Fallback: look for session_id on the latest human message additional_kwargs
+    try:
+        for m in reversed(messages or []):
+            addl = getattr(m, "additional_kwargs", None)
+            if isinstance(addl, dict) and isinstance(addl.get("session_id"), str) and addl.get("session_id"):
+                return addl.get("session_id")
+            if isinstance(m, dict):
+                ak = m.get("additional_kwargs") or {}
+                if isinstance(ak, dict) and isinstance(ak.get("session_id"), str) and ak.get("session_id"):
+                    return ak.get("session_id")
+    except Exception:
+        pass
+    return "unknown"
+
+
+def _trim_messages(messages: List[BaseMessage], max_messages: int = 40) -> List[BaseMessage]:
+    if len(messages) <= max_messages:
+        return messages
+    return messages[-max_messages:]
+
+
+def _sanitize_conversation(messages: List[BaseMessage]) -> List[BaseMessage]:
+    """Ensure tool messages only follow an assistant message with tool_calls.
+
+    Drops orphan tool messages that could cause OpenAI 400 errors.
+    """
+    sanitized: List[BaseMessage] = []
+    pending_tool_ids: set[str] | None = None
+    for m in messages:
+        try:
+            if isinstance(m, AIMessage):
+                sanitized.append(m)
+                tool_calls = getattr(m, "tool_calls", None) or []
+                ids: set[str] = set()
+                for tc in tool_calls:
+                    # ToolCall can be mapping-like or object-like
+                    if isinstance(tc, dict):
+                        _id = tc.get("id") or tc.get("tool_call_id")
+                    else:
+                        _id = getattr(tc, "id", None) or getattr(tc, "tool_call_id", None)
+                    if isinstance(_id, str):
+                        ids.add(_id)
+                pending_tool_ids = ids if ids else None
+                continue
+            if isinstance(m, ToolMessage):
+                if pending_tool_ids and isinstance(getattr(m, "tool_call_id", None), str) and m.tool_call_id in pending_tool_ids:
+                    sanitized.append(m)
+                    # keep accepting subsequent tool messages for the same assistant turn
+                    continue
+                # Orphan tool message: drop
+                continue
+            # Any other message resets expectation
+            sanitized.append(m)
+            pending_tool_ids = None
+        except Exception:
+            # On any unexpected shape, include as-is but reset to avoid pairing issues
+            sanitized.append(m)
+            pending_tool_ids = None
+    # Ensure the conversation doesn't start with a ToolMessage
+    while sanitized and isinstance(sanitized[0], ToolMessage):
+        sanitized.pop(0)
+    return sanitized
+
+
+def _today_string() -> str:
+    override = os.getenv("RBC_FEES_TODAY_OVERRIDE")
+    if isinstance(override, str) and override.strip():
+        try:
+            datetime.strptime(override.strip(), "%Y-%m-%d")
+            return override.strip()
+        except Exception:
+            pass
+    return datetime.utcnow().strftime("%Y-%m-%d")
+
+
+def _system_messages() -> List[BaseMessage]:
+    today = _today_string()
+    return [SystemMessage(content=SYSTEM_PROMPT)]
+
+
+@task()
+def call_llm(messages: List[BaseMessage]) -> AIMessage:
+    """LLM decides whether to call a tool or not."""
+    if _DEBUG:
+        try:
+            preview = [f"{getattr(m,'type', getattr(m,'role',''))}:{str(getattr(m,'content', m))[:80]}" for m in messages[-6:]]
+            logger.info("call_llm: messages_count=%s preview=%s", len(messages), preview)
+        except Exception:
+            logger.info("call_llm: messages_count=%s", len(messages))
+    resp = _LLM_WITH_TOOLS.invoke(_system_messages() + messages)
+    try:
+        # Log assistant content or tool calls for visibility
+        tool_calls = getattr(resp, "tool_calls", None) or []
+        if tool_calls:
+            names = []
+            for tc in tool_calls:
+                n = tc.get("name") if isinstance(tc, dict) else getattr(tc, "name", None)
+                if isinstance(n, str):
+                    names.append(n)
+            logger.info("LLM tool_calls: %s", names)
+        else:
+            txt = getattr(resp, "content", "") or ""
+            if isinstance(txt, str) and txt.strip():
+                logger.info("LLM content: %s", (txt if len(txt) <= 500 else (txt[:500] + "…")))
+    except Exception:
+        pass
+    return resp
+
+
+@task()
+def call_tool(tool_call: ToolCall) -> ToolMessage:
+    """Execute a tool call and wrap result in a ToolMessage."""
+    global _CURRENT_MSISDN
+    tool = _ALL_TOOLS_BY_NAME[tool_call["name"]]
+    args = tool_call.get("args") or {}
+    # Auto-inject session context and remembered msisdn
+    if tool.name in ("start_login_tool", "verify_login_tool"):
+        if "session_id" not in args and _CURRENT_THREAD_ID:
+            args["session_id"] = _CURRENT_THREAD_ID
+    if "msisdn" not in args and _CURRENT_MSISDN:
+        args["msisdn"] = _CURRENT_MSISDN
+    # If the LLM passes msisdn, remember it for subsequent calls
+    try:
+        if isinstance(args.get("msisdn"), str) and args.get("msisdn").strip():
+            _CURRENT_MSISDN = args.get("msisdn")
+    except Exception:
+        pass
+    if _DEBUG:
+        try:
+            logger.info("call_tool: name=%s args_keys=%s", tool.name, list(args.keys()))
+        except Exception:
+            logger.info("call_tool: name=%s", tool.name)
+    result = tool.invoke(args)
+    # Ensure string content
+    content = result if isinstance(result, str) else json.dumps(result)
+    try:
+        # Log tool result previews and OTP debug_code when present
+        if tool.name == "verify_login_tool":
+            try:
+                data = json.loads(content)
+                logger.info("verify_login: verified=%s", data.get("verified"))
+            except Exception:
+                logger.info("verify_login result: %s", content[:300])
+        elif tool.name == "start_login_tool":
+            try:
+                data = json.loads(content)
+                logger.info("start_login_tool: sent=%s", data.get("sent"))
+            except Exception:
+                logger.info("start_login_tool: %s", content[:300])
+        else:
+            # Generic preview
+            logger.info("tool %s result: %s", tool.name, (content[:300] if isinstance(content, str) else str(content)[:300]))
+    except Exception:
+        pass
+    # Never expose OTP debug_code to the LLM
+    try:
+        if tool.name == "start_login_tool":
+            data = json.loads(content)
+            if isinstance(data, dict) and "debug_code" in data:
+                data.pop("debug_code", None)
+                content = json.dumps(data)
+    except Exception:
+        pass
+    return ToolMessage(content=content, tool_call_id=tool_call["id"], name=tool.name)
+
+
+@entrypoint()
+def agent(input_dict: dict, previous: Any = None, config: RunnableConfig | None = None, store: BaseStore | None = None):
+    """Multi-threaded telco agent supporting concurrent conversations during long operations.
+    
+    Args:
+        input_dict: Must contain:
+            - messages: List of new messages
+            - thread_type: "main" or "secondary"
+            - interim_messages_reset: bool (reset interim conversation)
+        previous: Previous state dict with {messages, interim_messages}
+        config: Runtime configuration
+        store: LangGraph store for coordination
+    """
+    # Extract input parameters - handle both dict and list formats
+    if isinstance(input_dict, dict):
+        messages = input_dict.get("messages", [])
+        thread_type = input_dict.get("thread_type", "main")
+        interim_messages_reset = input_dict.get("interim_messages_reset", True)
+    else:
+        # input_dict is actually a list of messages (legacy format)
+        messages = input_dict if isinstance(input_dict, list) else []
+        thread_type = "main"
+        interim_messages_reset = True
+    
+    # Get store (from parameter or global context)
+    if store is None:
+        store = get_store()
+    
+    # Get namespace for coordination
+    cfg = ensure_config() if config is None else config
+    conf = cfg.get("configurable", {}) if isinstance(cfg, dict) else {}
+    namespace = conf.get("namespace_for_memory")
+    if namespace and not isinstance(namespace, tuple):
+        try:
+            namespace = tuple(namespace)
+        except (TypeError, ValueError):
+            namespace = (str(namespace),)
+    
+    # Merge with previous state
+    interim_messages = []
+    if previous:
+        if isinstance(previous, dict):
+            previous_messages = previous.get("messages", [])
+            previous_interim_messages = previous.get("interim_messages", [])
+        else:
+            # Fallback: previous might be a list of messages (old format)
+            previous_messages = list(previous) if isinstance(previous, list) else []
+            previous_interim_messages = []
+        
+        messages = add_messages(previous_messages, messages)
+        interim_messages = add_messages(messages, previous_interim_messages)
+    
+    # Trim and sanitize
+    messages = _trim_messages(messages, max_messages=int(os.getenv("RBC_FEES_MAX_MSGS", "40")))
+    messages = _sanitize_conversation(messages)
+    
+    # Get thread ID and session context
+    thread_id = _get_thread_id(cfg, messages)
+    default_msisdn = conf.get("msisdn") or conf.get("phone_number")
+    
+    # Update module context
+    global _CURRENT_THREAD_ID, _CURRENT_MSISDN
+    _CURRENT_THREAD_ID = thread_id
+    _CURRENT_MSISDN = default_msisdn
+    
+    logger.info("agent start: thread_id=%s thread_type=%s total_in=%s", thread_id, thread_type, len(messages))
+    
+    # Secondary thread: Set processing lock at start
+    if thread_type != "main" and namespace:
+        store.put(namespace, "secondary_status", {
+            "processing": True,
+            "started_at": time.time()
+        })
+        
+        # Check abort flag before starting
+        abort_signal = store.get(namespace, "secondary_abort")
+        if abort_signal and abort_signal.value.get("abort"):
+            # Clean up and exit silently
+            store.put(namespace, "secondary_status", {"processing": False, "aborted": True})
+            store.delete(namespace, "secondary_abort")
+            prev_state = previous if isinstance(previous, dict) else {"messages": [], "interim_messages": []}
+            return entrypoint.final(value=[], save=prev_state)
+    
+    # Choose LLM and system prompt based on thread type
+    if thread_type == "main":
+        active_llm_with_tools = _LLM_WITH_TOOLS
+        system_prompt = SYSTEM_PROMPT
+    else:
+        active_llm_with_tools = _HELPER_LLM_WITH_TOOLS
+        system_prompt = SECONDARY_SYSTEM_PROMPT
+    
+    # Build system messages
+    sys_messages = [SystemMessage(content=system_prompt)]
+    
+    # First LLM call
+    llm_response = active_llm_with_tools.invoke(sys_messages + messages)
+    
+    # Tool execution loop
+    while True:
+        tool_calls = getattr(llm_response, "tool_calls", None) or []
+        if not tool_calls:
+            break
+        
+        # Execute tools in parallel
+        futures = [call_tool(tc) for tc in tool_calls]
+        tool_results = [f.result() for f in futures]
+        
+        if _DEBUG:
+            try:
+                logger.info("tool_results: count=%s names=%s", len(tool_results), [tr.name for tr in tool_results])
+            except Exception:
+                pass
+        
+        messages = add_messages(messages, [llm_response, *tool_results])
+        llm_response = active_llm_with_tools.invoke(sys_messages + messages)
+    
+    # Append final assistant turn
+    messages = add_messages(messages, [llm_response])
+    
+    # Update interim messages
+    if interim_messages_reset:
+        interim_messages = add_messages([], [llm_response])
+    else:
+        interim_messages = add_messages(interim_messages, [llm_response])
+    
+    # Main thread: Reset status after completion and signal completion
+    if thread_type == "main" and namespace:
+        reset_status(store, namespace)
+        # Signal that main operation is complete
+        store.put(namespace, "main_operation_complete", {
+            "completed": True,
+            "timestamp": time.time()
+        })
+    
+    # Secondary thread: Handle abort and release lock
+    if thread_type != "main" and namespace:
+        # Check abort flag before writing results
+        abort_signal = store.get(namespace, "secondary_abort")
+        if abort_signal and abort_signal.value.get("abort"):
+            # Clean up and exit without saving
+            store.put(namespace, "secondary_status", {"processing": False, "aborted": True})
+            store.delete(namespace, "secondary_abort")
+            prev_state = previous if isinstance(previous, dict) else {"messages": [], "interim_messages": []}
+            return entrypoint.final(value=[], save=prev_state)
+        
+        # Safe to proceed - write results and release lock
+        store.put(namespace, "secondary_interim_messages", {"messages": interim_messages})
+        store.put(namespace, "secondary_status", {
+            "processing": False,
+            "completed_at": time.time()
+        })
+    
+    # Main thread: Wait for secondary and synthesize if needed
+    if thread_type == "main" and namespace:
+        # Wait for secondary thread to finish processing (with timeout)
+        MAX_WAIT_SECONDS = 15
+        CHECK_INTERVAL = 0.5
+        elapsed = 0
+        
+        while elapsed < MAX_WAIT_SECONDS:
+            secondary_status = store.get(namespace, "secondary_status")
+            if not secondary_status or not secondary_status.value.get("processing", False):
+                break
+            time.sleep(CHECK_INTERVAL)
+            elapsed += CHECK_INTERVAL
+        
+        # If timed out, set abort flag
+        if elapsed >= MAX_WAIT_SECONDS:
+            store.put(namespace, "secondary_abort", {
+                "abort": True,
+                "reason": "main_thread_timeout",
+                "timestamp": time.time()
+            })
+            time.sleep(0.2)  # Brief moment for secondary to see abort
+        
+        # Read and synthesize interim messages (only if meaningful)
+        interim_messages_from_store = store.get(namespace, "secondary_interim_messages")
+        if interim_messages_from_store:
+            interim_conv = interim_messages_from_store.value.get("messages")
+            if interim_conv and len(interim_conv) > 0:
+                # Filter out status-only messages for synthesis
+                meaningful_messages = []
+                for m in interim_conv:
+                    content = getattr(m, 'content', '').lower()
+                    # Skip if it's just about status/progress
+                    if not any(word in content for word in ['processing', 'complete', 'running', 'percent', 'status']):
+                        meaningful_messages.append(m)
+                
+                # Only synthesize if there were non-status conversations
+                if meaningful_messages:
+                    tool_result_content = messages[-1].content if messages else ""
+                    interim_conv_str = "\n".join(
+                        [f"{getattr(m, 'type', 'message')}: {getattr(m, 'content', '')}" for m in meaningful_messages]
+                    )
+                    try:
+                        final_answer = _SYNTHESIS_CHAIN.invoke({
+                            "tool_result": tool_result_content,
+                            "interim_conversation": interim_conv_str,
+                        })
+                        # Add visual marker for synthesis
+                        synthesized_content = f"{final_answer.content}"
+                        messages[-1] = AIMessage(content=synthesized_content)
+                        logger.info("Synthesized response with %d meaningful interim messages", len(meaningful_messages))
+                    except Exception as e:
+                        logger.warning("Synthesis failed: %s", e)
+                else:
+                    logger.info("No meaningful interim messages to synthesize (only status checks)")
+                
+                store.delete(namespace, "secondary_interim_messages")
+        
+        # Clean up coordination state
+        reset_status(store, namespace)
+        store.delete(namespace, "secondary_status")
+        store.delete(namespace, "secondary_abort")
+        # Keep completion flag briefly for client to see
+        store.put(namespace, "main_operation_complete", {
+            "completed": True,
+            "timestamp": time.time(),
+            "ready_for_new_operation": True
+        })
+    
+    # Prepare final state
+    current_state = {
+        "messages": messages,
+        "interim_messages": interim_messages,
+    }
+    
+    final_text = getattr(messages[-1], "content", "") if messages else ""
+    try:
+        if isinstance(final_text, str) and final_text.strip():
+            logger.info("final content: %s", (final_text if len(final_text) <= 500 else (final_text[:500] + "…")))
+    except Exception:
+        pass
+    
+    logger.info("agent done: thread_id=%s thread_type=%s total_messages=%s", thread_id, thread_type, len(messages))
+    
+    return entrypoint.final(value=messages, save=current_state)
+
+

examples/voice_agent_multi_thread/agents/telco-agent-multi/tools.py

@@ -0,0 +1,192 @@
+import os
+import json
+import time
+from typing import Dict, Any
+
+from langchain_core.tools import tool
+from langchain_core.runnables.config import ensure_config
+from langgraph.config import get_store, get_stream_writer
+
+# Robust logic import that avoids cross-module leakage during hot reloads
+try:
+    from . import logic as telco_logic  # type: ignore
+except Exception:
+    import importlib.util as _ilu
+    _dir = os.path.dirname(__file__)
+    _logic_path = os.path.join(_dir, "logic.py")
+    _spec = _ilu.spec_from_file_location("telco_agent_logic", _logic_path)
+    telco_logic = _ilu.module_from_spec(_spec)  # type: ignore
+    assert _spec and _spec.loader
+    _spec.loader.exec_module(telco_logic)  # type: ignore
+
+# Import helper functions (following the working example pattern)
+try:
+    from ..helper_functions import write_status
+except Exception:
+    # Fallback inline definition if import fails
+    def write_status(tool_name: str, progress: int, status: str, store, namespace, config):
+        if not isinstance(namespace, tuple):
+            try:
+                namespace = tuple(namespace)
+            except (TypeError, ValueError):
+                namespace = (str(namespace),)
+        store.put(namespace, "working-tool-status-update", {
+            "tool_name": tool_name,
+            "progress": progress,
+            "status": status,
+        })
+
+
+# --- Identity tools ---
+
+@tool
+def start_login_tool(session_id: str, msisdn: str) -> str:
+    """Send a one-time code via SMS to the given mobile number. Returns masked destination and status (JSON)."""
+    return json.dumps(telco_logic.start_login(session_id, msisdn))
+
+
+@tool
+def verify_login_tool(session_id: str, msisdn: str, otp: str) -> str:
+    """Verify the one-time code sent to the user's phone. Returns {verified, session_id, msisdn}."""
+    return json.dumps(telco_logic.verify_login(session_id, msisdn, otp))
+
+
+# --- Customer/package tools ---
+
+@tool
+def get_current_package_tool(msisdn: str) -> str:
+    """Get the customer's current package, contract status, and addons (JSON)."""
+    return json.dumps(telco_logic.get_current_package(msisdn))
+
+
+@tool
+def get_data_balance_tool(msisdn: str) -> str:
+    """Get the customer's current month data usage and remaining allowance (JSON)."""
+    return json.dumps(telco_logic.get_data_balance(msisdn))
+
+
+@tool
+def list_available_packages_tool() -> str:
+    """List all available mobile packages with fees and features (JSON array)."""
+    return json.dumps(telco_logic.list_available_packages())
+
+
+@tool
+def recommend_packages_tool(msisdn: str, preferences_json: str | None = None) -> str:
+    """Recommend up to 3 packages based on the customer's usage and optional preferences JSON."""
+    prefs: Dict[str, Any] = {}
+    try:
+        if isinstance(preferences_json, str) and preferences_json.strip():
+            prefs = json.loads(preferences_json)
+    except Exception:
+        prefs = {}
+    return json.dumps(telco_logic.recommend_packages(msisdn, prefs))
+
+
+@tool
+def get_roaming_info_tool(msisdn: str, country_code: str) -> str:
+    """Get roaming pricing and available passes for a country; indicates if included by current package (JSON)."""
+    return json.dumps(telco_logic.get_roaming_info(msisdn, country_code))
+
+
+@tool
+def close_contract_tool(msisdn: str, confirm: bool = False) -> str:
+    """Close the customer's contract. Use confirm=true only after explicit user confirmation. Returns summary (JSON)."""
+    if not confirm:
+        # Just return preview, no long operation
+        return json.dumps(telco_logic.close_contract(msisdn, False))
+    
+    # Long-running operation with progress reporting (following working example pattern)
+    writer = get_stream_writer()
+    writer("Processing your contract closure request. This may take a moment...")
+    
+    tool_name = "close_contract_tool"
+    steps = 10
+    interval_seconds = 5  # 10 steps × 5 seconds = 50 seconds total
+    
+    config = ensure_config()
+    namespace = config["configurable"]["namespace_for_memory"]
+    server_store = get_store()
+    
+    for i in range(1, steps + 1):
+        time.sleep(interval_seconds)
+        pct = (i * 100) // steps
+        status = "running"
+        write_status(tool_name, pct, status, server_store, namespace, config)
+    
+    # Execute actual closure
+    result = telco_logic.close_contract(msisdn, True)
+    
+    write_status(tool_name, 100, "completed", server_store, namespace, config)
+    return json.dumps(result)
+
+
+# --- Extended tools ---
+
+@tool
+def list_addons_tool(msisdn: str) -> str:
+    """List customer's active addons (e.g., roaming passes)."""
+    return json.dumps(telco_logic.list_addons(msisdn))
+
+
+@tool
+def purchase_roaming_pass_tool(msisdn: str, country_code: str, pass_id: str) -> str:
+    """Purchase a roaming pass for a country by pass_id. Returns the added addon (JSON)."""
+    result = telco_logic.purchase_roaming_pass(msisdn, country_code, pass_id)
+    return json.dumps(result)
+
+
+@tool
+def change_package_tool(msisdn: str, package_id: str, effective: str = "next_cycle") -> str:
+    """Change customer's package now or next_cycle. Returns status summary (JSON)."""
+    result = telco_logic.change_package(msisdn, package_id, effective)
+    return json.dumps(result)
+
+
+@tool
+def get_billing_summary_tool(msisdn: str) -> str:
+    """Get billing summary including monthly fee and last bill amount (JSON)."""
+    result = telco_logic.get_billing_summary(msisdn)
+    return json.dumps(result)
+
+
+@tool
+def set_data_alerts_tool(msisdn: str, threshold_percent: int | None = None, threshold_gb: float | None = None) -> str:
+    """Set data usage alerts by percent and/or GB. Returns updated alert settings (JSON)."""
+    return json.dumps(telco_logic.set_data_alerts(msisdn, threshold_percent, threshold_gb))
+
+
+# --- Helper tool for secondary thread ---
+
+@tool
+def check_status() -> dict:
+    """Check the current status and progress of any long-running task."""
+    config = ensure_config()
+    namespace = config["configurable"]["namespace_for_memory"]
+    
+    if not isinstance(namespace, tuple):
+        try:
+            namespace = tuple(namespace)
+        except (TypeError, ValueError):
+            namespace = (str(namespace),)
+    
+    server_store = get_store()
+    memory_update = server_store.get(namespace, "working-tool-status-update")
+    
+    if memory_update:
+        item_value = memory_update.value
+        status = item_value.get("status", "unknown")
+        progress = item_value.get("progress", None)
+        tool_name = item_value.get("tool_name", "unknown")
+        return {
+            "status": status,
+            "progress": progress,
+            "tool_name": tool_name
+        }
+    else:
+        return {
+            "status": "idle",
+            "progress": None,
+            "tool_name": None
+        }
+

examples/voice_agent_multi_thread/agents/telco_client.py

@@ -0,0 +1,570 @@
+#!/usr/bin/env python3
+"""
+Client for multi-threaded telco agent.
+
+This client handles routing between main and secondary threads:
+- Main thread: Handles long-running operations (package changes, contract closures, etc.)
+- Secondary thread: Handles interim queries while main thread is busy
+
+Usage:
+    # Interactive mode
+    python telco_client.py --interactive
+    
+    # Single message
+    python telco_client.py
+    
+    # Custom server URL
+    python telco_client.py --url http://localhost:2024 --interactive
+"""
+
+import argparse
+import asyncio
+import sys
+import time
+import uuid
+from pathlib import Path
+import contextlib
+
+from langgraph_sdk import get_client
+from langgraph_sdk.schema import StreamPart
+import httpx
+from typing import Any, Optional
+
+
+# Terminal colors
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+FG_BLUE = "\033[34m"
+FG_GREEN = "\033[32m"
+FG_CYAN = "\033[36m"
+FG_YELLOW = "\033[33m"
+FG_MAGENTA = "\033[35m"
+FG_GRAY = "\033[90m"
+PROMPT_STR = f"{BOLD}> {RESET}"
+
+
+def _show_prompt() -> None:
+    sys.stdout.write(PROMPT_STR)
+    sys.stdout.flush()
+
+
+def _write_line(s: str) -> None:
+    sys.stdout.write("\r\x1b[2K" + s + "\n")
+    sys.stdout.flush()
+    _show_prompt()
+
+
+def _write_line_no_prompt(s: str) -> None:
+    sys.stdout.write("\r\x1b[2K" + s + "\n")
+    sys.stdout.flush()
+
+
+def _log(msg: str) -> None:
+    _write_line(f"{FG_GRAY}{msg}{RESET}")
+
+
+def _user(msg: str) -> None:
+    _write_line_no_prompt(f"{FG_BLUE}User{RESET}: {msg}")
+
+
+def _assistant(msg: str) -> None:
+    _write_line(f"{FG_GREEN}Assistant{RESET}: {msg}")
+
+
+def _event(label: str, text: str) -> None:
+    _write_line(f"{FG_YELLOW}[{label}]{RESET} {DIM}{text}{RESET}")
+
+
+def _extract_text_from_messages(messages: list[Any]) -> Optional[str]:
+    """Extract text from a list of message objects."""
+    if not isinstance(messages, list) or not messages:
+        return None
+    last = messages[-1]
+    if isinstance(last, dict):
+        content = last.get("content")
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            pieces: list[str] = []
+            for seg in content:
+                if isinstance(seg, dict):
+                    t = seg.get("text") or seg.get("content") or ""
+                    if isinstance(t, str) and t:
+                        pieces.append(t)
+            if pieces:
+                return "\n".join(pieces)
+    return None
+
+
+def _extract_text(payload: Any, *, graph_key: str | None = None) -> Optional[str]:
+    """Extract assistant text from various payload shapes."""
+    # Direct string
+    if isinstance(payload, str):
+        return payload
+    # List of messages or mixed
+    if isinstance(payload, list):
+        text = _extract_text_from_messages(payload)
+        if text:
+            return text
+        # Fallback: any string entries
+        for v in payload:
+            t = _extract_text(v, graph_key=graph_key)
+            if t:
+                return t
+        return None
+    # Dict payloads
+    if isinstance(payload, dict):
+        # Graph-level direct string
+        if graph_key and isinstance(payload.get(graph_key), str):
+            return payload[graph_key]
+        # Common shapes
+        if isinstance(payload.get("value"), (str, list, dict)):
+            t = _extract_text(payload.get("value"), graph_key=graph_key)
+            if t:
+                return t
+        if isinstance(payload.get("messages"), list):
+            t = _extract_text_from_messages(payload.get("messages", []))
+            if t:
+                return t
+        if isinstance(payload.get("content"), str):
+            return payload.get("content")
+        # Search nested values
+        for v in payload.values():
+            t = _extract_text(v, graph_key=graph_key)
+            if t:
+                return t
+    return None
+
+
+async def stream_run(
+    client,
+    thread_id: str,
+    graph: str,
+    message: dict,
+    label: str,
+    *,
+    namespace_for_memory: tuple[str, ...],
+    global_last_text: dict[str, str],  # Shared across runs for deduplication
+) -> int:
+    """Stream a run and print output."""
+    printed_once = False
+    command: dict[str, Any] | None = None
+
+    config = {
+        "configurable": {
+            "thread_id": thread_id,
+            "namespace_for_memory": list(namespace_for_memory),
+        }
+    }
+
+    while True:
+        last_text: Optional[str] = global_last_text.get("last", None)  # Global de-dupe
+        stream = client.runs.stream(
+            thread_id=thread_id,
+            assistant_id=graph,
+            input=message if command is None else None,
+            command=command,
+            stream_mode=["values", "custom"],
+            config=config,
+        )
+
+        saw_interrupt = False
+        async for part in stream:
+            assert isinstance(part, StreamPart)
+            if part.event == "metadata":
+                data = part.data or {}
+                run_id = (data.get("run_id") if isinstance(data, dict) else None) or "?"
+                _event(label, f"run started (run_id={run_id}, thread_id={thread_id})")
+                continue
+            if part.event == "custom":
+                data = part.data
+                text = _extract_text(data, graph_key=graph)
+                if text and text != last_text:
+                    _assistant(text)
+                    last_text = text
+                    global_last_text["last"] = text
+                continue
+            if part.event == "values":
+                data = part.data
+                text = _extract_text(data, graph_key=graph)
+                if text and text != last_text:
+                    _assistant(text)
+                    last_text = text
+                    global_last_text["last"] = text
+                continue
+            # Uncomment for debug info
+            # if part.event:
+            #     _event(label, f"{part.event} {part.data}")
+            if part.event == "end":
+                return 0
+
+        if saw_interrupt:
+            command = {"resume": None}
+            continue
+        return 0
+
+
+async def ainput(prompt: str = "") -> str:
+    """Async input wrapper."""
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, lambda: input(prompt))
+
+
+async def read_latest_status(client, namespace_for_memory: tuple[str, ...]) -> dict:
+    """Read the latest tool status from the store."""
+    ns_list = list(namespace_for_memory)
+    try:
+        items = await client.store.search_items(ns_list)
+    except Exception:
+        return {}
+    
+    # Normalize return shape: SDK may return a dict with 'items' or a bare list
+    items_list: list[Any] | None = None
+    if isinstance(items, dict):
+        inner = items.get("items")
+        if isinstance(inner, list):
+            items_list = inner
+    elif isinstance(items, list):
+        items_list = items
+    
+    if not items_list:
+        return {}
+    
+    # Walk from the end to find the most recent item that has a 'status'
+    for item in reversed(items_list):
+        value = getattr(item, "value", None)
+        if value is None and isinstance(item, dict):
+            value = item.get("value")
+        if isinstance(value, dict) and "status" in value:
+            return value
+    
+    # Fallback to last value if present
+    last = items_list[-1]
+    value = getattr(last, "value", None)
+    if value is None and isinstance(last, dict):
+        value = last.get("value")
+    return value if isinstance(value, dict) else {}
+
+
+async def check_completion_flag(client, namespace_for_memory: tuple[str, ...]) -> bool:
+    """Check if main operation has completed recently."""
+    ns_list = list(namespace_for_memory)
+    try:
+        items = await client.store.search_items(ns_list)
+    except Exception:
+        return False
+    
+    # Normalize return shape
+    items_list: list[Any] | None = None
+    if isinstance(items, dict):
+        inner = items.get("items")
+        if isinstance(inner, list):
+            items_list = inner
+    elif isinstance(items, list):
+        items_list = items
+    
+    if not items_list:
+        return False
+    
+    # Look for completion flag
+    for item in reversed(items_list):
+        key = getattr(item, "key", None) or (item.get("key") if isinstance(item, dict) else None)
+        if key == "main_operation_complete":
+            value = getattr(item, "value", None)
+            if value is None and isinstance(item, dict):
+                value = item.get("value")
+            if isinstance(value, dict) and value.get("ready_for_new_operation"):
+                return True
+    
+    return False
+
+
+async def run_client(
+    base_url: str,
+    graph: str,
+    user_id: str,
+    interactive: bool,
+    thread_file: str | None,
+    initial_message: str | None,
+) -> int:
+    """Main client logic."""
+    client = get_client(url=base_url)
+
+    # Primary and secondary thread ids
+    thread_path = Path(thread_file) if thread_file else None
+    
+    # Main thread: load from file if present; otherwise create on server and persist
+    if thread_path and thread_path.exists():
+        try:
+            loaded = thread_path.read_text().strip().splitlines()
+            thread_id_main = loaded[0] if loaded else None
+        except Exception:
+            thread_id_main = None
+        
+        if not thread_id_main:
+            t = await client.threads.create()
+            thread_id_main = getattr(t, "thread_id", None) or (
+                t["thread_id"] if isinstance(t, dict) else str(uuid.uuid4())
+            )
+            try:
+                thread_path.write_text(thread_id_main + "\n")
+            except Exception:
+                pass
+        else:
+            try:
+                await client.threads.create(thread_id=thread_id_main, if_exists="do_nothing")
+            except httpx.HTTPStatusError as e:
+                if getattr(e, "response", None) is not None and e.response.status_code == 409:
+                    pass
+                else:
+                    raise
+    else:
+        t = await client.threads.create()
+        thread_id_main = getattr(t, "thread_id", None) or (
+            t["thread_id"] if isinstance(t, dict) else str(uuid.uuid4())
+        )
+        if thread_path:
+            try:
+                thread_path.write_text(thread_id_main + "\n")
+            except Exception:
+                pass
+
+    # Secondary thread: always create on server (ephemeral)
+    t2 = await client.threads.create()
+    thread_id_updates = getattr(t2, "thread_id", None) or (
+        t2["thread_id"] if isinstance(t2, dict) else str(uuid.uuid4())
+    )
+
+    # Shared namespace used by server agent's tools
+    namespace_for_memory = (user_id, "tools_updates")
+
+    print(f"{FG_MAGENTA}Telco Agent Multi-Threaded Client{RESET}")
+    print(f"Main Thread ID: {FG_CYAN}{thread_id_main}{RESET}")
+    print(f"Secondary Thread ID: {FG_CYAN}{thread_id_updates}{RESET}")
+    print(f"Namespace: {FG_CYAN}{namespace_for_memory}{RESET}")
+    print()
+
+    # Interactive loop
+    if interactive:
+        print(f"{FG_CYAN}Interactive Mode: Type your message. Use /exit to quit.{RESET}")
+        print(f"{FG_GRAY}Long operations will run in background. You can ask questions while they run.{RESET}")
+        print()
+        
+        # Clear any stale flags from previous sessions
+        try:
+            ns_list = list(namespace_for_memory)
+            await client.store.delete_item(ns_list, "main_operation_complete")
+            await client.store.delete_item(ns_list, "working-tool-status-update")
+            await client.store.delete_item(ns_list, "secondary_status")
+            await client.store.delete_item(ns_list, "secondary_abort")
+            await client.store.delete_item(ns_list, "secondary_interim_messages")
+        except Exception:
+            pass  # Flags might not exist, that's okay
+        
+        _show_prompt()
+        
+        # Track background task and state
+        main_job: asyncio.Task[int] | None = None
+        interim_messages_reset = True
+        global_last_text: dict[str, str] = {}  # Global deduplication
+        cooldown_until: float = 0  # Cooldown timestamp
+        last_operation_complete_time: float = 0
+
+        while True:
+            try:
+                user_text = await ainput("")
+            except (KeyboardInterrupt, EOFError):
+                user_text = "/exit"
+            
+            user_text = (user_text or "").strip()
+            if not user_text:
+                continue
+            
+            if user_text.lower() in {"exit", "quit", "/exit"}:
+                break
+            
+            _user(user_text)
+
+            # Check if we're in cooldown period
+            current_time = time.time()
+            if current_time < cooldown_until:
+                wait_time = int(cooldown_until - current_time)
+                _event("cooldown", f"Operation just completed, waiting {wait_time}s before starting new operation...")
+                await asyncio.sleep(cooldown_until - current_time)
+                cooldown_until = 0
+                # Clear completion flag after cooldown
+                try:
+                    ns_list = list(namespace_for_memory)
+                    # Try to delete completion flag (may not exist)
+                    try:
+                        await client.store.delete_item(ns_list, "main_operation_complete")
+                    except Exception:
+                        pass
+                except Exception:
+                    pass
+
+            # Determine current status based ONLY on server-side store
+            # Don't use main_job.done() because the client task finishes quickly
+            # even though the server operation continues
+            long_info = await read_latest_status(client, namespace_for_memory)
+            long_running = bool(long_info.get("status") == "running")
+            just_completed = await check_completion_flag(client, namespace_for_memory)
+            
+            # If operation just completed, set cooldown but don't skip the message
+            if just_completed and last_operation_complete_time != current_time:
+                _event("status", f"{FG_MAGENTA}Operation complete! Ready for new requests.{RESET}")
+                cooldown_until = time.time() + 2.0  # 2 second cooldown
+                last_operation_complete_time = current_time
+                global_last_text.clear()  # Clear dedup cache
+                main_job = None
+                # Clear completion flag
+                try:
+                    ns_list = list(namespace_for_memory)
+                    await client.store.delete_item(ns_list, "main_operation_complete")
+                except Exception:
+                    pass
+                # Don't continue - let the message be processed after cooldown
+                # The cooldown check above will handle waiting if needed
+
+            # Routing logic: Use ONLY server-side status, not client task status
+            if long_running and not just_completed:
+                # Secondary thread: handle queries during long operation
+                progress = long_info.get("progress", "?")
+                tool_name = long_info.get("tool_name", "operation")
+                _event("routing", f"Operation in progress ({progress}%), routing to secondary thread")
+                payload = {
+                    "messages": [{"type": "human", "content": user_text}],
+                    "thread_type": "secondary",
+                    "interim_messages_reset": False,
+                }
+                await stream_run(
+                    client,
+                    thread_id_updates,
+                    graph,
+                    payload,
+                    label=f"secondary [{progress}%]",
+                    namespace_for_memory=namespace_for_memory,
+                    global_last_text=global_last_text,
+                )
+                interim_messages_reset = False
+            else:
+                # Main thread: start new operation
+                _event("routing", "Starting new operation on main thread (background)")
+                interim_messages_reset = True
+                global_last_text.clear()  # Clear for new operation
+                payload = {
+                    "messages": [{"type": "human", "content": user_text}],
+                    "thread_type": "main",
+                    "interim_messages_reset": interim_messages_reset,
+                }
+
+                async def run_main() -> int:
+                    result = await stream_run(
+                        client,
+                        thread_id_main,
+                        graph,
+                        payload,
+                        label="main",
+                        namespace_for_memory=namespace_for_memory,
+                        global_last_text=global_last_text,
+                    )
+                    # After completion, signal cooldown
+                    return result
+
+                main_job = asyncio.create_task(run_main())
+                # Do not await; allow user to type while long task runs
+
+        # On exit, best-effort wait for background
+        if main_job is not None:
+            print(f"\n{FG_GRAY}Waiting for background task to complete...{RESET}")
+            with contextlib.suppress(Exception):
+                await asyncio.wait_for(main_job, timeout=10)
+        return 0
+    else:
+        # Non-interactive: single message to main thread
+        msg = initial_message or "Hello, I need help with my mobile account"
+        print(f"{FG_BLUE}Sending:{RESET} {msg}\n")
+        payload = {
+            "messages": [{"type": "human", "content": msg}],
+            "thread_type": "main",
+            "interim_messages_reset": True,
+        }
+        global_last_text: dict[str, str] = {}
+        return await stream_run(
+            client,
+            thread_id_main,
+            graph,
+            payload,
+            label="single",
+            namespace_for_memory=namespace_for_memory,
+            global_last_text=global_last_text,
+        )
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="Client for multi-threaded telco agent",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Interactive mode (recommended)
+  python telco_client.py --interactive
+  
+  # Single message
+  python telco_client.py --message "What's my current package?"
+  
+  # Custom server and user
+  python telco_client.py --url http://localhost:8000 --user john_doe --interactive
+  
+  # Use different thread file
+  python telco_client.py --thread-file .telco_thread --interactive
+        """
+    )
+    parser.add_argument(
+        "--url",
+        default="http://127.0.0.1:2024",
+        help="LangGraph server base URL (default: http://127.0.0.1:2024)"
+    )
+    parser.add_argument(
+        "--graph",
+        default="telco-agent",
+        help="Graph name as defined in langgraph.json (default: telco-agent)"
+    )
+    parser.add_argument(
+        "--user",
+        default="fciannella",
+        help="User ID for namespace (default: fciannella)"
+    )
+    parser.add_argument(
+        "--interactive",
+        action="store_true",
+        help="Interactive mode (chat continuously)"
+    )
+    parser.add_argument(
+        "--thread-file",
+        default=".telco_thread_id",
+        help="Path to persist/load main thread ID (default: .telco_thread_id)"
+    )
+    parser.add_argument(
+        "--message",
+        "-m",
+        help="Single message to send (non-interactive mode)"
+    )
+    args = parser.parse_args(argv)
+
+    return asyncio.run(
+        run_client(
+            base_url=args.url,
+            graph=args.graph,
+            user_id=args.user,
+            interactive=args.interactive,
+            thread_file=args.thread_file,
+            initial_message=args.message,
+        )
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/README.md

@@ -0,0 +1,56 @@
+# Wire Transfer Agent
+
+This agent helps customers send domestic or international wire transfers using mock tools and data. It verifies the caller, collects transfer details, validates requirements, provides a quote (FX/fees/ETA), then confirms with OTP before executing.
+
+## How to use
+
+1. Start with your full name.
+2. Verify identity (mandatory): provide DOB plus either SSN last-4 or your secret answer. If a secret question is returned, answer it.
+3. Provide transfer info one by one when asked: type (DOMESTIC/INTERNATIONAL), source account (last-4), amount and source currency, destination country and currency, who pays fees (OUR/SHA/BEN).
+4. Provide beneficiary details depending on country requirements.
+5. Review the quote (FX rate, fees, net sent/received, ETA), then request OTP, provide the code, and confirm execution.
+
+## Mock identities and accounts
+
+From `mock_data/accounts.json`:
+
+- Francesco Ciannella (`cust_test`)
+  - DOB 1990-01-01, SSN last-4 6001, secret answer "blue"
+  - Accounts: `WT-CHK-001` (wire-enabled, USD, balance 5200.50), `WT-SAV-001` (not wire-enabled)
+- Alice Stone (`cust_alice`): last-4 1101, secret answer "green"
+
+OTP: see `mock_data/otps.json` (default = 123456).
+
+Country requirements (`mock_data/country_requirements.json`):
+- US: routing_number, account_number, account_name
+- CA: institution_number, transit_number, account_number, account_name
+- EU: iban, account_name
+
+## Example conversation
+
+- Agent: Hi! What’s your full name?
+- You: Francesco Ciannella
+- Agent: Please provide DOB and either SSN last-4 or your secret answer.
+- You: 1990-01-01 and 6001
+- Agent: Verified. Is this a DOMESTIC or INTERNATIONAL wire?
+- You: INTERNATIONAL
+- Agent: From which account (last-4)?
+- You: 6001
+- Agent: How much and currency?
+- You: 1000 USD to EUR
+- Agent: Destination country?
+- You: DE
+- Agent: Who pays fees (OUR/SHA/BEN)?
+- You: SHA
+- Agent: Please provide beneficiary fields required for DE (EU): iban and account_name.
+- You: iban DE89 37040044 0532013000, account_name Alice GmbH
+- Agent: Here’s your quote: FX, fees, net sent/received, ETA. Shall I send an OTP to confirm?
+- You: Yes
+- Agent: Please provide the 6-digit OTP.
+- You: 123456
+- Agent: Transfer submitted. Confirmation WI-XXXXXX
+
+## Notes
+
+- Wire is only allowed from wire-enabled accounts and within daily limits and balances.
+- For SHA/BEN, recipient fees reduce the amount received.

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/__init__.py

@@ -0,0 +1,9 @@
+"""Wire Transfer Agent (ReAct)
+
+This package contains a LangGraph ReAct-based agent that helps users
+initiate domestic or international wire transfers using mock tools and fixtures.
+"""
+
+from .react_agent import agent  # noqa: F401
+
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/fees_agent.py

@@ -0,0 +1,15 @@
+"""Compatibility shim.
+
+Some environments may still reference `./rbc-fees-agent/fees_agent.py:agent`.
+This file re-exports the ReAct agent defined in `react_agent.py`.
+"""
+
+try:
+    from .react_agent import agent  # noqa: F401
+except ImportError:
+    import os as _os
+    import sys as _sys
+    _sys.path.append(_os.path.dirname(__file__))
+    from react_agent import agent  # type: ignore  # noqa: F401
+
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/logic.py

@@ -0,0 +1,634 @@
+import os
+import json
+import uuid
+from datetime import datetime
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from langchain_openai import ChatOpenAI
+
+
+_FIXTURE_CACHE: Dict[str, Any] = {}
+_DISPUTES_DB: Dict[str, Dict[str, Any]] = {}
+_SESSIONS: Dict[str, Dict[str, Any]] = {}
+_OTP_DB: Dict[str, Dict[str, Any]] = {}
+_QUOTES: Dict[str, Dict[str, Any]] = {}
+_BENEFICIARIES_DB: Dict[str, List[Dict[str, Any]]] = {}
+
+
+def _fixtures_dir() -> Path:
+    return Path(__file__).parent / "mock_data"
+
+
+def _load_fixture(name: str) -> Any:
+    if name in _FIXTURE_CACHE:
+        return _FIXTURE_CACHE[name]
+    p = _fixtures_dir() / name
+    with p.open("r", encoding="utf-8") as f:
+        data = json.load(f)
+    _FIXTURE_CACHE[name] = data
+    return data
+
+
+def _parse_iso_date(text: Optional[str]) -> Optional[datetime]:
+    if not text:
+        return None
+    try:
+        return datetime.strptime(text, "%Y-%m-%d")
+    except Exception:
+        return None
+
+
+def _get_customer_blob(customer_id: str) -> Dict[str, Any]:
+    data = _load_fixture("accounts.json")
+    return dict(data.get("customers", {}).get(customer_id, {}))
+
+
+def get_accounts(customer_id: str) -> List[Dict[str, Any]]:
+    cust = _get_customer_blob(customer_id)
+    if isinstance(cust, list):
+        # backward-compat: old format was a list of accounts
+        return list(cust)
+    return list(cust.get("accounts", []))
+
+
+def get_profile(customer_id: str) -> Dict[str, Any]:
+    cust = _get_customer_blob(customer_id)
+    if isinstance(cust, dict):
+        return dict(cust.get("profile", {}))
+    return {}
+
+
+def find_customer_by_name(first_name: str, last_name: str) -> Dict[str, Any]:
+    data = _load_fixture("accounts.json")
+    customers = data.get("customers", {})
+    fn = (first_name or "").strip().lower()
+    ln = (last_name or "").strip().lower()
+    for cid, blob in customers.items():
+        prof = blob.get("profile") if isinstance(blob, dict) else None
+        if isinstance(prof, dict):
+            pfn = str(prof.get("first_name") or "").strip().lower()
+            pln = str(prof.get("last_name") or "").strip().lower()
+            if fn == pfn and ln == pln:
+                return {"customer_id": cid, "profile": prof}
+    return {}
+
+
+def find_customer_by_full_name(full_name: str) -> Dict[str, Any]:
+    data = _load_fixture("accounts.json")
+    customers = data.get("customers", {})
+    target = (full_name or "").strip().lower()
+    for cid, blob in customers.items():
+        prof = blob.get("profile") if isinstance(blob, dict) else None
+        if isinstance(prof, dict):
+            fn = f"{str(prof.get('first_name') or '').strip()} {str(prof.get('last_name') or '').strip()}".strip().lower()
+            ff = str(prof.get("full_name") or "").strip().lower()
+            if target and (target == fn or target == ff):
+                return {"customer_id": cid, "profile": prof}
+    return {}
+
+
+def _normalize_dob(text: Optional[str]) -> Optional[str]:
+    if not isinstance(text, str) or not text.strip():
+        return None
+    t = text.strip().lower()
+    # YYYY-MM-DD
+    try:
+        if len(t) >= 10 and t[4] == '-' and t[7] == '-':
+            d = datetime.strptime(t[:10], "%Y-%m-%d")
+            return d.strftime("%Y-%m-%d")
+    except Exception:
+        pass
+    # YYYY MM DD or YYYY/MM/DD or YYYY.MM.DD (loosely)
+    try:
+        import re as _re
+        parts = _re.findall(r"\d+", t)
+        if len(parts) >= 3 and len(parts[0]) == 4:
+            y, m, d = int(parts[0]), int(parts[1]), int(parts[2])
+            if 1900 <= y <= 2100 and 1 <= m <= 12 and 1 <= d <= 31:
+                dt = datetime(y, m, d)
+                return dt.strftime("%Y-%m-%d")
+    except Exception:
+        pass
+    # Month name DD YYYY
+    MONTHS = {
+        "jan": 1, "january": 1, "feb": 2, "february": 2, "mar": 3, "march": 3,
+        "apr": 4, "april": 4, "may": 5, "jun": 6, "june": 6, "jul": 7, "july": 7,
+        "aug": 8, "august": 8, "sep": 9, "sept": 9, "september": 9,
+        "oct": 10, "october": 10, "nov": 11, "november": 11, "dec": 12, "december": 12,
+    }
+    try:
+        parts = t.replace(',', ' ').split()
+        if len(parts) >= 3 and parts[0] in MONTHS:
+            m = MONTHS[parts[0]]
+            day = int(''.join(ch for ch in parts[1] if ch.isdigit()))
+            year = int(parts[2])
+            d = datetime(year, m, day)
+            return d.strftime("%Y-%m-%d")
+    except Exception:
+        pass
+    # DD/MM/YYYY or MM/DD/YYYY
+    try:
+        for sep in ('/', '-'):
+            if sep in t and t.count(sep) == 2:
+                a, b, c = t.split(sep)[:3]
+                if len(c) == 4 and a.isdigit() and b.isdigit() and c.isdigit():
+                    da, db, dy = int(a), int(b), int(c)
+                    # If first looks like month, assume MM/DD
+                    if 1 <= da <= 12 and 1 <= db <= 31:
+                        d = datetime(dy, da, db)
+                    else:
+                        # assume DD/MM
+                        d = datetime(dy, db, da)
+                    return d.strftime("%Y-%m-%d")
+    except Exception:
+        pass
+    return None
+
+
+def _find_account_by_id(account_id: str) -> Optional[Dict[str, Any]]:
+    data = _load_fixture("accounts.json")
+    customers = data.get("customers", {})
+    for _, blob in customers.items():
+        accts = (blob or {}).get("accounts", [])
+        for a in accts or []:
+            if str(a.get("account_id")) == account_id:
+                return a
+    return None
+
+
+def get_account_balance(account_id: str) -> Dict[str, Any]:
+    acc = _find_account_by_id(account_id) or {}
+    return {
+        "account_id": account_id,
+        "currency": acc.get("currency"),
+        "balance": float(acc.get("balance", 0.0)),
+        "daily_wire_limit": float(acc.get("daily_wire_limit", 0.0)),
+        "wire_enabled": bool(acc.get("wire_enabled", False)),
+    }
+
+
+def get_exchange_rate(from_currency: str, to_currency: str, amount: float) -> Dict[str, Any]:
+    if from_currency.upper() == to_currency.upper():
+        return {
+            "from": from_currency.upper(),
+            "to": to_currency.upper(),
+            "mid_rate": 1.0,
+            "applied_rate": 1.0,
+            "margin_bps": 0,
+            "converted_amount": round(float(amount), 2),
+        }
+    data = _load_fixture("exchange_rates.json")
+    pairs = data.get("pairs", [])
+    mid = None
+    bps = 150
+    fc = from_currency.upper()
+    tc = to_currency.upper()
+    for p in pairs:
+        if str(p.get("from")).upper() == fc and str(p.get("to")).upper() == tc:
+            mid = float(p.get("mid_rate"))
+            bps = int(p.get("margin_bps", bps))
+            break
+    if mid is None:
+        # naive inverse lookup
+        for p in pairs:
+            if str(p.get("from")).upper() == tc and str(p.get("to")).upper() == fc:
+                inv = float(p.get("mid_rate"))
+                mid = 1.0 / inv if inv else None
+                bps = int(p.get("margin_bps", bps))
+                break
+    if mid is None:
+        mid = 1.0
+    applied = mid * (1.0 - bps / 10000.0)
+    converted = float(amount) * applied
+    return {
+        "from": fc,
+        "to": tc,
+        "mid_rate": round(mid, 6),
+        "applied_rate": round(applied, 6),
+        "margin_bps": bps,
+        "converted_amount": round(converted, 2),
+    }
+
+
+def calculate_wire_fee(kind: str, amount: float, from_currency: str, to_currency: str, payer: str) -> Dict[str, Any]:
+    fees = _load_fixture("fee_schedules.json")
+    k = (kind or "").strip().upper()
+    payer_opt = (payer or "SHA").strip().upper()
+    if k not in ("DOMESTIC", "INTERNATIONAL"):
+        return {"error": "invalid_type", "message": "type must be DOMESTIC or INTERNATIONAL"}
+    if payer_opt not in ("OUR", "SHA", "BEN"):
+        return {"error": "invalid_payer", "message": "payer must be OUR, SHA, or BEN"}
+    breakdown: Dict[str, float] = {}
+    if k == "DOMESTIC":
+        breakdown["DOMESTIC_BASE"] = float(fees.get("DOMESTIC", {}).get("base_fee", 15.0))
+    else:
+        intl = fees.get("INTERNATIONAL", {})
+        breakdown["INTERNATIONAL_BASE"] = float(intl.get("base_fee", 25.0))
+        breakdown["SWIFT"] = float(intl.get("swift_network_fee", 5.0))
+        breakdown["CORRESPONDENT"] = float(intl.get("correspondent_fee", 10.0))
+        breakdown["LIFTING"] = float(intl.get("lifting_fee", 5.0))
+
+    initiator = 0.0
+    recipient = 0.0
+    for code, fee in breakdown.items():
+        if payer_opt == "OUR":
+            initiator += fee
+        elif payer_opt == "SHA":
+            # Sender pays origin bank fees (base, swift); recipient pays intermediary (correspondent/lifting)
+            if code in ("DOMESTIC_BASE", "INTERNATIONAL_BASE", "SWIFT"):
+                initiator += fee
+            else:
+                recipient += fee
+        elif payer_opt == "BEN":
+            recipient += fee
+    return {
+        "type": k,
+        "payer": payer_opt,
+        "from_currency": from_currency.upper(),
+        "to_currency": to_currency.upper(),
+        "amount": float(amount),
+        "initiator_fees_total": round(initiator, 2),
+        "recipient_fees_total": round(recipient, 2),
+        "breakdown": {k: round(v, 2) for k, v in breakdown.items()},
+    }
+
+
+def screen_sanctions(name: str, country: str) -> Dict[str, Any]:
+    data = _load_fixture("sanctions_list.json")
+    blocked = data.get("blocked", [])
+    nm = (name or "").strip().lower()
+    cc = (country or "").strip().upper()
+    for e in blocked:
+        if str(e.get("name", "")).strip().lower() == nm and str(e.get("country", "")).strip().upper() == cc:
+            return {"cleared": False, "reason": "Sanctions match"}
+    return {"cleared": True}
+
+
+def check_wire_limits(account_id: str, amount: float) -> Dict[str, Any]:
+    acc = _find_account_by_id(account_id) or {}
+    if not acc:
+        return {"ok": False, "reason": "account_not_found"}
+    bal = float(acc.get("balance", 0.0))
+    lim = float(acc.get("daily_wire_limit", 0.0))
+    if not bool(acc.get("wire_enabled", False)):
+        return {"ok": False, "reason": "wire_not_enabled"}
+    if amount > lim:
+        return {"ok": False, "reason": "exceeds_daily_limit", "limit": lim}
+    if amount > bal:
+        return {"ok": False, "reason": "insufficient_funds", "balance": bal}
+    return {"ok": True, "balance": bal, "limit": lim}
+
+
+def get_cutoff_and_eta(kind: str, country: str) -> Dict[str, Any]:
+    cfg = _load_fixture("cutoff_times.json")
+    k = (kind or "").strip().upper()
+    key = "DOMESTIC" if k == "DOMESTIC" else "INTERNATIONAL"
+    info = cfg.get(key, {})
+    return {
+        "cutoff_local": info.get("cutoff_local", "17:00"),
+        "eta_hours": list(info.get("eta_hours", [24, 72])),
+        "country": country
+    }
+
+
+def get_country_requirements(code: str) -> List[str]:
+    data = _load_fixture("country_requirements.json")
+    return list(data.get(code.upper(), []))
+
+
+def validate_beneficiary(country_code: str, beneficiary: Dict[str, Any]) -> Dict[str, Any]:
+    required = get_country_requirements(country_code)
+    missing: List[str] = []
+    for field in required:
+        if not isinstance(beneficiary.get(field), str) or not str(beneficiary.get(field)).strip():
+            missing.append(field)
+    return {"ok": len(missing) == 0, "missing": missing}
+
+
+def save_beneficiary(customer_id: str, beneficiary: Dict[str, Any]) -> Dict[str, Any]:
+    arr = _BENEFICIARIES_DB.setdefault(customer_id, [])
+    bid = beneficiary.get("beneficiary_id") or f"B-{uuid.uuid4().hex[:6]}"
+    entry = dict(beneficiary)
+    entry["beneficiary_id"] = bid
+    arr.append(entry)
+    return {"beneficiary_id": bid}
+
+
+def generate_otp(customer_id: str) -> Dict[str, Any]:
+    # Prefer static OTP from fixture for predictable testing
+    static = None
+    try:
+        data = _load_fixture("otps.json")
+        if isinstance(data, dict):
+            byc = data.get("by_customer", {}) or {}
+            static = byc.get(customer_id) or data.get("default")
+    except Exception:
+        static = None
+    code = str(static or f"{uuid.uuid4().int % 1000000:06d}").zfill(6)
+    _OTP_DB[customer_id] = {"otp": code, "created_at": datetime.utcnow().isoformat() + "Z"}
+    # In real world, send to phone/email; here we mask
+    resp = {"sent": True, "destination": "on-file", "masked": "***-***-****"}
+    try:
+        if os.getenv("WIRE_DEBUG_OTP", "0").lower() not in ("", "0", "false"):  # dev convenience
+            resp["debug_code"] = code
+    except Exception:
+        pass
+    return resp
+
+
+def verify_otp(customer_id: str, otp: str) -> Dict[str, Any]:
+    rec = _OTP_DB.get(customer_id) or {}
+    ok = str(rec.get("otp")) == str(otp)
+    if ok:
+        rec["used_at"] = datetime.utcnow().isoformat() + "Z"
+        _OTP_DB[customer_id] = rec
+    return {"verified": ok}
+
+
+def authenticate_user_wire(session_id: str, customer_id: Optional[str], full_name: Optional[str], dob_yyyy_mm_dd: Optional[str], ssn_last4: Optional[str], secret_answer: Optional[str]) -> Dict[str, Any]:
+    session = _SESSIONS.get(session_id) or {"verified": False, "customer_id": customer_id, "name": full_name}
+    if isinstance(customer_id, str) and customer_id:
+        session["customer_id"] = customer_id
+    if isinstance(full_name, str) and full_name:
+        session["name"] = full_name
+    if isinstance(dob_yyyy_mm_dd, str) and dob_yyyy_mm_dd:
+        session["dob"] = dob_yyyy_mm_dd
+    if isinstance(ssn_last4, str) and ssn_last4:
+        session["ssn_last4"] = ssn_last4
+    if isinstance(secret_answer, str) and secret_answer:
+        session["secret"] = secret_answer
+
+    ok = False
+    cid = session.get("customer_id")
+    if isinstance(cid, str):
+        prof = get_profile(cid)
+        user_dob_norm = _normalize_dob(session.get("dob"))
+        prof_dob_norm = _normalize_dob(prof.get("dob"))
+        dob_ok = (user_dob_norm is not None) and (user_dob_norm == prof_dob_norm)
+        ssn_ok = str(session.get("ssn_last4") or "") == str(prof.get("ssn_last4") or "")
+        def _norm(x: Optional[str]) -> str:
+            # Extract only the core answer, removing common phrases
+            s = (x or "").strip().lower()
+            # Remove common prefixes that users might add
+            for prefix in ["my favorite color is ", "my favorite ", "it is ", "it's ", "the answer is "]:
+                if s.startswith(prefix):
+                    s = s[len(prefix):].strip()
+            return s
+        secret_ok = _norm(session.get("secret")) == _norm(prof.get("secret_answer"))
+        if dob_ok and (ssn_ok or secret_ok):
+            ok = True
+    session["verified"] = ok
+    _SESSIONS[session_id] = session
+    need: List[str] = []
+    if _normalize_dob(session.get("dob")) is None:
+        need.append("dob")
+    if not session.get("ssn_last4") and not session.get("secret"):
+        need.append("ssn_last4_or_secret")
+    if not session.get("customer_id"):
+        need.append("customer")
+    resp: Dict[str, Any] = {"session_id": session_id, "verified": ok, "needs": need, "profile": {"name": session.get("name")}}
+    try:
+        if isinstance(session.get("customer_id"), str):
+            prof = get_profile(session.get("customer_id"))
+            if isinstance(prof, dict) and prof.get("secret_question"):
+                resp["question"] = prof.get("secret_question")
+    except Exception:
+        pass
+    return resp
+
+
+def quote_wire(kind: str, from_account_id: str, beneficiary: Dict[str, Any], amount: float, from_currency: str, to_currency: str, payer: str) -> Dict[str, Any]:
+    # FX
+    fx = get_exchange_rate(from_currency, to_currency, amount)
+    converted_amount = fx["converted_amount"]
+    # Fees
+    fee = calculate_wire_fee(kind, amount, from_currency, to_currency, payer)
+    # Limits and balance
+    limits = check_wire_limits(from_account_id, amount)
+    if not limits.get("ok"):
+        return {"error": "limit_or_balance", "details": limits}
+    # Sanctions
+    sanc = screen_sanctions(str(beneficiary.get("account_name") or beneficiary.get("name") or ""), str(beneficiary.get("country") or ""))
+    if not sanc.get("cleared"):
+        return {"error": "sanctions", "details": sanc}
+    # ETA
+    eta = get_cutoff_and_eta(kind, str(beneficiary.get("country") or ""))
+
+    payer_opt = (payer or "SHA").upper()
+    initiator_fees = float(fee.get("initiator_fees_total", 0.0))
+    recipient_fees = float(fee.get("recipient_fees_total", 0.0))
+    net_sent = float(amount) + (initiator_fees if payer_opt in ("OUR", "SHA") else 0.0)
+    # recipient side fees reduce the amount received when SHA/BEN
+    net_received = float(converted_amount)
+    if payer_opt in ("SHA", "BEN"):
+        net_received = max(0.0, net_received - recipient_fees)
+
+    qid = f"Q-{uuid.uuid4().hex[:8]}"
+    quote = {
+        "quote_id": qid,
+        "type": kind.upper(),
+        "from_account_id": from_account_id,
+        "amount": float(amount),
+        "from_currency": from_currency.upper(),
+        "to_currency": to_currency.upper(),
+        "payer": payer_opt,
+        "fx": fx,
+        "fees": fee,
+        "net_sent": round(net_sent, 2),
+        "net_received": round(net_received, 2),
+        "eta": eta,
+        "created_at": datetime.utcnow().isoformat() + "Z",
+        "expires_at": (datetime.utcnow().isoformat() + "Z")
+    }
+    _QUOTES[qid] = quote
+    return quote
+
+
+def wire_transfer_domestic(quote_id: str, otp: str) -> Dict[str, Any]:
+    q = _QUOTES.get(quote_id)
+    if not q or q.get("type") != "DOMESTIC":
+        return {"error": "invalid_quote"}
+    # OTP expected: we need customer_id context; skip and assume OTP verified externally
+    conf = f"WD-{uuid.uuid4().hex[:8]}"
+    return {"confirmation_id": conf, "status": "submitted"}
+
+
+def wire_transfer_international(quote_id: str, otp: str) -> Dict[str, Any]:
+    q = _QUOTES.get(quote_id)
+    if not q or q.get("type") != "INTERNATIONAL":
+        return {"error": "invalid_quote"}
+    conf = f"WI-{uuid.uuid4().hex[:8]}"
+    return {"confirmation_id": conf, "status": "submitted"}
+
+
+def list_transactions(account_id: str, start: Optional[str], end: Optional[str]) -> List[Dict[str, Any]]:
+    data = _load_fixture("transactions.json")
+    txns = list(data.get(account_id, []))
+    if start or end:
+        start_dt = _parse_iso_date(start) or datetime.min
+        end_dt = _parse_iso_date(end) or datetime.max
+        out: List[Dict[str, Any]] = []
+        for t in txns:
+            td = _parse_iso_date(t.get("date"))
+            if td and start_dt <= td <= end_dt:
+                out.append(t)
+        return out
+    return txns
+
+
+def get_fee_schedule(product_type: str) -> Dict[str, Any]:
+    data = _load_fixture("fee_schedules.json")
+    return dict(data.get(product_type.upper(), {}))
+
+
+def detect_fees(transactions: List[Dict[str, Any]], schedule: Dict[str, Any]) -> List[Dict[str, Any]]:
+    results: List[Dict[str, Any]] = []
+    for t in transactions:
+        if str(t.get("entry_type")).upper() == "FEE":
+            fee_code = (t.get("fee_code") or "").upper()
+            sched_entry = None
+            for s in schedule.get("fees", []) or []:
+                if str(s.get("code", "")).upper() == fee_code:
+                    sched_entry = s
+                    break
+            evt = {
+                "id": t.get("id") or str(uuid.uuid4()),
+                "posted_date": t.get("date"),
+                "amount": float(t.get("amount", 0)),
+                "description": t.get("description") or fee_code,
+                "fee_code": fee_code,
+                "schedule": sched_entry or None,
+            }
+            results.append(evt)
+    try:
+        results.sort(key=lambda x: x.get("posted_date") or "")
+    except Exception:
+        pass
+    return results
+
+
+def explain_fee(fee_event: Dict[str, Any]) -> str:
+    openai_api_key = os.getenv("OPENAI_API_KEY")
+    code = (fee_event.get("fee_code") or "").upper()
+    name = fee_event.get("schedule", {}).get("name") or code.title()
+    posted = fee_event.get("posted_date") or ""
+    amount = float(fee_event.get("amount") or 0)
+    policy = fee_event.get("schedule", {}).get("policy") or ""
+    if not openai_api_key:
+        base = f"You were charged {name} on {posted} for CAD {amount:.2f}."
+        if code == "NSF":
+            return base + " This is applied when a payment is attempted but the account balance was insufficient."
+        if code == "MAINTENANCE":
+            return base + " This is the monthly account fee as per your account plan."
+        if code == "ATM":
+            return base + " This fee applies to certain ATM withdrawals."
+        return base + " This fee was identified based on your recent transactions."
+
+    llm = ChatOpenAI(model=os.getenv("EXPLAIN_MODEL", "gpt-4o"), api_key=openai_api_key)
+    chain = EXPLAIN_FEE_PROMPT | llm
+    out = chain.invoke(
+        {
+            "fee_code": code,
+            "posted_date": posted,
+            "amount": f"{amount:.2f}",
+            "schedule_name": name,
+            "schedule_policy": policy,
+        }
+    )
+    text = getattr(out, "content", None)
+    return text if isinstance(text, str) and text.strip() else f"You were charged {name} on {posted} for CAD {amount:.2f}."
+
+
+def check_dispute_eligibility(fee_event: Dict[str, Any]) -> Dict[str, Any]:
+    code = (fee_event.get("fee_code") or "").upper()
+    amount = float(fee_event.get("amount", 0))
+    first_time = bool(fee_event.get("first_time_90d", False))
+    eligible = False
+    reason = ""
+    if code in {"NSF", "ATM", "MAINTENANCE", "WITHDRAWAL"} and amount <= 20.0 and first_time:
+        eligible = True
+        reason = "First occurrence in 90 days and small amount"
+    return {"eligible": eligible, "reason": reason}
+
+
+def create_dispute_case(fee_event: Dict[str, Any], idempotency_key: str) -> Dict[str, Any]:
+    if idempotency_key in _DISPUTES_DB:
+        return _DISPUTES_DB[idempotency_key]
+    case = {
+        "case_id": str(uuid.uuid4()),
+        "status": "submitted",
+        "fee_id": fee_event.get("id"),
+        "created_at": datetime.utcnow().isoformat() + "Z",
+    }
+    _DISPUTES_DB[idempotency_key] = case
+    return case
+
+
+def authenticate_user(session_id: str, name: Optional[str], dob_yyyy_mm_dd: Optional[str], last4: Optional[str], secret_answer: Optional[str], customer_id: Optional[str] = None) -> Dict[str, Any]:
+    """Mock identity verification.
+
+    Rules (mock):
+    - If dob == 1990-01-01 and last4 == 6001 or secret_answer == "blue", auth succeeds.
+    - Otherwise, remains pending with which fields are still missing.
+    Persists per session_id.
+    """
+    session = _SESSIONS.get(session_id) or {"verified": False, "name": name, "customer_id": customer_id}
+    if isinstance(name, str) and name:
+        session["name"] = name
+    if isinstance(customer_id, str) and customer_id:
+        session["customer_id"] = customer_id
+    if isinstance(dob_yyyy_mm_dd, str) and dob_yyyy_mm_dd:
+        # Normalize DOB to YYYY-MM-DD
+        norm = _normalize_dob(dob_yyyy_mm_dd)
+        session["dob"] = norm or dob_yyyy_mm_dd
+    if isinstance(last4, str) and last4:
+        session["last4"] = last4
+    if isinstance(secret_answer, str) and secret_answer:
+        session["secret"] = secret_answer
+
+    ok = False
+    # If a specific customer is in context, validate against their profile and accounts
+    if isinstance(session.get("customer_id"), str):
+        prof = get_profile(session.get("customer_id"))
+        accts = get_accounts(session.get("customer_id"))
+        dob_ok = _normalize_dob(session.get("dob")) == _normalize_dob(prof.get("dob")) and bool(session.get("dob"))
+        last4s = {str(a.get("account_number"))[-4:] for a in accts if a.get("account_number")}
+        last4_ok = isinstance(session.get("last4"), str) and session.get("last4") in last4s
+        def _norm_secret(x: Optional[str]) -> str:
+            # Extract only the core answer, removing common phrases
+            s = (x or "").strip().lower()
+            # Remove common prefixes that users might add
+            for prefix in ["my favorite color is ", "my favorite ", "it is ", "it's ", "the answer is "]:
+                if s.startswith(prefix):
+                    s = s[len(prefix):].strip()
+            return s
+        secret_ok = _norm_secret(session.get("secret")) == _norm_secret(prof.get("secret_answer"))
+        if dob_ok and (last4_ok or secret_ok):
+            ok = True
+    else:
+        # Optional demo fallback (disabled by default)
+        allow_fallback = os.getenv("RBC_FEES_ALLOW_GLOBAL_FALLBACK", "0") not in ("", "0", "false", "False")
+        if allow_fallback and session.get("dob") == "1990-01-01" and (session.get("last4") == "6001" or (session.get("secret") or "").strip().lower() == "blue"):
+            ok = True
+    session["verified"] = ok
+    _SESSIONS[session_id] = session
+    need: list[str] = []
+    if not session.get("dob"):
+        need.append("dob")
+    if not session.get("last4") and not session.get("secret"):
+        need.append("last4_or_secret")
+    if not session.get("customer_id"):
+        need.append("customer")
+    resp: Dict[str, Any] = {"session_id": session_id, "verified": ok, "needs": need, "profile": {"name": session.get("name")}}
+    try:
+        if isinstance(session.get("customer_id"), str):
+            prof = get_profile(session.get("customer_id"))
+            if isinstance(prof, dict) and prof.get("secret_question"):
+                resp["question"] = prof.get("secret_question")
+    except Exception:
+        pass
+    return resp
+
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/mock_data/accounts.json

@@ -0,0 +1,170 @@
+{
+  "customers": {
+    "cust_test": {
+      "profile": {
+        "first_name": "Francesco",
+        "last_name": "Ciannella",
+        "full_name": "Francesco Ciannella",
+        "dob": "1990-01-01",
+        "ssn_last4": "6001",
+        "secret_question": "What is your favorite color?",
+        "secret_answer": "blue",
+        "phone_masked": "***-***-1234"
+      },
+      "accounts": [
+        {
+          "account_id": "WT-CHK-001",
+          "product_type": "CHK",
+          "nickname": "Everyday Chequing",
+          "account_number": "6001",
+          "currency": "USD",
+          "balance": 5200.50,
+          "wire_enabled": true,
+          "daily_wire_limit": 10000.00
+        },
+        {
+          "account_id": "WT-SAV-001",
+          "product_type": "SAV",
+          "nickname": "High Interest Savings",
+          "account_number": "7182",
+          "currency": "USD",
+          "balance": 12000.00,
+          "wire_enabled": false,
+          "daily_wire_limit": 0.00
+        }
+      ]
+    },
+    "cust_alice": {
+      "profile": {
+        "first_name": "Alice",
+        "last_name": "Stone",
+        "full_name": "Alice Stone",
+        "dob": "1985-05-12",
+        "ssn_last4": "1101",
+        "secret_question": "Favorite color?",
+        "secret_answer": "green",
+        "phone_masked": "***-***-2211"
+      },
+      "accounts": [
+        {
+          "account_id": "WT-CHK-101",
+          "product_type": "CHK",
+          "nickname": "Everyday Chequing",
+          "account_number": "1101",
+          "currency": "CAD",
+          "balance": 2450.00,
+          "wire_enabled": true,
+          "daily_wire_limit": 7500.00
+        },
+        {
+          "account_id": "WT-SAV-101",
+          "product_type": "SAV",
+          "nickname": "High Interest Savings",
+          "account_number": "7101",
+          "currency": "CAD",
+          "balance": 8000.00,
+          "wire_enabled": false,
+          "daily_wire_limit": 0.00
+        }
+      ]
+    },
+    "cust_bob": {
+      "profile": {
+        "first_name": "Bob",
+        "last_name": "Rivera",
+        "full_name": "Bob Rivera",
+        "dob": "1978-11-30",
+        "ssn_last4": "1202",
+        "secret_question": "Favorite color?",
+        "secret_answer": "red",
+        "phone_masked": "***-***-3322"
+      },
+      "accounts": [
+        {
+          "account_id": "WT-CHK-202",
+          "product_type": "CHK",
+          "nickname": "Primary Chequing",
+          "account_number": "1202",
+          "currency": "USD",
+          "balance": 3900.00,
+          "wire_enabled": true,
+          "daily_wire_limit": 5000.00
+        }
+      ]
+    },
+    "cust_carla": {
+      "profile": {
+        "first_name": "Carla",
+        "last_name": "Nguyen",
+        "full_name": "Carla Nguyen",
+        "dob": "1992-03-14",
+        "ssn_last4": "7303",
+        "secret_question": "Favorite color?",
+        "secret_answer": "blue",
+        "phone_masked": "***-***-4433"
+      },
+      "accounts": [
+        {
+          "account_id": "WT-SAV-303",
+          "product_type": "SAV",
+          "nickname": "Savings",
+          "account_number": "7303",
+          "currency": "EUR",
+          "balance": 1500.00,
+          "wire_enabled": true,
+          "daily_wire_limit": 3000.00
+        }
+      ]
+    },
+    "cust_dave": {
+      "profile": {
+        "first_name": "David",
+        "last_name": "Patel",
+        "full_name": "David Patel",
+        "dob": "1989-07-21",
+        "ssn_last4": "1404",
+        "secret_question": "Favorite animal?",
+        "secret_answer": "tiger",
+        "phone_masked": "***-***-5544"
+      },
+      "accounts": [
+        {
+          "account_id": "WT-CHK-404",
+          "product_type": "CHK",
+          "nickname": "Everyday Chequing",
+          "account_number": "1404",
+          "currency": "USD",
+          "balance": 15000.00,
+          "wire_enabled": true,
+          "daily_wire_limit": 20000.00
+        }
+      ]
+    },
+    "cust_eve": {
+      "profile": {
+        "first_name": "Evelyn",
+        "last_name": "Moore",
+        "full_name": "Evelyn Moore",
+        "dob": "1995-09-09",
+        "ssn_last4": "7505",
+        "secret_question": "Favorite season?",
+        "secret_answer": "summer",
+        "phone_masked": "***-***-6655"
+      },
+      "accounts": [
+        {
+          "account_id": "WT-SAV-505",
+          "product_type": "SAV",
+          "nickname": "High Interest Savings",
+          "account_number": "7505",
+          "currency": "CAD",
+          "balance": 6400.00,
+          "wire_enabled": true,
+          "daily_wire_limit": 4000.00
+        }
+      ]
+    }
+  }
+}
+
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/mock_data/beneficiaries.json

@@ -0,0 +1,15 @@
+{
+  "saved": [
+    {
+      "customer_id": "cust_test",
+      "beneficiary_id": "B-001",
+      "name": "John Smith",
+      "country": "US",
+      "currency": "USD",
+      "bank_fields": {"routing_number": "021000021", "account_number": "123456789", "account_name": "John Smith"},
+      "last_used_at": "2025-08-25T10:00:00Z"
+    }
+  ]
+}
+
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/mock_data/country_requirements.json

@@ -0,0 +1,11 @@
+{
+  "US": ["routing_number", "account_number", "account_name"],
+  "CA": ["institution_number", "transit_number", "account_number", "account_name"],
+  "GB": ["sort_code", "account_number", "account_name"],
+  "EU": ["iban", "account_name"],
+  "MX": ["clabe", "account_name"],
+  "IN": ["ifsc", "account_number", "account_name"],
+  "RU": ["account_number", "account_name"]
+}
+
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/mock_data/cutoff_times.json

@@ -0,0 +1,6 @@
+{
+  "DOMESTIC": {"cutoff_local": "17:00", "eta_hours": [2, 24]},
+  "INTERNATIONAL": {"cutoff_local": "15:00", "eta_hours": [24, 72]}
+}
+
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/mock_data/exchange_rates.json

@@ -0,0 +1,12 @@
+{
+  "pairs": [
+    {"from": "USD", "to": "EUR", "mid_rate": 0.92, "margin_bps": 150, "updated_at": "2025-08-25T12:00:00Z"},
+    {"from": "USD", "to": "CAD", "mid_rate": 1.32, "margin_bps": 120, "updated_at": "2025-08-25T12:00:00Z"},
+    {"from": "CAD", "to": "USD", "mid_rate": 0.76, "margin_bps": 120, "updated_at": "2025-08-25T12:00:00Z"},
+    {"from": "CAD", "to": "GBP", "mid_rate": 0.58, "margin_bps": 160, "updated_at": "2025-08-25T12:00:00Z"},
+    {"from": "USD", "to": "RUB", "mid_rate": 90.0, "margin_bps": 200, "updated_at": "2025-08-25T12:00:00Z"},
+    {"from": "RUB", "to": "USD", "mid_rate": 0.011111, "margin_bps": 200, "updated_at": "2025-08-25T12:00:00Z"}
+  ]
+}
+
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/mock_data/fee_schedules.json

@@ -0,0 +1,17 @@
+{
+  "DOMESTIC": {
+    "base_fee": 15.00,
+    "expedited_fee": 10.00,
+    "networks": ["ACH", "FEDWIRE"],
+    "payer_rules": {"OUR": true, "SHA": true, "BEN": true}
+  },
+  "INTERNATIONAL": {
+    "base_fee": 25.00,
+    "correspondent_fee": 10.00,
+    "lifting_fee": 5.00,
+    "swift_network_fee": 5.00,
+    "payer_rules": {"OUR": true, "SHA": true, "BEN": true}
+  }
+}
+
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/mock_data/limits.json

@@ -0,0 +1,15 @@
+{
+  "global": {"daily_total_limit": 20000.0},
+  "per_account": {
+    "WT-CHK-001": {"daily_limit": 10000.0},
+    "WT-SAV-001": {"daily_limit": 0.0},
+    "WT-CHK-101": {"daily_limit": 7500.0},
+    "WT-SAV-101": {"daily_limit": 0.0},
+    "WT-CHK-202": {"daily_limit": 5000.0},
+    "WT-SAV-303": {"daily_limit": 3000.0},
+    "WT-CHK-404": {"daily_limit": 20000.0},
+    "WT-SAV-505": {"daily_limit": 4000.0}
+  }
+}
+
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/mock_data/otps.json

@@ -0,0 +1,13 @@
+{
+  "default": "123456",
+  "by_customer": {
+    "cust_test": "123456",
+    "cust_alice": "123456",
+    "cust_bob": "123456",
+    "cust_carla": "123456",
+    "cust_dave": "123456",
+    "cust_eve": "123456"
+  }
+}
+
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/mock_data/packages.json

@@ -0,0 +1,11 @@
+{
+  "FX_MARGINS_BPS": 150,
+  "WIRE_PLANS": [
+    {"id": "WIRE_BASIC", "name": "Wire Basic", "monthly_fee": 0.0, "notes": "Pay per transfer; standard fees apply."},
+    {"id": "WIRE_PLUS", "name": "Wire Plus", "monthly_fee": 15.0, "waives": ["DOMESTIC_BASE"], "reduces": {"INTERNATIONAL_BASE": 0.5}, "notes": "Domestic base fee waived; 50% off international base fee."},
+    {"id": "WIRE_PREMIER", "name": "Wire Premier", "monthly_fee": 30.0, "waives": ["DOMESTIC_BASE", "INTERNATIONAL_BASE", "SWIFT"], "reduces": {"CORRESPONDENT": 0.5}, "notes": "Waives base fees; cuts correspondent 50%; great for frequent senders."}
+  ],
+  "DEFAULTS": {"domestic_base": 15.0, "international_base": 25.0, "swift": 5.0, "correspondent": 10.0, "lifting": 5.0}
+}
+
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/mock_data/sanctions_list.json

@@ -0,0 +1,8 @@
+{
+  "blocked": [
+    {"name": "ACME Import Export", "country": "RU"},
+    {"name": "Global Holdings", "country": "IR"}
+  ]
+}
+
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/mock_data/transactions.json

@@ -0,0 +1,22 @@
+{
+  "WT-CHK-001": [
+    {"id": "w1", "date": "2025-08-25", "amount": -1200.00, "description": "Wire to John Smith (domestic)", "entry_type": "WIRE", "direction": "OUT"},
+    {"id": "w2", "date": "2025-08-25", "amount": -15.00, "description": "Wire fee domestic", "entry_type": "FEE", "fee_code": "WIRE_OUT"},
+    {"id": "p1", "date": "2025-08-15", "amount": 3000.00, "description": "Payroll", "entry_type": "CREDIT"}
+  ],
+  "WT-SAV-001": [],
+  "WT-CHK-101": [
+    {"id": "w3", "date": "2025-08-12", "amount": -2500.00, "description": "Wire to UK vendor (international)", "entry_type": "WIRE", "direction": "OUT"},
+    {"id": "w4", "date": "2025-08-12", "amount": -25.00, "description": "Wire fee international", "entry_type": "FEE", "fee_code": "WIRE_OUT"}
+  ],
+  "WT-SAV-101": [],
+  "WT-CHK-202": [],
+  "WT-SAV-303": [],
+  "WT-CHK-404": [
+    {"id": "w5", "date": "2025-08-05", "amount": -5000.00, "description": "Wire to CA supplier (international)", "entry_type": "WIRE", "direction": "OUT"},
+    {"id": "w6", "date": "2025-08-05", "amount": -35.00, "description": "Wire fee international", "entry_type": "FEE", "fee_code": "WIRE_OUT"}
+  ],
+  "WT-SAV-505": []
+}
+
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/prompts.py

@@ -0,0 +1,31 @@
+from langchain_core.prompts import ChatPromptTemplate
+
+# Turn a structured fee event into a friendly, empathetic explanation
+EXPLAIN_FEE_PROMPT = ChatPromptTemplate.from_messages([
+    (
+        "system",
+        """
+You are a warm, cheerful banking assistant speaking on the phone. Use a friendly, empathetic tone.
+Guidelines:
+- Start with brief empathy (e.g., "I know surprise fees can be frustrating.").
+- Clearly explain what the fee is and why it was applied.
+- Keep it concise (2–3 sentences), plain language, no jargon.
+- Offer help-oriented phrasing ("we can look into options"), no blame.
+""",
+    ),
+    (
+        "human",
+        """
+Fee event:
+- code: {fee_code}
+- posted_date: {posted_date}
+- amount: {amount}
+- schedule_name: {schedule_name}
+- schedule_policy: {schedule_policy}
+
+Write a concise explanation (2–3 sentences) suitable for a mobile UI.
+""",
+    ),
+])
+
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/react_agent.py

@@ -0,0 +1,396 @@
+import os
+import json
+import logging
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List
+
+from langgraph.func import entrypoint, task
+from langgraph.graph import add_messages
+from langchain_openai import ChatOpenAI
+from langchain_core.messages import (
+    SystemMessage,
+    HumanMessage,
+    AIMessage,
+    BaseMessage,
+    ToolCall,
+    ToolMessage,
+)
+
+
+# ---- Tools (wire-transfer) ----
+
+try:
+    from . import tools as wire_tools  # type: ignore
+except Exception:
+    import importlib.util as _ilu
+    _dir = os.path.dirname(__file__)
+    _tools_path = os.path.join(_dir, "tools.py")
+    _spec = _ilu.spec_from_file_location("wire_transfer_agent_tools", _tools_path)
+    wire_tools = _ilu.module_from_spec(_spec)  # type: ignore
+    assert _spec and _spec.loader
+    _spec.loader.exec_module(wire_tools)  # type: ignore
+
+# Aliases for tool functions
+list_accounts = wire_tools.list_accounts
+get_customer_profile = wire_tools.get_customer_profile
+find_customer = wire_tools.find_customer
+find_account_by_last4 = wire_tools.find_account_by_last4
+verify_identity = wire_tools.verify_identity
+get_account_balance_tool = wire_tools.get_account_balance_tool
+get_exchange_rate_tool = wire_tools.get_exchange_rate_tool
+calculate_wire_fee_tool = wire_tools.calculate_wire_fee_tool
+check_wire_limits_tool = wire_tools.check_wire_limits_tool
+get_cutoff_and_eta_tool = wire_tools.get_cutoff_and_eta_tool
+get_country_requirements_tool = wire_tools.get_country_requirements_tool
+validate_beneficiary_tool = wire_tools.validate_beneficiary_tool
+save_beneficiary_tool = wire_tools.save_beneficiary_tool
+quote_wire_tool = wire_tools.quote_wire_tool
+generate_otp_tool = wire_tools.generate_otp_tool
+verify_otp_tool = wire_tools.verify_otp_tool
+wire_transfer_domestic = wire_tools.wire_transfer_domestic
+wire_transfer_international = wire_tools.wire_transfer_international
+find_customer_by_name = wire_tools.find_customer_by_name
+
+
+"""ReAct agent entrypoint and system prompt."""
+
+
+SYSTEM_PROMPT = (
+    "You are a warm, cheerful banking assistant helping a customer send a wire transfer (domestic or international). "
+    "Start with a brief greeting and very short small talk. Then ask for the caller's full name. "
+    "CUSTOMER LOOKUP: After receiving the customer's name, thank them and call find_customer with their first and last name to get their customer_id. If find_customer returns an empty result ({}), politely ask the customer to confirm their full name spelling or offer to look them up by other details. Do NOT proceed to asking for date of birth if you don't have a valid customer_id. "
+    "IDENTITY IS MANDATORY: Once you have a customer_id from find_customer, you MUST call verify_identity. Thank the customer for their name, then ask for date of birth (customer can use any format; you normalize) and EITHER SSN last-4 OR the secret answer. If verify_identity returns a secret question, read it verbatim and collect the answer. "
+    "NEVER claim the customer is verified unless the verify_identity tool returned verified=true. If not verified, ask ONLY for the next missing field and call verify_identity again. Do NOT proceed to wire details until verified=true. "
+    "IMPORTANT: Once verified=true is returned from verify_identity, DO NOT ask for identity verification again. The customer is verified for the entire session. Proceed directly to OTP verification when ready to execute the transfer. "
+    "AFTER VERIFIED: Ask ONE question at a time, in this order, waiting for the user's answer each time: (1) wire type (DOMESTIC or INTERNATIONAL); (2) source account (last-4 or picker); (3) amount (with source currency); (4) destination country/state; (5) destination currency preference; (6) who pays fees (OUR/SHA/BEN). Keep each turn to a single, concise prompt. Do NOT re-ask for fields already provided; instead, briefly summarize known details and ask only for the next missing field. "
+    "If destination currency differs from source, call get_exchange_rate_tool and state the applied rate and converted amount. "
+    "Collect beneficiary details next. Use get_country_requirements_tool and validate_beneficiary_tool; if fields are missing, ask for ONLY the next missing field (one per turn). "
+    "Then check balance/limits via get_account_balance_tool and check_wire_limits_tool. Provide a pre-transfer quote using quote_wire_tool showing: FX rate, total fees, who pays what, net sent, net received, and ETA from get_cutoff_and_eta_tool. "
+    "Before executing, generate an OTP (generate_otp_tool), collect it, verify via verify_otp_tool, then execute the appropriate transfer: wire_transfer_domestic or wire_transfer_international. Offer to save the beneficiary afterward. "
+    "STYLE: Keep messages short (1–2 sentences), empathetic, and strictly ask one question per turn. "
+    "TTS SAFETY: Output must be plain text suitable for text-to-speech. Do not use markdown, bullets, asterisks, emojis, or special typography. Use only ASCII punctuation and straight quotes."
+)
+
+
+_MODEL_NAME = os.getenv("REACT_MODEL", os.getenv("CLARIFY_MODEL", "gpt-4o"))
+_LLM = ChatOpenAI(model=_MODEL_NAME, temperature=0.3)
+_TOOLS = [
+    list_accounts,
+    get_customer_profile,
+    find_customer,
+    find_account_by_last4,
+    verify_identity,
+    get_account_balance_tool,
+    get_exchange_rate_tool,
+    calculate_wire_fee_tool,
+    check_wire_limits_tool,
+    get_cutoff_and_eta_tool,
+    get_country_requirements_tool,
+    validate_beneficiary_tool,
+    save_beneficiary_tool,
+    quote_wire_tool,
+    generate_otp_tool,
+    verify_otp_tool,
+    wire_transfer_domestic,
+    wire_transfer_international,
+]
+_LLM_WITH_TOOLS = _LLM.bind_tools(_TOOLS)
+_TOOLS_BY_NAME = {t.name: t for t in _TOOLS}
+
+# Simple per-run context storage (thread-safe enough for local dev worker)
+_CURRENT_THREAD_ID: str | None = None
+_CURRENT_CUSTOMER_ID: str | None = None
+
+# ---- Logger ----
+logger = logging.getLogger("WireTransferAgent")
+if not logger.handlers:
+    _stream = logging.StreamHandler()
+    _stream.setLevel(logging.INFO)
+    _fmt = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    _stream.setFormatter(_fmt)
+    logger.addHandler(_stream)
+    try:
+        _file = logging.FileHandler(str(Path(__file__).resolve().parents[2] / "app.log"))
+        _file.setLevel(logging.INFO)
+        _file.setFormatter(_fmt)
+        logger.addHandler(_file)
+    except Exception:
+        pass
+logger.setLevel(logging.INFO)
+_DEBUG = os.getenv("RBC_FEES_DEBUG", "0") not in ("", "0", "false", "False")
+
+def _get_thread_id(config: Dict[str, Any] | None, messages: List[BaseMessage]) -> str:
+    cfg = config or {}
+    # Try dict-like and attribute-like access
+    def _safe_get(container: Any, key: str, default: Any = None) -> Any:
+        try:
+            if isinstance(container, dict):
+                return container.get(key, default)
+            if hasattr(container, "get"):
+                return container.get(key, default)
+            if hasattr(container, key):
+                return getattr(container, key, default)
+        except Exception:
+            return default
+        return default
+
+    try:
+        conf = _safe_get(cfg, "configurable", {}) or {}
+        for key in ("thread_id", "session_id", "thread"):
+            val = _safe_get(conf, key)
+            if isinstance(val, str) and val:
+                return val
+    except Exception:
+        pass
+
+    # Fallback: look for session_id on the latest human message additional_kwargs
+    try:
+        for m in reversed(messages or []):
+            addl = getattr(m, "additional_kwargs", None)
+            if isinstance(addl, dict) and isinstance(addl.get("session_id"), str) and addl.get("session_id"):
+                return addl.get("session_id")
+            if isinstance(m, dict):
+                ak = m.get("additional_kwargs") or {}
+                if isinstance(ak, dict) and isinstance(ak.get("session_id"), str) and ak.get("session_id"):
+                    return ak.get("session_id")
+    except Exception:
+        pass
+    return "unknown"
+
+
+def _trim_messages(messages: List[BaseMessage], max_messages: int = 40) -> List[BaseMessage]:
+    if len(messages) <= max_messages:
+        return messages
+    return messages[-max_messages:]
+
+
+def _sanitize_conversation(messages: List[BaseMessage]) -> List[BaseMessage]:
+    """Ensure tool messages only follow an assistant message with tool_calls.
+
+    Drops orphan tool messages that could cause OpenAI 400 errors.
+    """
+    sanitized: List[BaseMessage] = []
+    pending_tool_ids: set[str] | None = None
+    for m in messages:
+        try:
+            if isinstance(m, AIMessage):
+                sanitized.append(m)
+                tool_calls = getattr(m, "tool_calls", None) or []
+                ids: set[str] = set()
+                for tc in tool_calls:
+                    # ToolCall can be mapping-like or object-like
+                    if isinstance(tc, dict):
+                        _id = tc.get("id") or tc.get("tool_call_id")
+                    else:
+                        _id = getattr(tc, "id", None) or getattr(tc, "tool_call_id", None)
+                    if isinstance(_id, str):
+                        ids.add(_id)
+                pending_tool_ids = ids if ids else None
+                continue
+            if isinstance(m, ToolMessage):
+                if pending_tool_ids and isinstance(getattr(m, "tool_call_id", None), str) and m.tool_call_id in pending_tool_ids:
+                    sanitized.append(m)
+                    # keep accepting subsequent tool messages for the same assistant turn
+                    continue
+                # Orphan tool message: drop
+                continue
+            # Any other message resets expectation
+            sanitized.append(m)
+            pending_tool_ids = None
+        except Exception:
+            # On any unexpected shape, include as-is but reset to avoid pairing issues
+            sanitized.append(m)
+            pending_tool_ids = None
+    # Ensure the conversation doesn't start with a ToolMessage
+    while sanitized and isinstance(sanitized[0], ToolMessage):
+        sanitized.pop(0)
+    return sanitized
+
+
+def _today_string() -> str:
+    override = os.getenv("RBC_FEES_TODAY_OVERRIDE")
+    if isinstance(override, str) and override.strip():
+        try:
+            datetime.strptime(override.strip(), "%Y-%m-%d")
+            return override.strip()
+        except Exception:
+            pass
+    return datetime.utcnow().strftime("%Y-%m-%d")
+
+
+def _system_messages() -> List[BaseMessage]:
+    today = _today_string()
+    return [SystemMessage(content=SYSTEM_PROMPT)]
+
+
+@task()
+def call_llm(messages: List[BaseMessage]) -> AIMessage:
+    """LLM decides whether to call a tool or not."""
+    if _DEBUG:
+        try:
+            preview = [f"{getattr(m,'type', getattr(m,'role',''))}:{str(getattr(m,'content', m))[:80]}" for m in messages[-6:]]
+            logger.info("call_llm: messages_count=%s preview=%s", len(messages), preview)
+        except Exception:
+            logger.info("call_llm: messages_count=%s", len(messages))
+    resp = _LLM_WITH_TOOLS.invoke(_system_messages() + messages)
+    try:
+        # Log assistant content or tool calls for visibility
+        tool_calls = getattr(resp, "tool_calls", None) or []
+        if tool_calls:
+            names = []
+            for tc in tool_calls:
+                n = tc.get("name") if isinstance(tc, dict) else getattr(tc, "name", None)
+                if isinstance(n, str):
+                    names.append(n)
+            logger.info("LLM tool_calls: %s", names)
+        else:
+            txt = getattr(resp, "content", "") or ""
+            if isinstance(txt, str) and txt.strip():
+                logger.info("LLM content: %s", (txt if len(txt) <= 500 else (txt[:500] + "…")))
+    except Exception:
+        pass
+    return resp
+
+
+@task()
+def call_tool(tool_call: ToolCall) -> ToolMessage:
+    """Execute a tool call and wrap result in a ToolMessage."""
+    tool = _TOOLS_BY_NAME[tool_call["name"]]
+    args = tool_call.get("args") or {}
+    # Auto-inject session/customer context if missing for identity and other tools
+    if tool.name == "verify_identity":
+        if "session_id" not in args and _CURRENT_THREAD_ID:
+            args["session_id"] = _CURRENT_THREAD_ID
+        if "customer_id" not in args and _CURRENT_CUSTOMER_ID:
+            args["customer_id"] = _CURRENT_CUSTOMER_ID
+    if tool.name == "list_accounts":
+        if "customer_id" not in args and _CURRENT_CUSTOMER_ID:
+            args["customer_id"] = _CURRENT_CUSTOMER_ID
+    # Gate non-identity tools until verified=true
+    try:
+        if tool.name not in ("verify_identity", "find_customer"):
+            # Look back through recent messages for the last verify_identity result
+            # The runtime passes messages separately; we cannot access here, so rely on LLM prompt discipline.
+            # As an extra guard, if the tool is attempting a wire action before identity, return a friendly error.
+            pass
+    except Exception:
+        pass
+    if _DEBUG:
+        try:
+            logger.info("call_tool: name=%s args_keys=%s", tool.name, list(args.keys()))
+        except Exception:
+            logger.info("call_tool: name=%s", tool.name)
+    result = tool.invoke(args)
+    # Ensure string content
+    content = result if isinstance(result, str) else json.dumps(result)
+    try:
+        # Log tool result previews and OTP debug_code when present
+        if tool.name == "verify_identity":
+            try:
+                data = json.loads(content)
+                logger.info("verify_identity: verified=%s needs=%s", data.get("verified"), data.get("needs"))
+            except Exception:
+                logger.info("verify_identity result: %s", content[:300])
+        elif tool.name == "generate_otp_tool":
+            try:
+                data = json.loads(content)
+                if isinstance(data, dict) and data.get("debug_code"):
+                    logger.info("OTP debug_code: %s", data.get("debug_code"))
+                else:
+                    logger.info("generate_otp_tool: %s", content[:300])
+            except Exception:
+                logger.info("generate_otp_tool: %s", content[:300])
+        else:
+            # Generic preview
+            logger.info("tool %s result: %s", tool.name, (content[:300] if isinstance(content, str) else str(content)[:300]))
+    except Exception:
+        pass
+    # Never expose OTP debug_code to the LLM
+    try:
+        if tool.name == "generate_otp_tool":
+            data = json.loads(content)
+            if isinstance(data, dict) and "debug_code" in data:
+                data.pop("debug_code", None)
+                content = json.dumps(data)
+    except Exception:
+        pass
+    return ToolMessage(content=content, tool_call_id=tool_call["id"], name=tool.name)
+
+
+@entrypoint()
+def agent(messages: List[BaseMessage], previous: List[BaseMessage] | None, config: Dict[str, Any] | None = None):
+    # Start from full conversation history (previous + new)
+    prev_list = list(previous or [])
+    new_list = list(messages or [])
+    convo: List[BaseMessage] = prev_list + new_list
+    # Trim to avoid context bloat
+    convo = _trim_messages(convo, max_messages=int(os.getenv("RBC_FEES_MAX_MSGS", "40")))
+    # Sanitize to avoid orphan tool messages after trimming
+    convo = _sanitize_conversation(convo)
+    thread_id = _get_thread_id(config, new_list)
+    logger.info("agent start: thread_id=%s total_in=%s (prev=%s, new=%s)", thread_id, len(convo), len(prev_list), len(new_list))
+    # Establish default customer from config (or fallback to cust_test)
+    conf = (config or {}).get("configurable", {}) if isinstance(config, dict) else {}
+    default_customer = conf.get("customer_id") or conf.get("user_email") or "cust_test"
+
+    # Heuristic: infer customer_id from latest human name if provided (e.g., "I am Alice Stone")
+    inferred_customer: str | None = None
+    try:
+        recent_humans = [m for m in reversed(new_list) if (getattr(m, "type", None) == "human" or getattr(m, "role", None) == "user" or (isinstance(m, dict) and m.get("type") == "human"))]
+        text = None
+        for m in recent_humans[:3]:
+            text = (getattr(m, "content", None) if not isinstance(m, dict) else m.get("content")) or ""
+            if isinstance(text, str) and text.strip():
+                break
+        if isinstance(text, str):
+            tokens = [t for t in text.replace(',', ' ').split() if t.isalpha()]
+            if len(tokens) >= 2 and find_customer_by_name is not None:
+                # Try adjacent pairs as first/last
+                for i in range(len(tokens) - 1):
+                    fn = tokens[i]
+                    ln = tokens[i + 1]
+                    found = find_customer_by_name(fn, ln)  # type: ignore
+                    if isinstance(found, dict) and found.get("customer_id"):
+                        inferred_customer = found.get("customer_id")
+                        break
+    except Exception:
+        pass
+
+    # Update module context
+    global _CURRENT_THREAD_ID, _CURRENT_CUSTOMER_ID
+    _CURRENT_THREAD_ID = thread_id
+    _CURRENT_CUSTOMER_ID = inferred_customer or default_customer
+
+    llm_response = call_llm(convo).result()
+
+    while True:
+        tool_calls = getattr(llm_response, "tool_calls", None) or []
+        if not tool_calls:
+            break
+
+        # Execute tools (in parallel) and append results
+        futures = [call_tool(tc) for tc in tool_calls]
+        tool_results = [f.result() for f in futures]
+        if _DEBUG:
+            try:
+                logger.info("tool_results: count=%s names=%s", len(tool_results), [tr.name for tr in tool_results])
+            except Exception:
+                pass
+        convo = add_messages(convo, [llm_response, *tool_results])
+        llm_response = call_llm(convo).result()
+
+    # Append final assistant turn
+    convo = add_messages(convo, [llm_response])
+    final_text = getattr(llm_response, "content", "") or ""
+    try:
+        if isinstance(final_text, str) and final_text.strip():
+            logger.info("final content: %s", (final_text if len(final_text) <= 500 else (final_text[:500] + "…")))
+    except Exception:
+        pass
+    ai = AIMessage(content=final_text if isinstance(final_text, str) else str(final_text))
+    logger.info("agent done: thread_id=%s total_messages=%s final_len=%s", thread_id, len(convo), len(ai.content))
+    # Save only the merged conversation (avoid duplicating previous)
+    return entrypoint.final(value=ai, save=convo)
+
+

examples/voice_agent_multi_thread/agents/wire-transfer-agent-multi/tools.py

@@ -0,0 +1,167 @@
+import os
+import sys
+import json
+from typing import Any, Dict
+
+from langchain_core.tools import tool
+
+# Robust logic import to avoid crossing into other agent modules during hot reloads
+try:
+    from . import logic as wt_logic  # type: ignore
+except Exception:
+    import importlib.util as _ilu
+    _dir = os.path.dirname(__file__)
+    _logic_path = os.path.join(_dir, "logic.py")
+    _spec = _ilu.spec_from_file_location("wire_transfer_agent_logic", _logic_path)
+    wt_logic = _ilu.module_from_spec(_spec)  # type: ignore
+    assert _spec and _spec.loader
+    _spec.loader.exec_module(wt_logic)  # type: ignore
+
+get_accounts = wt_logic.get_accounts
+get_profile = wt_logic.get_profile
+find_customer_by_name = wt_logic.find_customer_by_name
+find_customer_by_full_name = getattr(wt_logic, "find_customer_by_full_name", wt_logic.find_customer_by_name)
+get_account_balance = wt_logic.get_account_balance
+get_exchange_rate = wt_logic.get_exchange_rate
+calculate_wire_fee = wt_logic.calculate_wire_fee
+check_wire_limits = wt_logic.check_wire_limits
+get_cutoff_and_eta = wt_logic.get_cutoff_and_eta
+get_country_requirements = wt_logic.get_country_requirements
+validate_beneficiary = wt_logic.validate_beneficiary
+save_beneficiary = wt_logic.save_beneficiary
+generate_otp = wt_logic.generate_otp
+verify_otp = wt_logic.verify_otp
+authenticate_user_wire = wt_logic.authenticate_user_wire
+quote_wire = wt_logic.quote_wire
+wire_transfer_domestic_logic = wt_logic.wire_transfer_domestic
+wire_transfer_international_logic = wt_logic.wire_transfer_international
+
+
+@tool
+def list_accounts(customer_id: str) -> str:
+    """List customer's accounts with masked numbers, balances, currency, and wire eligibility. Returns JSON string."""
+    return json.dumps(get_accounts(customer_id))
+
+
+@tool
+def get_customer_profile(customer_id: str) -> str:
+    """Fetch basic customer profile (full_name, dob, ssn_last4, secret question). Returns JSON string."""
+    return json.dumps(get_profile(customer_id))
+
+
+@tool
+def find_customer(first_name: str | None = None, last_name: str | None = None, full_name: str | None = None) -> str:
+    """Find a customer_id by name. Prefer full_name; otherwise use first and last name. Returns JSON with customer_id or {}."""
+    if isinstance(full_name, str) and full_name.strip():
+        return json.dumps(find_customer_by_full_name(full_name))
+    return json.dumps(find_customer_by_name(first_name or "", last_name or ""))
+
+
+@tool
+def find_account_by_last4(customer_id: str, last4: str) -> str:
+    """Find a customer's account by last 4 digits. Returns JSON with account or {} if not found."""
+    accts = get_accounts(customer_id)
+    for a in accts:
+        num = str(a.get("account_number") or "")
+        if num.endswith(str(last4)):
+            return json.dumps(a)
+    return json.dumps({})
+
+
+@tool
+def verify_identity(session_id: str, customer_id: str | None = None, full_name: str | None = None, dob_yyyy_mm_dd: str | None = None, ssn_last4: str | None = None, secret_answer: str | None = None) -> str:
+    """Verify user identity before wires. Provide any of: full_name, dob (YYYY-MM-DD), ssn_last4, secret_answer. Returns JSON with verified flag, needed fields, and optional secret question."""
+    res = authenticate_user_wire(session_id, customer_id, full_name, dob_yyyy_mm_dd, ssn_last4, secret_answer)
+    return json.dumps(res)
+
+
+@tool
+def get_account_balance_tool(account_id: str) -> str:
+    """Get balance, currency, and wire limits for an account. Returns JSON."""
+    return json.dumps(get_account_balance(account_id))
+
+
+@tool
+def get_exchange_rate_tool(from_currency: str, to_currency: str, amount: float) -> str:
+    """Get exchange rate and converted amount for a given amount. Returns JSON."""
+    return json.dumps(get_exchange_rate(from_currency, to_currency, amount))
+
+
+@tool
+def calculate_wire_fee_tool(kind: str, amount: float, from_currency: str, to_currency: str, payer: str) -> str:
+    """Calculate wire fee breakdown and who pays (OUR/SHA/BEN). Returns JSON."""
+    return json.dumps(calculate_wire_fee(kind, amount, from_currency, to_currency, payer))
+
+
+@tool
+def check_wire_limits_tool(account_id: str, amount: float) -> str:
+    """Check sufficient funds and daily wire limit on an account. Returns JSON."""
+    return json.dumps(check_wire_limits(account_id, amount))
+
+
+@tool
+def get_cutoff_and_eta_tool(kind: str, country: str) -> str:
+    """Get cutoff time and estimated arrival window by type and country. Returns JSON."""
+    return json.dumps(get_cutoff_and_eta(kind, country))
+
+
+@tool
+def get_country_requirements_tool(country_code: str) -> str:
+    """Get required beneficiary fields for a country. Returns JSON array."""
+    return json.dumps(get_country_requirements(country_code))
+
+
+@tool
+def validate_beneficiary_tool(country_code: str, beneficiary_json: str) -> str:
+    """Validate beneficiary fields for a given country. Input is JSON dict string; returns {ok, missing}."""
+    try:
+        beneficiary = json.loads(beneficiary_json)
+    except Exception:
+        beneficiary = {}
+    return json.dumps(validate_beneficiary(country_code, beneficiary))
+
+
+@tool
+def save_beneficiary_tool(customer_id: str, beneficiary_json: str) -> str:
+    """Save a beneficiary for future use. Input is JSON dict string; returns {beneficiary_id}."""
+    try:
+        beneficiary = json.loads(beneficiary_json)
+    except Exception:
+        beneficiary = {}
+    return json.dumps(save_beneficiary(customer_id, beneficiary))
+
+
+@tool
+def quote_wire_tool(kind: str, from_account_id: str, beneficiary_json: str, amount: float, from_currency: str, to_currency: str, payer: str) -> str:
+    """Create a wire quote including FX, fees, limits, sanctions, eta; returns JSON with quote_id and totals."""
+    try:
+        beneficiary = json.loads(beneficiary_json)
+    except Exception:
+        beneficiary = {}
+    return json.dumps(quote_wire(kind, from_account_id, beneficiary, amount, from_currency, to_currency, payer))
+
+
+@tool
+def generate_otp_tool(customer_id: str) -> str:
+    """Generate a one-time passcode for wire authorization. Returns masked destination info."""
+    return json.dumps(generate_otp(customer_id))
+
+
+@tool
+def verify_otp_tool(customer_id: str, otp: str) -> str:
+    """Verify the one-time passcode for wire authorization. Returns {verified}."""
+    return json.dumps(verify_otp(customer_id, otp))
+
+
+@tool
+def wire_transfer_domestic(quote_id: str, otp: str) -> str:
+    """Execute a domestic wire with a valid quote_id and OTP. Returns confirmation."""
+    return json.dumps(wire_transfer_domestic_logic(quote_id, otp))
+
+
+@tool
+def wire_transfer_international(quote_id: str, otp: str) -> str:
+    """Execute an international wire with a valid quote_id and OTP. Returns confirmation."""
+    return json.dumps(wire_transfer_international_logic(quote_id, otp))
+
+

examples/voice_agent_multi_thread/docker-compose.yml

@@ -0,0 +1,49 @@
+name: voice-agents-webrtc-langgraph
+
+services:
+  python-app:
+    build:
+      context: ../../
+      dockerfile: examples/voice_agent_webrtc_langgraph/Dockerfile
+    ports:
+      - "9000:9000"   # UI static server
+      - "7860:7860"   # Pipeline API/WebSocket
+      - "2024:2024"   # LangGraph dev (optional external access)
+    volumes:
+      - ./audio_dumps:/app/examples/voice_agent_webrtc_langgraph/audio_dumps
+      # - /home/fciannella/src/ace-controller/examples/voice_agent_webrtc_langgraph:/app/examples/voice_agent_webrtc_langgraph/audio_prompt.wav
+      # - /home/fciannella/src/ace-controller-langgraph-agents:/langgraph-agents
+    env_file:
+      - .env
+    environment:
+      - NVIDIA_API_KEY=${NVIDIA_API_KEY}
+      - USE_LANGGRAPH=${USE_LANGGRAPH}
+      - LANGGRAPH_BASE_URL=${LANGGRAPH_BASE_URL}
+      - LANGGRAPH_ASSISTANT=${LANGGRAPH_ASSISTANT}
+      - USER_EMAIL=${USER_EMAIL}
+      - LANGGRAPH_STREAM_MODE=${LANGGRAPH_STREAM_MODE}
+      - LANGGRAPH_DEBUG_STREAM=${LANGGRAPH_DEBUG_STREAM}
+      - LANGGRAPH_PORT=${LANGGRAPH_PORT}
+
+      - RIVA_ASR_LANGUAGE=en-US
+      - RIVA_TTS_LANGUAGE=en-US
+      - RIVA_TTS_VOICE_ID=Magpie-ZeroShot.Female-1
+      - ZERO_SHOT_AUDIO_PROMPT=/app/examples/voice_agent_webrtc_langgraph/audio_prompt.wav # set this only if using a zero-shot TTS model with a custom audio prompt
+      - ENABLE_SPECULATIVE_SPEECH=true # set to false to disable speculative speech processing
+
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:7860/get_prompt || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "50m"
+        max-file: "5"
+
+volumes:
+  nim_cache:
+  riva_data:

examples/voice_agent_multi_thread/env.example

@@ -0,0 +1,9 @@
+NVIDIA_API_KEY=nvapi-
+ZEROSHOT_TTS_NVIDIA_API_KEY=nvapi-
+RIVA_API_KEY=nvapi-
+USE_LANGGRAPH=true
+LANGGRAPH_BASE_URL=http://127.0.0.1:2024
+LANGGRAPH_ASSISTANT=ace-base-agent
+USER_EMAIL=test@example.com
+LANGGRAPH_STREAM_MODE=values
+LANGGRAPH_DEBUG_STREAM=true

examples/voice_agent_multi_thread/index.html

@@ -0,0 +1,154 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>WebRTC Voice Agent</title>
+    <style>
+        body { font-family: Arial, sans-serif; text-align: center; margin-top: 50px; }
+        #status { font-size: 20px; margin: 20px; }
+        button { padding: 10px 20px; font-size: 16px; }
+    </style>
+</head>
+<body>
+    <h1>WebRTC Voice Agent</h1>
+    <p id="status">Disconnected</p>
+    <button id="connect-btn">Connect</button>
+    <audio id="audio-el" autoplay></audio>
+
+    <script>
+        const statusEl = document.getElementById("status")
+        const buttonEl = document.getElementById("connect-btn")
+        const audioEl = document.getElementById("audio-el")
+
+        let connected = false
+        let peerConnection = null
+
+        const waitForIceGatheringComplete = async (pc, timeoutMs = 2000) => {
+            if (pc.iceGatheringState === 'complete') return;
+            console.log("Waiting for ICE gathering to complete. Current state:", pc.iceGatheringState);
+            return new Promise((resolve) => {
+                let timeoutId;
+                const checkState = () => {
+                    console.log("icegatheringstatechange:", pc.iceGatheringState);
+                    if (pc.iceGatheringState === 'complete') {
+                        cleanup();
+                        resolve();
+                    }
+                };
+                const onTimeout = () => {
+                    console.warn(`ICE gathering timed out after ${timeoutMs} ms.`);
+                    cleanup();
+                    resolve();
+                };
+                const cleanup = () => {
+                    pc.removeEventListener('icegatheringstatechange', checkState);
+                    clearTimeout(timeoutId);
+                };
+                pc.addEventListener('icegatheringstatechange', checkState);
+                timeoutId = setTimeout(onTimeout, timeoutMs);
+                // Checking the state again to avoid any eventual race condition
+                checkState();
+            });
+        };
+
+
+        const createSmallWebRTCConnection = async (audioTrack) => {
+            const config = {
+              iceServers: [],
+            };
+            const pc = new RTCPeerConnection(config)
+            addPeerConnectionEventListeners(pc)
+            pc.ontrack = e => audioEl.srcObject = e.streams[0]
+            // SmallWebRTCTransport expects to receive both transceivers
+            pc.addTransceiver(audioTrack, { direction: 'sendrecv' })
+            pc.addTransceiver('video', { direction: 'sendrecv' })
+            await pc.setLocalDescription(await pc.createOffer())
+            await waitForIceGatheringComplete(pc)
+            const offer = pc.localDescription
+            try {
+                const response = await fetch('/api/offer', {
+                    body: JSON.stringify({ sdp: offer.sdp, type: offer.type}),
+                    headers: { 'Content-Type': 'application/json' },
+                    method: 'POST',
+                });
+                
+                if (!response.ok) {
+                    throw new Error(`HTTP error! status: ${response.status}`);
+                }
+                
+                const answer = await response.json()
+                await pc.setRemoteDescription(answer)
+            } catch (error) {
+                console.error('Error during WebRTC connection setup:', error);
+                _onDisconnected();
+                throw error;
+            }
+            return pc
+        }
+
+        const connect = async () => {
+            _onConnecting()
+            const audioStream = await navigator.mediaDevices.getUserMedia({audio: true})
+            peerConnection= await createSmallWebRTCConnection(audioStream.getAudioTracks()[0])
+        }
+
+        const addPeerConnectionEventListeners = (pc) => {
+            pc.oniceconnectionstatechange = () => {
+                console.log("oniceconnectionstatechange", pc?.iceConnectionState)
+            }
+            pc.onconnectionstatechange = () => {
+                console.log("onconnectionstatechange", pc?.connectionState)
+                let connectionState = pc?.connectionState
+                if (connectionState === 'connected') {
+                    _onConnected()
+                } else if (connectionState === 'disconnected') {
+                    _onDisconnected()
+                }
+            }
+            pc.onicecandidate = (event) => {
+                if (event.candidate) {
+                    console.log("New ICE candidate:", event.candidate);
+                } else {
+                    console.log("All ICE candidates have been sent.");
+                }
+            };
+        }
+
+        const _onConnecting = () => {
+            statusEl.textContent = "Connecting"
+            buttonEl.textContent = "Disconnect"
+            connected = true
+        }
+
+        const _onConnected = () => {
+            statusEl.textContent = "Connected"
+            buttonEl.textContent = "Disconnect"
+            connected = true
+        }
+
+        const _onDisconnected = () => {
+            statusEl.textContent = "Disconnected"
+            buttonEl.textContent = "Connect"
+            connected = false
+        }
+
+        const disconnect = () => {
+            if (!peerConnection) {
+                return
+            }
+            peerConnection.close()
+            peerConnection = null
+            _onDisconnected()
+        }
+
+        buttonEl.addEventListener("click", async () => {
+            if (!connected) {
+                await connect()
+            } else {
+                disconnect()
+            }
+        });
+    </script>
+</body>
+</html>

examples/voice_agent_multi_thread/ipa.json

@@ -0,0 +1,121 @@
+{
+    "NVIDIA": "ˈɛnˌvɪdiə",
+    "Riva": "ˈriːvə",
+    "Parakeet": "ˈpærəˌkiːt",
+    "Canary": "kəˈnɛri",
+    "Magpie": "ˈmæɡˌpaɪ",
+    "Llama": "ˈlɑːmə",
+    "Nemotron": "ˈniːmoʊˌtrɒn",
+    "TTS": "ˌtiːˌtiːˈɛs",
+    "ASR": "ˌeɪˌɛsˈɑːr",
+    "GPU": "ˌdʒiːˌpiːˈjuː",
+    "RTX": "ɑːrˌtiːˈɛks",
+    "A100": "eɪ wʌn ˈhʌndrəd",
+    "H100": "eɪtʃ wʌn ˈhʌndrəd",
+    "Blackwell": "ˈblækwɛl",
+    "Grace Hopper": "ˈɡreɪs ˈhɒpər",
+    "DLI": "ˌdiːˌɛlˈaɪ",
+    "DGX": "ˌdiːˌdʒiːˈɛks",
+    "Omniverse": "ˈɑːmnɪˌvɜːrs",
+    "Jetson": "ˈdʒɛtsən",
+    "TensorRT": "ˈtɛnsər ɑːrˈtiː",
+    "CUDA": "ˈkuːdə",
+    "RAG": "ræɡ",
+    "NIM": "nɪm",
+    "ACE": "eɪs",
+    "NeMo": "ˈniːmoʊ",
+    "Nemo Guardrails": "ˈniːmoʊ ˈɡɑːrdˌreɪlz",
+    "Helm": "hɛlm",
+    "Kubernetes": "ˌkuːbərˈnetiːz",
+    "Docker": "ˈdɒkər",
+    "API": "ˌeɪˌpiːˈaɪ",
+    "SDK": "ˌɛsˌdiːˈkeɪ",
+    "NGC": "ˌɛnˌdʒiːˈsiː",
+    "CUDA Core": "ˈkuːdə kɔːr",
+    "Inference": "ˈɪnfərəns",
+    "Riva NIM": "ˈriːvə nɪm",
+    "RIVA API": "ˈriːvə ˌeɪˌpiːˈaɪ",
+    "Riva Canary": "ˈriːvə kəˈnɛri",
+    "FastPitch": "ˈfæstˌpɪtʃ",
+    "CTC": "ˌsiːˌtiːˈsiː",
+    "RNNT": "ˌɑːrˌɛnˌɛnˈtiː",
+    "TDT": "ˌtiːˌdiːˈtiː",
+    "Adi": "ˈɑːdi",
+    "Julie": "ˈdʒuːli",
+    "Ryan": "ˈraɪən",
+    "Ankit": "ˈæŋkɪt",
+    "Priya": "ˈpriːjɑː",
+    "Sanjay": "ˈsɑːndʒeɪ",
+    "Wei": "weɪ",
+    "Jing": "dʒɪŋ",
+    "Elena": "ɛˈleɪnə",
+    "Ivan": "ˈiːvɑːn",
+    "Monica": "ˈmɒnɪkə",
+    "bouquet": "buˈkeɪ",
+    "delivery": "dɪˈlɪvəri",
+    "vase": "veɪs",
+    "greenery": "ˈgriːnəri",
+    "foliage": "ˈfoʊliɪdʒ",
+    "eucalyptus": "ˌjuːkəˈlɪptəs",
+    "orchid": "ˈɔːrkɪd",
+    "succulent": "ˈsʌkjələnt",
+    "fern": "fɜːrn",
+    "hydrangea": "haɪˈdreɪndʒə",
+    "rose": "roʊz",
+    "sunflower": "ˈsʌnˌflaʊər",
+    "lily": "ˈlɪli",
+    "tulip": "ˈtuːlɪp",
+    "peony": "ˈpiːəni",
+    "carnation": "kɑːrˈneɪʃən",
+    "daisy": "ˈdeɪzi",
+    "chrysanthemum": "krɪˈzænθəməm",
+    "snapdragon": "ˈsnæpˌdræɡən",
+    "alstroemeria": "ælstroʊˈmiːriə",
+    "freesia": "ˈfriːʒə",
+    "marigold": "ˈmærɪˌɡoʊld",
+    "anthurium": "ænˈθjʊriəm",
+    "camellia": "kəˈmiːliə",
+    "greens": "griːnz",
+    "hypericum": "haɪˈpɛrɪkəm",
+    "NVIDIA headquarters": "ɛnˌvɪdiə ˈhɛd.kwɔːrtərz",
+    "Santa Clara": "ˌsæntə ˈklærə",
+    "California": "ˌkælɪˈfɔːrnɪə",
+    "Silicon Valley": "ˈsɪlɪkən ˈvæli",
+    "Building E": "ˈbɪldɪŋ iː",
+    "Endeavor": "ˈɛndɪˌvər",
+    "NVIDIA green": "ɛnˌvɪdiə ɡriːn",
+    "lime green": "laɪm ɡriːn",
+    "emerald": "ˈɛmərəld",
+    "moss green": "mɒs ɡriːn",
+    "forest green": "ˈfɒrɪst ɡriːn",
+    "chartreuse": "ʃɑːrˈtruːs",
+    "gift card": "ɡɪft kɑːrd",
+    "credit card": "ˈkrɛdɪt kɑːrd",
+    "Visa": "ˈviːzə",
+    "Mastercard": "ˈmæstərˌkɑːrd",
+    "Amex": "ˈæmɛks",
+    "PayPal": "ˈpeɪˌpæl",
+    "Apple Pay": "ˈæpəl peɪ",
+    "confirmation email": "͵kɒnfəˈmeɪʃən ˈiːˌmeɪl",
+    "AI": "ˌeɪˈaɪ",
+    "cloud": "klaʊd",
+    "audio": "ˈɔːdiˌoʊ",
+    "speech": "spiːtʃ",
+    "model": "ˈmɒdl̩",
+    "LLM": "ˌɛlˌɛlˈɛm",
+    "API key": "ˌeɪˌpiːˈaɪ kiː",
+    "voice agent": "vɔɪs ˈeɪdʒənt",
+    "Flora": "ˈflɔːrə",
+    "assistant": "əˈsɪstənt",
+    "flower bot": "ˈflaʊər bɑːt",
+    "voice demo": "vɔɪs ˈdɛmoʊ",
+    "Have a green day": "ˈhæv ə ɡriːn deɪ",
+    "blooms": "bluːmz",
+    "NVIDIA swag": "ɛnˌvɪdiə swæɡ",
+    "limited edition": "ˈlɪmɪtɪd ɪˈdɪʃən",
+    "coupon": "ˈkuːˌpɒn",
+    "gift wrap": "ɡɪft ræp",
+    "email": "ˈiːˌmeɪl",
+    "phone number": "foʊn ˈnʌmbər",
+    "pickup": "ˈpɪkˌʌp"
+}

examples/voice_agent_multi_thread/langgraph_llm_service.py

@@ -0,0 +1,432 @@
+"""LangGraph-backed LLM service for Pipecat pipelines.
+
+This service adapts a running LangGraph agent (accessed via langgraph-sdk)
+to Pipecat's frame-based processing model. It consumes `OpenAILLMContextFrame`
+or `LLMMessagesFrame` inputs, extracts the latest user message (using the
+LangGraph server's thread to persist history), and streams assistant tokens
+back as `LLMTextFrame` until completion.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Optional
+import os
+from dotenv import load_dotenv
+
+from langgraph_sdk import get_client
+from langchain_core.messages import HumanMessage
+from loguru import logger
+from pipecat.frames.frames import (
+    Frame,
+    LLMFullResponseEndFrame,
+    LLMFullResponseStartFrame,
+    LLMMessagesFrame,
+    LLMTextFrame,
+    StartInterruptionFrame,
+    VisionImageRawFrame,
+)
+from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext, OpenAILLMContextFrame
+from pipecat.processors.frame_processor import FrameDirection
+from pipecat.services.openai.llm import OpenAILLMService
+
+
+load_dotenv()
+
+# TTS sanitize helper: normalize curly quotes/dashes and non-breaking spaces to ASCII
+def _tts_sanitize(text: str) -> str:
+    try:
+        if not isinstance(text, str):
+            text = str(text)
+        replacements = {
+            "\u2018": "'",  # left single quote
+            "\u2019": "'",  # right single quote / apostrophe
+            "\u201C": '"',   # left double quote
+            "\u201D": '"',   # right double quote
+            "\u00AB": '"',   # left angle quote
+            "\u00BB": '"',   # right angle quote
+            "\u2013": "-",  # en dash
+            "\u2014": "-",  # em dash
+            "\u2026": "...",# ellipsis
+            "\u00A0": " ",  # non-breaking space
+            "\u202F": " ",  # narrow no-break space
+        }
+        for k, v in replacements.items():
+            text = text.replace(k, v)
+        return text
+    except Exception:
+        return text
+
+class LangGraphLLMService(OpenAILLMService):
+    """Pipecat LLM service that delegates responses to a LangGraph agent.
+
+    Attributes:
+        base_url: LangGraph API base URL, e.g. "http://127.0.0.1:2024".
+        assistant: Assistant name or id registered with the LangGraph server.
+        user_email: Value for `configurable.user_email` (routing / personalization).
+        stream_mode: SDK stream mode ("updates", "values", "messages", "events").
+        debug_stream: When True, logs raw stream events for troubleshooting.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str = "http://127.0.0.1:2024",
+        assistant: str = "ace-base-agent",
+        user_email: str = "test@example.com",
+        stream_mode: str = "values",
+        debug_stream: bool = False,
+        thread_id: Optional[str] = None,
+        auth_token: Optional[str] = None,
+        enable_multi_threading: bool = True,  # Enable multi-threaded routing
+        **kwargs: Any,
+    ) -> None:
+        # Initialize base class; OpenAI settings unused but required by parent
+        super().__init__(api_key="", **kwargs)
+        self.base_url = base_url
+        self.assistant = assistant
+        self.user_email = user_email
+        self.stream_mode = stream_mode
+        self.debug_stream = debug_stream
+        self.enable_multi_threading = enable_multi_threading
+
+        # Optional auth header
+        token = (
+            auth_token
+            or os.getenv("LANGGRAPH_AUTH_TOKEN")
+            or os.getenv("AUTH0_ACCESS_TOKEN")
+            or os.getenv("AUTH_BEARER_TOKEN")
+        )
+
+        headers = {"Authorization": f"Bearer {token}"} if isinstance(token, str) and token else None
+        self._client = get_client(url=self.base_url, headers=headers) if headers else get_client(url=self.base_url)
+        
+        # Multi-threading: maintain separate threads for main and secondary
+        self._thread_id_main: Optional[str] = thread_id
+        self._thread_id_secondary: Optional[str] = None
+        self._thread_id: Optional[str] = thread_id  # Backward compatibility
+        
+        # Namespace for store coordination - sanitize email (periods not allowed)
+        sanitized_email = self.user_email.replace(".", "_").replace("@", "_at_")
+        self._namespace_for_memory: tuple[str, str] = (sanitized_email, "tools_updates")
+        
+        # Track interim message reset state
+        self._interim_messages_reset: bool = True
+        self._last_was_long_operation: bool = False
+        
+        self._current_task: Optional[asyncio.Task] = None
+        self._outer_open: bool = False
+        self._emitted_texts: set[str] = set()
+
+    async def _ensure_thread(self, thread_type: str = "main") -> Optional[str]:
+        """Ensure thread exists for the given type (main or secondary)."""
+        if thread_type == "main":
+            if self._thread_id_main:
+                return self._thread_id_main
+        else:
+            if self._thread_id_secondary:
+                return self._thread_id_secondary
+        
+        try:
+            thread = await self._client.threads.create()
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(f"LangGraph: failed to create {thread_type} thread; proceeding threadless. Error: {exc}")
+            return None
+
+        thread_id = getattr(thread, "thread_id", None)
+        if thread_id is None and isinstance(thread, dict):
+            thread_id = thread.get("thread_id") or thread.get("id")
+        if thread_id is None:
+            thread_id = getattr(thread, "id", None)
+        
+        if isinstance(thread_id, str) and thread_id:
+            if thread_type == "main":
+                self._thread_id_main = thread_id
+                self._thread_id = thread_id  # Backward compatibility
+            else:
+                self._thread_id_secondary = thread_id
+            logger.info(f"Created {thread_type} thread: {thread_id}")
+            return thread_id
+        else:
+            logger.warning(f"LangGraph: could not determine {thread_type} thread id; proceeding threadless.")
+            return None
+
+    async def _check_long_operation_running(self) -> bool:
+        """Check if a long operation is currently running via the store."""
+        if not self.enable_multi_threading:
+            logger.info("Multi-threading disabled, returning False")
+            return False
+        
+        try:
+            ns_list = list(self._namespace_for_memory)
+            logger.info(f"Checking store with namespace: {ns_list}")
+            
+            # Get the specific status key that tools write to
+            item = await self._client.store.get_item(ns_list, "working-tool-status-update")
+            
+            if item is None:
+                logger.info("No item found in store, returning False")
+                return False
+            
+            # Extract value from the item
+            value = getattr(item, "value", None)
+            if value is None and isinstance(item, dict):
+                value = item.get("value")
+            
+            # Check if status is "running"
+            if isinstance(value, dict):
+                status = value.get("status")
+                logger.info(f"🔍 Long operation check: status={status}, tool={value.get('tool_name')}, progress={value.get('progress')}")
+                return status == "running"
+            
+            logger.info(f"Value not a dict: {type(value)}")
+            return False
+        except Exception as exc:  # noqa: BLE001
+            logger.error(f"❌ Failed to check operation status: {exc}", exc_info=True)
+            return False
+
+    @staticmethod
+    def _extract_latest_user_text(context: OpenAILLMContext) -> str:
+        """Return the latest user (or fallback system) message content.
+
+        The LangGraph server maintains history via threads, so we only need to
+        send the current turn text. Prefer the latest user message; if absent,
+        fall back to the latest system message so system-only kickoffs can work.
+        """
+        messages = context.get_messages() or []
+        for msg in reversed(messages):
+            try:
+                if msg.get("role") == "user":
+                    content = msg.get("content", "")
+                    return content if isinstance(content, str) else str(content)
+            except Exception:  # Defensive against unexpected shapes
+                continue
+        # Fallback: use the most recent system message if no user message exists
+        for msg in reversed(messages):
+            try:
+                if msg.get("role") == "system":
+                    content = msg.get("content", "")
+                    return content if isinstance(content, str) else str(content)
+            except Exception:
+                continue
+        return ""
+
+    async def _stream_langgraph(self, text: str) -> None:
+        # Determine thread type based on whether a long operation is running
+        thread_type = "main"
+        if self.enable_multi_threading:
+            long_operation_running = await self._check_long_operation_running()
+            if long_operation_running:
+                thread_type = "secondary"
+                self._interim_messages_reset = False
+                logger.info("Long operation detected, routing to secondary thread")
+            else:
+                # Starting new main operation
+                if self._last_was_long_operation:
+                    self._interim_messages_reset = True
+                    self._last_was_long_operation = False
+                else:
+                    self._interim_messages_reset = True
+                logger.info("No long operation, routing to main thread")
+        
+        # Ensure appropriate thread
+        thread_id = await self._ensure_thread(thread_type)
+        
+        # Build config with namespace for store coordination
+        config = {
+            "configurable": {
+                "user_email": self.user_email,
+                "thread_id": thread_id,
+                "namespace_for_memory": list(self._namespace_for_memory),
+            }
+        }
+        
+        # Build input dict for multi-threaded agent
+        if self.enable_multi_threading:
+            input_payload = {
+                "messages": [{"type": "human", "content": text}],
+                "thread_type": thread_type,
+                "interim_messages_reset": self._interim_messages_reset,
+            }
+        else:
+            # Backward compatible: simple message input
+            input_payload = [HumanMessage(content=text)]
+
+        try:
+            async for chunk in self._client.runs.stream(
+                thread_id,
+                self.assistant,
+                input=input_payload,
+                stream_mode=self.stream_mode,
+                config=config,
+            ):
+                data = getattr(chunk, "data", None)
+                event = getattr(chunk, "event", "") or ""
+
+                if self.debug_stream:
+                    try:
+                        # Short, structured debugging output
+                        dtype = type(data).__name__
+                        preview = ""
+                        if hasattr(data, "content") and isinstance(getattr(data, "content"), str):
+                            c = getattr(data, "content")
+                            preview = c[:120]
+                        elif isinstance(data, dict):
+                            preview = ",".join(list(data.keys())[:6])
+                        logger.debug(f"[LangGraph stream] event={event} data={dtype}:{preview}")
+                    except Exception:  # noqa: BLE001
+                        logger.debug(f"[LangGraph stream] event={event}")
+
+                # Token streaming events (LangChain chat model streaming)
+                if "on_chat_model_stream" in event or event.endswith(".on_chat_model_stream"):
+                    part_text = ""
+                    d = data
+                    if isinstance(d, dict):
+                        if "chunk" in d:
+                            ch = d["chunk"]
+                            part_text = getattr(ch, "content", None) or ""
+                            if not isinstance(part_text, str):
+                                part_text = str(part_text)
+                        elif "delta" in d:
+                            delta = d["delta"]
+                            part_text = getattr(delta, "content", None) or ""
+                            if not isinstance(part_text, str):
+                                part_text = str(part_text)
+                        elif "content" in d and isinstance(d["content"], str):
+                            part_text = d["content"]
+                    else:
+                        part_text = getattr(d, "content", "")
+
+                    if part_text:
+                        if not self._outer_open:
+                            await self.push_frame(LLMFullResponseStartFrame())
+                            self._outer_open = True
+                            self._emitted_texts.clear()
+                        if part_text not in self._emitted_texts:
+                            self._emitted_texts.add(part_text)
+                            await self.push_frame(LLMTextFrame(_tts_sanitize(part_text)))
+
+                # Final value-style events (values mode)
+                if event == "values":
+                    # Some dev servers send final AI message content here
+                    final_text = ""
+                    
+                    # Handle list of messages (most common case)
+                    if isinstance(data, list) and data:
+                        # Find the last AI message in the list
+                        for msg in reversed(data):
+                            if isinstance(msg, dict):
+                                if msg.get("type") == "ai" and isinstance(msg.get("content"), str):
+                                    final_text = msg["content"]
+                                    break
+                            elif hasattr(msg, "type") and getattr(msg, "type") == "ai":
+                                content = getattr(msg, "content", None)
+                                if isinstance(content, str):
+                                    final_text = content
+                                    break
+                    # Handle single message object
+                    elif hasattr(data, "content") and isinstance(getattr(data, "content"), str):
+                        final_text = getattr(data, "content")
+                    # Handle single message dict
+                    elif isinstance(data, dict):
+                        c = data.get("content")
+                        if isinstance(c, str):
+                            final_text = c
+                    
+                    if final_text:
+                        # Close backchannel utterance if open
+                        if self._outer_open:
+                            await self.push_frame(LLMFullResponseEndFrame())
+                            self._outer_open = False
+                            self._emitted_texts.clear()
+                        # Emit final explanation as its own message
+                        await self.push_frame(LLMFullResponseStartFrame())
+                        await self.push_frame(LLMTextFrame(_tts_sanitize(final_text)))
+                        await self.push_frame(LLMFullResponseEndFrame())
+
+                # Messages mode: look for an array of messages
+                if event == "messages" or event.endswith(":messages"):
+                    try:
+                        msgs = None
+                        if isinstance(data, dict):
+                            msgs = data.get("messages") or data.get("result") or data.get("value")
+                        elif hasattr(data, "messages"):
+                            msgs = getattr(data, "messages")
+                        if isinstance(msgs, list) and msgs:
+                            last = msgs[-1]
+                            content = getattr(last, "content", None)
+                            if content is None and isinstance(last, dict):
+                                content = last.get("content")
+                            if isinstance(content, str) and content:
+                                if not self._outer_open:
+                                    await self.push_frame(LLMFullResponseStartFrame())
+                                    self._outer_open = True
+                                    self._emitted_texts.clear()
+                                if content not in self._emitted_texts:
+                                    self._emitted_texts.add(content)
+                                    await self.push_frame(LLMTextFrame(_tts_sanitize(content)))
+                    except Exception as exc:  # noqa: BLE001
+                        logger.debug(f"LangGraph messages parsing error: {exc}")
+                # If payload is a plain string, emit it
+                if isinstance(data, str):
+                    txt = data.strip()
+                    if txt:
+                        if not self._outer_open:
+                            await self.push_frame(LLMFullResponseStartFrame())
+                            self._outer_open = True
+                            self._emitted_texts.clear()
+                        if txt not in self._emitted_texts:
+                            self._emitted_texts.add(txt)
+                            await self.push_frame(LLMTextFrame(_tts_sanitize(txt)))
+        except Exception as exc:  # noqa: BLE001
+            logger.error(f"LangGraph stream error: {exc}")
+
+    async def _process_context_and_frames(self, context: OpenAILLMContext) -> None:
+        """Adapter entrypoint: push start/end frames and stream tokens."""
+        try:
+            # Defer opening until backchannels arrive; final will be emitted separately
+            user_text = self._extract_latest_user_text(context)
+            if not user_text:
+                logger.debug("LangGraph: no user text in context; skipping run.")
+                return
+            self._outer_open = False
+            self._emitted_texts.clear()
+            await self._stream_langgraph(user_text)
+        finally:
+            if self._outer_open:
+                await self.push_frame(LLMFullResponseEndFrame())
+                self._outer_open = False
+
+    async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process pipeline frames, handling interruptions and context inputs."""
+        context: Optional[OpenAILLMContext] = None
+
+        if isinstance(frame, OpenAILLMContextFrame):
+            context = frame.context
+        elif isinstance(frame, LLMMessagesFrame):
+            context = OpenAILLMContext.from_messages(frame.messages)
+        elif isinstance(frame, VisionImageRawFrame):
+            # Not implemented for LangGraph adapter; ignore images
+            context = None
+        elif isinstance(frame, StartInterruptionFrame):
+            # Relay interruption downstream and cancel any active run
+            await self._start_interruption()
+            await self.stop_all_metrics()
+            await self.push_frame(frame, direction)
+            if self._current_task is not None and not self._current_task.done():
+                await self.cancel_task(self._current_task)
+                self._current_task = None
+            return
+        else:
+            await super().process_frame(frame, direction)
+
+        if context is not None:
+            if self._current_task is not None and not self._current_task.done():
+                await self.cancel_task(self._current_task)
+                self._current_task = None
+                logger.debug("LangGraph LLM: canceled previous task")
+
+            self._current_task = self.create_task(self._process_context_and_frames(context))
+            self._current_task.add_done_callback(lambda _: setattr(self, "_current_task", None))
+
+

examples/voice_agent_multi_thread/pipeline.py

@@ -0,0 +1,550 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: BSD 2-Clause License
+
+"""Voice Agent WebRTC Pipeline.
+
+This module implements a voice agent pipeline using WebRTC for real-time
+speech-to-speech communication with dynamic prompt support.
+"""
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+import uuid
+from pathlib import Path
+
+import uvicorn
+from dotenv import load_dotenv
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect, Request
+from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.middleware.cors import CORSMiddleware
+from loguru import logger
+from pipecat.audio.vad.silero import SileroVADAnalyzer
+from pipecat.frames.frames import InputAudioRawFrame, LLMMessagesFrame, TTSAudioRawFrame
+from pipecat.pipeline.pipeline import Pipeline
+from pipecat.pipeline.runner import PipelineRunner
+from pipecat.pipeline.task import PipelineParams, PipelineTask
+from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext
+from pipecat.transports.base_transport import TransportParams
+from pipecat.transports.network.small_webrtc import SmallWebRTCTransport
+from pipecat.transports.network.webrtc_connection import (
+    IceServer,
+    SmallWebRTCConnection,
+)
+from websocket_transcript_output import WebsocketTranscriptOutput
+
+from nvidia_pipecat.processors.audio_util import AudioRecorder
+from nvidia_pipecat.processors.nvidia_context_aggregator import (
+    NvidiaTTSResponseCacher,
+    create_nvidia_context_aggregator,
+)
+from nvidia_pipecat.processors.transcript_synchronization import (
+    BotTranscriptSynchronization,
+    UserTranscriptSynchronization,
+)
+from nvidia_pipecat.services.riva_speech import RivaASRService, RivaTTSService
+from langgraph_llm_service import LangGraphLLMService
+
+load_dotenv(override=True)
+
+
+app = FastAPI()
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Store connections by pc_id
+pcs_map: dict[str, SmallWebRTCConnection] = {}
+contexts_map: dict[str, OpenAILLMContext] = {}
+
+
+# Helper: Build ICE servers for client (browser) using Twilio token if configured
+def _build_client_ice_servers() -> list[dict]:
+    # Prefer Twilio dynamic credentials
+    sid = os.getenv("TWILIO_ACCOUNT_SID")
+    tok = os.getenv("TWILIO_AUTH_TOKEN")
+    if sid and tok:
+        try:
+            # Import lazily to avoid hard dependency when not configured
+            from twilio.rest import Client  # type: ignore
+
+            client = Client(sid, tok)
+            token = client.tokens.create()
+            servers: list[dict] = []
+            # Twilio may return either 'ice_servers' with 'url' or 'urls'
+            for s in getattr(token, "ice_servers", []) or []:
+                url_val = s.get("urls") if isinstance(s, dict) else getattr(s, "urls", None)
+                if not url_val:
+                    url_val = s.get("url") if isinstance(s, dict) else getattr(s, "url", None)
+                entry: dict = {"urls": url_val}
+                u = s.get("username") if isinstance(s, dict) else getattr(s, "username", None)
+                c = s.get("credential") if isinstance(s, dict) else getattr(s, "credential", None)
+                if u:
+                    entry["username"] = u
+                if c:
+                    entry["credential"] = c
+                if entry.get("urls"):
+                    servers.append(entry)
+            # Always include a public STUN fallback
+            servers.append({"urls": "stun:stun.l.google.com:19302"})
+            return servers
+        except Exception as e:  # noqa: BLE001
+            logger.warning(f"Twilio TURN fetch failed, falling back to env/static: {e}")
+    # Static env fallback
+    servers: list[dict] = []
+    turn_url = os.getenv("TURN_SERVER_URL") or os.getenv("TURN_URL")
+    turn_user = os.getenv("TURN_USERNAME") or os.getenv("TURN_USER")
+    turn_pass = os.getenv("TURN_PASSWORD") or os.getenv("TURN_PASS")
+    if turn_url:
+        server: dict = {"urls": turn_url}
+        if turn_user:
+            server["username"] = turn_user
+        if turn_pass:
+            server["credential"] = turn_pass
+        servers.append(server)
+    servers.append({"urls": "stun:stun.l.google.com:19302"})
+    return servers
+
+
+# Helper: Convert client ICE dicts to server IceServer objects
+def _build_server_ice_servers() -> list[IceServer]:
+    out: list[IceServer] = []
+    for s in _build_client_ice_servers():
+        urls = s.get("urls")
+        username = s.get("username", "")
+        credential = s.get("credential", "")
+        # urls may be a list or a string. Normalize to list for safety.
+        if isinstance(urls, list):
+            for u in urls:
+                out.append(IceServer(urls=u, username=username, credential=credential))
+        elif isinstance(urls, str) and urls:
+            out.append(IceServer(urls=urls, username=username, credential=credential))
+    return out
+
+
+# Backward-compatible static servers (unused when Twilio configured)
+ice_servers = (
+    [
+        IceServer(
+            urls=os.getenv("TURN_SERVER_URL", ""),
+            username=os.getenv("TURN_USERNAME", ""),
+            credential=os.getenv("TURN_PASSWORD", ""),
+        )
+    ]
+    if os.getenv("TURN_SERVER_URL")
+    else []
+)
+
+
+@app.get("/assistants")
+async def list_assistants(request: Request):
+    """Return a list of assistants from LangGraph, with robust fallbacks.
+
+    Output: List of {assistant_id, graph_id?, name?, description?, display_name}.
+    """
+    import requests
+
+    base_url = os.getenv("LANGGRAPH_BASE_URL", "http://127.0.0.1:2024").rstrip("/")
+
+    inbound_auth = request.headers.get("authorization")
+    token = os.getenv("LANGGRAPH_AUTH_TOKEN") or os.getenv("AUTH0_ACCESS_TOKEN") or os.getenv("AUTH_BEARER_TOKEN")
+    headers = {"Authorization": inbound_auth} if inbound_auth else ({"Authorization": f"Bearer {token}"} if token else None)
+
+    def normalize_entries(raw_items: list) -> list[dict]:
+        results: list[dict] = []
+        for entry in raw_items:
+            assistant_id = None
+            if isinstance(entry, dict):
+                assistant_id = entry.get("assistant_id") or entry.get("id") or entry.get("name")
+            elif isinstance(entry, str):
+                assistant_id = entry
+            if not assistant_id:
+                continue
+            results.append({"assistant_id": assistant_id, **(entry if isinstance(entry, dict) else {})})
+        return results
+
+    # Try GET /assistants first (newer servers)
+    items: list[dict] = []
+    try:
+        get_resp = requests.get(f"{base_url}/assistants", params={"limit": 100}, timeout=8, headers=headers)
+        if get_resp.ok:
+            data = get_resp.json() or []
+            if isinstance(data, dict):
+                data = data.get("items") or data.get("results") or data.get("assistants") or []
+            items = normalize_entries(data)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning(f"GET /assistants failed: {exc}")
+
+    # Fallback: POST /assistants/search (older servers)
+    if not items:
+        try:
+            search_resp = requests.post(
+                f"{base_url}/assistants/search",
+                json={
+                    "metadata": {},
+                    "limit": 100,
+                    "offset": 0,
+                    "sort_by": "assistant_id",
+                    "sort_order": "asc",
+                    "select": ["assistant_id"],
+                },
+                timeout=10,
+                headers=headers,
+            )
+            if search_resp.ok:
+                data = search_resp.json() or []
+                if isinstance(data, dict):
+                    data = data.get("items") or data.get("results") or []
+                items = normalize_entries(data)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(f"POST /assistants/search failed: {exc}")
+
+    # Best-effort: enrich with details when possible
+    enriched: list[dict] = []
+    for item in items:
+        detail = dict(item)
+        assistant_id = detail.get("assistant_id")
+        if assistant_id:
+            try:
+                detail_resp = requests.get(f"{base_url}/assistants/{assistant_id}", timeout=5, headers=headers)
+                if detail_resp.ok:
+                    d = detail_resp.json() or {}
+                    detail.update(
+                        {
+                            "graph_id": d.get("graph_id"),
+                            "name": d.get("name"),
+                            "description": d.get("description"),
+                            "metadata": d.get("metadata") or {},
+                        }
+                    )
+            except Exception:
+                pass
+        md = (detail.get("metadata") or {}) if isinstance(detail.get("metadata"), dict) else {}
+        display_name = (
+            detail.get("name")
+            or md.get("display_name")
+            or md.get("friendly_name")
+            or detail.get("graph_id")
+            or detail.get("assistant_id")
+        )
+        detail["display_name"] = display_name
+        enriched.append(detail)
+
+    # Final fallback: read local graphs from agents/langgraph.json
+    if not enriched:
+        try:
+            config_path = Path(__file__).parent / "agents" / "langgraph.json"
+            with open(config_path, encoding="utf-8") as f:
+                cfg = json.load(f) or {}
+            graphs = (cfg.get("graphs") or {}) if isinstance(cfg, dict) else {}
+            for graph_id in graphs.keys():
+                enriched.append({
+                    "assistant_id": graph_id,
+                    "graph_id": graph_id,
+                    "display_name": graph_id,
+                })
+        except Exception as exc:  # noqa: BLE001
+            logger.error(f"Failed to read local agents/langgraph.json: {exc}")
+
+    return enriched
+
+async def run_bot(webrtc_connection, ws: WebSocket, assistant_override: str | None = None):
+    """Run the voice agent bot with WebRTC connection and WebSocket.
+
+    Args:
+        webrtc_connection: The WebRTC connection for audio streaming
+        ws: WebSocket connection for communication
+    """
+    stream_id = uuid.uuid4()
+    transport_params = TransportParams(
+        audio_in_enabled=True,
+        audio_in_sample_rate=16000,
+        audio_out_sample_rate=16000,
+        audio_out_enabled=True,
+        vad_analyzer=SileroVADAnalyzer(),
+        audio_out_10ms_chunks=5,
+    )
+
+    transport = SmallWebRTCTransport(
+        webrtc_connection=webrtc_connection,
+        params=transport_params,
+    )
+
+    selected_assistant = assistant_override or os.getenv("LANGGRAPH_ASSISTANT", "ace-base-agent")
+    logger.info(f"Using LangGraph assistant: {selected_assistant}")
+
+    # Enable multi-threading for telco agent
+    enable_multi_threading = selected_assistant in ["telco-agent", "wire-transfer-agent"]
+    
+    llm = LangGraphLLMService(
+        base_url=os.getenv("LANGGRAPH_BASE_URL", "http://127.0.0.1:2024"),
+        assistant=selected_assistant,
+        user_email=os.getenv("USER_EMAIL", "test@example.com"),
+        stream_mode=os.getenv("LANGGRAPH_STREAM_MODE", "values"),
+        debug_stream=os.getenv("LANGGRAPH_DEBUG_STREAM", "false").lower() == "true",
+        enable_multi_threading=enable_multi_threading,
+    )
+
+
+
+    # stt = RivaASRService(
+    #     server=os.getenv("RIVA_ASR_URL", "localhost:50051"),
+    #     api_key=os.getenv("NVIDIA_API_KEY"),
+    #     language=os.getenv("RIVA_ASR_LANGUAGE", "en-US"),
+    #     sample_rate=16000,
+    #     model=os.getenv("RIVA_ASR_MODEL", "parakeet-1.1b-en-US-asr-streaming-silero-vad-asr-bls-ensemble"),
+    # )
+
+    stt = RivaASRService(
+        # server=os.getenv("RIVA_ASR_URL", "localhost:50051"), # default url is grpc.nvcf.nvidia.com:443
+        api_key=os.getenv("RIVA_API_KEY"),
+        function_id=os.getenv("NVIDIA_ASR_FUNCTION_ID", "52b117d2-6c15-4cfa-a905-a67013bee409"),
+        language=os.getenv("RIVA_ASR_LANGUAGE", "en-US"),
+        sample_rate=16000,
+        model=os.getenv("RIVA_ASR_MODEL", "parakeet-1.1b-en-US-asr-streaming-silero-vad-asr-bls-ensemble"),
+    )
+
+    # stt = RivaASRService(
+    #     server=os.getenv("RIVA_ASR_URL", "localhost:50051"),
+    #     api_key=os.getenv("NVIDIA_API_KEY"),
+    #     language=os.getenv("RIVA_ASR_LANGUAGE", "en-US"),
+    #     sample_rate=16000,
+    #     model=os.getenv("RIVA_ASR_MODEL", "parakeet-1.1b-en-US-asr-streaming-silero-vad-asr-bls-ensemble"),
+    # )
+
+    # Load IPA dictionary with error handling
+    ipa_file = Path(__file__).parent / "ipa.json"
+    try:
+        with open(ipa_file, encoding="utf-8") as f:
+            ipa_dict = json.load(f)
+    except FileNotFoundError as e:
+        logger.error(f"IPA dictionary file not found at {ipa_file}")
+        raise FileNotFoundError(f"IPA dictionary file not found at {ipa_file}") from e
+    except json.JSONDecodeError as e:
+        logger.error(f"Invalid JSON in IPA dictionary file: {e}")
+        raise ValueError(f"Invalid JSON in IPA dictionary file: {e}") from e
+    except Exception as e:
+        logger.error(f"Error loading IPA dictionary: {e}")
+        raise
+
+    tts = RivaTTSService(
+        # server=os.getenv("RIVA_TTS_URL", "localhost:50051"), # default url is grpc.nvcf.nvidia.com:443
+        api_key=os.getenv("RIVA_API_KEY"),
+        function_id=os.getenv("NVIDIA_TTS_FUNCTION_ID", "4e813649-d5e4-4020-b2be-2b918396d19d"),
+        voice_id=os.getenv("RIVA_TTS_VOICE_ID", "Magpie-ZeroShot.Female-1"),
+        model=os.getenv("RIVA_TTS_MODEL", "magpie_tts_ensemble-Magpie-ZeroShot"),
+        language=os.getenv("RIVA_TTS_LANGUAGE", "en-US"),
+        zero_shot_audio_prompt_file=(
+            Path(os.getenv("ZERO_SHOT_AUDIO_PROMPT")) if os.getenv("ZERO_SHOT_AUDIO_PROMPT") else None
+        ),
+    )
+
+    # tts = RivaTTSService(
+    #     server=os.getenv("RIVA_TTS_URL", "localhost:50051"),
+    #     api_key=os.getenv("NVIDIA_API_KEY"),
+    #     voice_id=os.getenv("RIVA_TTS_VOICE_ID", "Magpie-ZeroShot.Female-1"),
+    #     model=os.getenv("RIVA_TTS_MODEL", "magpie_tts_ensemble-Magpie-ZeroShot"),
+    #     language=os.getenv("RIVA_TTS_LANGUAGE", "en-US"),
+    #     zero_shot_audio_prompt_file=(
+    #         Path(os.getenv("ZERO_SHOT_AUDIO_PROMPT", str(Path(__file__).parent / "model-em_sample-02.wav")))
+    #         if os.getenv("ZERO_SHOT_AUDIO_PROMPT")
+    #         else None
+    #     ),
+    #     ipa_dict=ipa_dict,
+    # )
+
+    # Create audio_dumps directory if it doesn't exist
+    audio_dumps_dir = Path(__file__).parent / "audio_dumps"
+    audio_dumps_dir.mkdir(exist_ok=True)
+
+    asr_recorder = AudioRecorder(
+        output_file=str(audio_dumps_dir / f"asr_recording_{stream_id}.wav"),
+        params=transport_params,
+        frame_type=InputAudioRawFrame,
+    )
+
+    tts_recorder = AudioRecorder(
+        output_file=str(audio_dumps_dir / f"tts_recording_{stream_id}.wav"),
+        params=transport_params,
+        frame_type=TTSAudioRawFrame,
+    )
+
+    # Used to synchronize the user and bot transcripts in the UI
+    stt_transcript_synchronization = UserTranscriptSynchronization()
+    tts_transcript_synchronization = BotTranscriptSynchronization()
+
+    # Start with empty context; LangGraph agent manages prompts and policy
+    context = OpenAILLMContext([])
+
+    # Store context globally so WebSocket can access it
+    pc_id = webrtc_connection.pc_id
+    contexts_map[pc_id] = context
+
+    # Configure speculative speech processing based on environment variable
+    enable_speculative_speech = os.getenv("ENABLE_SPECULATIVE_SPEECH", "true").lower() == "true"
+
+    if enable_speculative_speech:
+        context_aggregator = create_nvidia_context_aggregator(context, send_interims=True)
+        tts_response_cacher = NvidiaTTSResponseCacher()
+    else:
+        context_aggregator = llm.create_context_aggregator(context)
+        tts_response_cacher = None
+
+    transcript_processor_output = WebsocketTranscriptOutput(ws)
+
+    pipeline = Pipeline(
+        [
+            transport.input(),  # Websocket input from client
+            asr_recorder,
+            stt,  # Speech-To-Text
+            stt_transcript_synchronization,
+            context_aggregator.user(),
+            llm,  # LLM
+            tts,  # Text-To-Speech
+            tts_recorder,
+            *([tts_response_cacher] if tts_response_cacher else []),  # Include cacher only if enabled
+            tts_transcript_synchronization,
+            transcript_processor_output,
+            transport.output(),  # Websocket output to client
+            context_aggregator.assistant(),
+        ]
+    )
+
+    task = PipelineTask(
+        pipeline,
+        params=PipelineParams(
+            allow_interruptions=True,
+            enable_metrics=True,
+            enable_usage_metrics=True,
+            send_initial_empty_metrics=True,
+            start_metadata={"stream_id": stream_id},
+        ),
+    )
+
+    # No auto-kickoff; LangGraph determines when/how to greet
+
+    runner = PipelineRunner(handle_sigint=False)
+
+    await runner.run(task)
+
+
+@app.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket):
+    """WebSocket endpoint for handling voice agent connections.
+
+    Args:
+        websocket: The WebSocket connection to handle
+    """
+    await websocket.accept()
+    try:
+        request = await websocket.receive_json()
+        pc_id = request.get("pc_id")
+        assistant_from_client = request.get("assistant")
+
+        if pc_id and pc_id in pcs_map:
+            pipecat_connection = pcs_map[pc_id]
+            logger.info(f"Reusing existing connection for pc_id: {pc_id}")
+            await pipecat_connection.renegotiate(sdp=request["sdp"], type=request["type"])
+        else:
+            # Build dynamic servers (Twilio or env) for new connections
+            dynamic_servers = _build_server_ice_servers()
+            pipecat_connection = SmallWebRTCConnection(dynamic_servers if dynamic_servers else ice_servers)
+            await pipecat_connection.initialize(sdp=request["sdp"], type=request["type"])
+
+            @pipecat_connection.event_handler("closed")
+            async def handle_disconnected(webrtc_connection: SmallWebRTCConnection):
+                logger.info(f"Discarding peer connection for pc_id: {webrtc_connection.pc_id}")
+                pcs_map.pop(webrtc_connection.pc_id, None)  # Remove connection reference
+                contexts_map.pop(webrtc_connection.pc_id, None)  # Remove context reference
+
+            asyncio.create_task(run_bot(pipecat_connection, websocket, assistant_from_client))
+
+        answer = pipecat_connection.get_answer()
+        pcs_map[answer["pc_id"]] = pipecat_connection
+
+        await websocket.send_json(answer)
+
+        # Keep the connection open and print text messages
+        while True:
+            try:
+                message = await websocket.receive_text()
+                # Parse JSON message from UI
+                try:
+                    data = json.loads(message)
+                    message = data.get("message", "").strip()
+                    if data.get("type") == "context_reset" and message:
+                        print(f"Received context reset from UI: {message}")
+                        logger.info(f"Context reset from UI: {message}")
+
+                        # Forward context reset as a user message to LangGraph on next turn
+                        pc_id = pipecat_connection.pc_id
+                        if pc_id in contexts_map:
+                            context = contexts_map[pc_id]
+                            context.add_message({"role": "user", "content": message})
+                        else:
+                            print(f"No context found for pc_id: {pc_id}")
+
+                except json.JSONDecodeError:
+                    print(f"Non-JSON message: {message}")
+            except Exception as e:
+                logger.error(f"Error processing message: {e}")
+                break
+
+    except WebSocketDisconnect:
+        logger.info("Client disconnected from websocket")
+
+
+@app.get("/get_prompt")
+async def get_prompt():
+    """Report that the LangGraph agent owns the prompt/policy."""
+    return {
+        "prompt": "",
+        "name": "LangGraph-managed",
+        "description": "Prompt and persona are managed by the LangGraph agent.",
+    }
+
+# RTC config endpoint must be registered before mounting static at "/"
+@app.get("/rtc-config")
+async def rtc_config():
+    """Expose browser RTC ICE configuration based on environment variables or Twilio.
+
+    Uses Twilio dynamic TURN credentials when TWILIO_ACCOUNT_SID/TWILIO_AUTH_TOKEN are set.
+    Falls back to TURN_* env vars. Always includes a public STUN fallback.
+    """
+    try:
+        servers = _build_client_ice_servers()
+        return {"iceServers": servers}
+    except Exception as e:  # noqa: BLE001
+        logger.warning(f"rtc-config dynamic build failed: {e}")
+        # Final safe fallback
+        return {"iceServers": [{"urls": "stun:stun.l.google.com:19302"}]}
+
+
+# Serve static UI (if bundled) after API/WebSocket routes so they still take precedence
+UI_DIST_DIR = Path(__file__).parent / "ui" / "dist"
+if UI_DIST_DIR.exists():
+    app.mount("/", StaticFiles(directory=str(UI_DIST_DIR), html=True), name="static")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="WebRTC demo")
+    parser.add_argument("--host", default="0.0.0.0", help="Host for HTTP server (default: localhost)")
+    parser.add_argument("--port", type=int, default=7860, help="Port for HTTP server (default: 7860)")
+    parser.add_argument("--verbose", "-v", action="count")
+    args = parser.parse_args()
+
+    logger.remove(0)
+    if args.verbose:
+        logger.add(sys.stderr, level="TRACE")
+    else:
+        logger.add(sys.stderr, level="DEBUG")
+
+    uvicorn.run(app, host=args.host, port=args.port)