diff --git a/AUTHENTICATION_QUICKSTART.md b/AUTHENTICATION_QUICKSTART.md index 6253830..07f8ec1 100644 --- a/AUTHENTICATION_QUICKSTART.md +++ b/AUTHENTICATION_QUICKSTART.md @@ -284,9 +284,10 @@ export AUTHORIZED_WEBEX_ORG_IDS="Y2lzY29zcGFyazovL3VzL09SR0FOSVpBVElPTi8xMjM0NTY ## Next Steps -- Review the [main README](README.md#authentication-setup) for production deployment - Check [monitoring README](src/monitoring/README.md#authentication) for detailed auth flow -- Set up AWS Secrets Manager for production (see main README) +- Review [Production Readiness](docs/PRODUCTION_READINESS.md) before exposing the dashboard + in a production environment +- Store production secrets in your organization's approved secret-management service ## Support @@ -294,4 +295,3 @@ For issues or questions: 1. Check the [monitoring README troubleshooting section](src/monitoring/README.md#troubleshooting-authentication) 2. Review [Webex OAuth documentation](https://developer.webex.com/docs/integrations) 3. Create an issue in the repository - diff --git a/README.md b/README.md index acbc6e8..84b6f45 100644 --- a/README.md +++ b/README.md @@ -2,802 +2,232 @@ [![License: Cisco Sample Code](https://img.shields.io/badge/License-Cisco%20Sample%20Code-blue.svg)](LICENSE) -A Python-based gateway for Webex Contact Center (WxCC) that provides virtual agent integration capabilities. This gateway acts as a bridge between WxCC and various virtual agent providers, enabling seamless voice interactions. +A Python gateway that connects Webex Contact Center (WxCC) to external voice virtual-agent +providers through the BYOVA gRPC interface. -## 📚 Documentation +This repository is functional sample code for customers and partners building or evaluating +a BYOVA integration. It is not a managed connector or a production-ready deployment. The +customer or implementation partner owns the gateway adaptation, hosting, security, capacity, +observability, and production operations. -**Start without a voice-agent vendor**: [Local Audio Connector Configuration](docs/LOCAL_AUDIO_CONFIGURATION.md) +If you are deciding whether BYOVA fits an existing voice agent, start with +[Evaluating BYOVA](docs/CUSTOMER_EVALUATION.md). If you have completed a proof of concept, +continue with [Production Readiness](docs/PRODUCTION_READINESS.md). -**Complete AWS Lex Setup Guide**: [BYOVA with AWS Lex Setup Guide](https://developer.webex.com/webex-contact-center/docs/byova-and-aws-lex) +If you want to validate the Webex-facing path before choosing a voice-agent provider, use +the [Local Audio Connector Configuration](docs/LOCAL_AUDIO_CONFIGURATION.md) guide. -This comprehensive guide walks you through: -- Setting up a Webex Contact Center sandbox -- Configuring BYOVA and BYODS -- Creating AWS Lex bots -- Deploying and testing the gateway +## What the Gateway Does -## Table of Contents +At runtime, WxCC opens a bidirectional gRPC stream to the registered gateway endpoint. The +gateway validates the signed Webex token, routes the conversation to the configured +connector, and translates audio and events between WxCC and the voice-agent provider. -- [Install](#install) -- [Monitoring Dashboard](#monitoring-dashboard) -- [Usage](#usage) -- [API](#api) -- [Security Configuration](docs/Security-Configuration.md) -- [Maintainers](#maintainers) -- [Contributing](#contributing) -- [License](#license) +The sample includes: -## Install - -### Prerequisites - -- Python 3.8 or higher -- macOS, Linux, or Windows -- Webex Contact Center environment for testing - -### Setup - -1. **Clone the Repository** - ```bash - git clone https://github.com/webex/webex-byova-gateway-python.git - cd webex-byova-gateway-python - ``` - -2. **Create and Activate Virtual Environment** - ```bash - # Create virtual environment - python -m venv venv - - # Activate virtual environment (REQUIRED before running any commands) - # On macOS/Linux: - source venv/bin/activate - # On Windows: - # venv\Scripts\activate - - # Verify activation - you should see (venv) in your prompt - which python # Should show path to venv/bin/python - ``` - -3. **Install Dependencies** (Required) - ```bash - pip install -r requirements.txt - ``` - - **Important**: All dependencies including JWT authentication libraries are required. The gateway will not start if dependencies are missing. - -4. **Generate gRPC Stubs** - ```bash - # Generate Python gRPC client and server stubs in the generated directory - python -m grpc_tools.protoc -I./proto --python_out=src/generated --grpc_python_out=src/generated proto/*.proto - ``` - - Generated protobuf files are stored in the `src/generated` directory to separate auto-generated code from hand-written code. - - **Important**: The generated protobuf files (`*_pb2.py` and `*_pb2_grpc.py`) are **NOT committed to the repository**. They must be generated locally after cloning the repository. The `__init__.py` file in the generated directory is committed to maintain the package structure. - - **Note**: The generated files are automatically imported by the gateway. No manual import is required for normal operation. - -5. **Prepare Audio Files** - - Place your audio files in the `audio/` directory. The default configuration expects: - - `welcome.wav` - Welcome message - - `default_response.wav` - Response messages - - `goodbye.wav` - Goodbye message - - `transferring.wav` - Transfer message - - `error.wav` - Error message - -## Monitoring Dashboard - -The gateway includes a web-based monitoring interface for viewing gateway status, active sessions, and connection history. The dashboard is accessible at `http://localhost:8080` when the gateway is running. - -For information about authentication and security for the monitoring dashboard, see: -- [Monitoring README](src/monitoring/README.md) - Comprehensive monitoring and authentication documentation -- [Authentication Quick Start](AUTHENTICATION_QUICKSTART.md) - Step-by-step authentication setup guide +- A BYOVA gRPC server with `ListVirtualAgents` and `ProcessCallerInput` +- JWT validation for the WxCC data plane +- A configuration-driven connector router +- Local audio and AWS Lex connectors +- gRPC and HTTP health checks +- A development monitoring dashboard +- Unit tests and local gRPC smoke-test utilities ## Quick Start -For a quick test of the gateway: - -1. **Activate virtual environment** (if not already active): - ```bash - source venv/bin/activate - ``` - -2. **Generate gRPC stubs** (if not already done): - ```bash - python -m grpc_tools.protoc -I./proto --python_out=src/generated --grpc_python_out=src/generated proto/*.proto - ``` - -3. **Start the server**: - ```bash - python main.py - ``` - -4. **Access the monitoring interface**: - - Open http://localhost:8080 in your browser - - Check the status at http://localhost:8080/api/status - -The gateway will start with the local audio connector by default, which uses the audio files in the `audio/` directory. - -## Usage - -### Configuration - -The gateway is configured via `config/config.yaml`. Key configuration sections: - -```yaml -# Gateway settings -gateway: - host: "0.0.0.0" - port: 50051 - -# Connectors configuration -connectors: - # Local Audio Connector - plays audio files from the audio/ directory - local_audio_connector: - type: "local_audio_connector" - class: "LocalAudioConnector" - module: "connectors.local_audio_connector" - config: - agent_id: "Local Playback" - audio_base_path: "audio" - audio_files: - welcome: "welcome.wav" - transfer: "transferring.wav" - goodbye: "goodbye.wav" - error: "error.wav" - default: "default_response.wav" - - # AWS Lex Connector - integrates with Amazon Lex bots - aws_lex_connector: - type: "aws_lex_connector" - class: "AWSLexConnector" - module: "connectors.aws_lex_connector" - config: - region_name: "us-east-1" - # bot_alias_id: "YOUR_BOT_ALIAS_ID" # Required for specific bot - # aws_access_key_id: "YOUR_ACCESS_KEY" # Optional, uses env vars if not set - # aws_secret_access_key: "YOUR_SECRET_KEY" # Optional, uses env vars if not set - initial_trigger_text: "hello" - barge_in_enabled: false - audio_logging: - enabled: true - output_dir: "logs/audio_recordings" - filename_format: "{conversation_id}_{timestamp}_{source}.wav" - log_all_audio: true - max_file_size: 10485760 - sample_rate: 8000 - bit_depth: 8 - channels: 1 - encoding: "ulaw" - agents: [] - -# Monitoring interface -monitoring: - enabled: true - host: "0.0.0.0" - port: 8080 - metrics_enabled: true - health_check_interval: 30 - -# Web dashboard authentication -authentication: - enabled: true - environment: "dev" # Options: "dev" or "production" - session: - timeout_hours: 24 - secret_key_env: "FLASK_SECRET_KEY" - webex_oauth: - scopes: "openid email profile" - state: "byova_gateway_auth" - -# JWT validation for gRPC requests (REQUIRED when enabled) -jwt_validation: - # Enable/disable JWT validation (default: true for security) - enabled: true - - # Enforce validation - if false, invalid tokens are logged but allowed - enforce_validation: true - - # REQUIRED: Datasource URL - must match URL registered with Webex Contact Center - # Example: "https://your-gateway-domain.com:443" - datasource_url: "" # Must be configured if enabled=true - - # Datasource schema UUID (default is standard BYOVA schema) - # This is the schema ID from https://github.com/webex/dataSourceSchemas - # Path: Services/VoiceVirtualAgent/5397013b-7920-4ffc-807c-e8a3e0a18f43/schema.json - # This value should not change unless there is a major modification to the BYOVA schema - datasource_schema_uuid: "5397013b-7920-4ffc-807c-e8a3e0a18f43" - - # Public key cache duration in minutes - cache_duration_minutes: 60 - -# Logging configuration -logging: - gateway: - level: "INFO" # DEBUG, INFO, WARNING, ERROR - format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s" - file: "logs/gateway.log" - max_size: "10MB" - backup_count: 5 - web: - level: "WARNING" - format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s" - file: "logs/web.log" - max_size: "5MB" - backup_count: 3 - -# Session management -sessions: - timeout: 600 # Session timeout in seconds - max_sessions: 1000 - cleanup_interval: 60 - enable_auto_cleanup: true - max_session_duration: 3600 - -# Audio processing -audio: - supported_formats: - - "wav" - - "mp3" - - "flac" - - "ogg" -``` - -#### Important Configuration Notes - -**JWT Validation** (Required): -- JWT validation is **enabled by default** for security -- You **must** configure `datasource_url` before starting the gateway -- The `datasource_url` must exactly match the URL you register with Webex Contact Center via the BYoDS API -- If JWT validation is enabled without `datasource_url`, the gateway will **fail to start** -- For development without JWT validation, explicitly set `jwt_validation.enabled: false` - -**Connector Configuration**: -- Multiple connectors can be configured simultaneously -- Each connector must have a unique identifier (e.g., `local_audio_connector`, `aws_lex_connector`) -- Connectors are loaded dynamically based on the `module` and `class` specified - -**AWS Credentials**: -- Prefer environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) over hardcoded credentials -- Explicit credentials in config files should only be used for development/testing - -The connector uses the standard AWS credential chain (in order of precedence): -1. **Environment variables**: `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` -2. **AWS credentials file**: `~/.aws/credentials` -3. **IAM roles**: For EC2, ECS, Lambda, and other AWS services -4. **AWS SSO**: If configured -5. **Other AWS credential sources** +> **Recommended for first-time setup:** Follow the complete +> [BYOVA with AWS Lex guide](https://developer.webex.com/webex-contact-center/docs/byova-and-aws-lex). +> It covers Webex organization enablement, the voice agent, public hosting, Service App +> authorization, data-source registration, gateway configuration, and the Contact Center +> call flow. If you have not selected a provider, use the +> [Local Audio Connector Configuration](docs/LOCAL_AUDIO_CONFIGURATION.md) guide for a +> vendor-neutral end-to-end validation. The abbreviated steps below only install and run +> the gateway code. + +### Webex Prerequisites for End-to-End Testing + +Before WxCC can connect to this gateway, you need: + +- A Webex Contact Center sandbox or nonproduction organization with BYOVA enabled +- A Service App configured with the BYODS scopes, Voice Virtual Agent schema, and the data + exchange domain for your gateway +- Authorization of that Service App by an administrator in the target organization +- A publicly reachable TLS-enabled gRPC server URL on the authorized domain +- An `ACTIVE` BYOVA data-source registration whose URL exactly matches the public server URL +- A Contact Center AI virtual-agent configuration and a test flow that uses the Virtual + Agent V2 activity +- A configured gateway connector: use the local audio connector for a vendor-neutral + validation, or configure an external voice agent and its compatible connector + +If any of these items are missing, stop here and use the +[full setup guide](https://developer.webex.com/webex-contact-center/docs/byova-and-aws-lex) +or the [local audio guide](docs/LOCAL_AUDIO_CONFIGURATION.md), depending on the connector you +are evaluating, before attempting an end-to-end call. The registered data-source URL must +also exactly match `jwt_validation.datasource_url` in `config/config.yaml`. + +### Local Software Prerequisites + +- Python 3.8 or later +- macOS, Linux, or Windows -**Examples:** +### Install ```bash -# Using environment variables (recommended for local development) -export AWS_ACCESS_KEY_ID=your_access_key_id -export AWS_SECRET_ACCESS_KEY=your_secret_access_key -export AWS_DEFAULT_REGION=us-east-1 - -# Or configure AWS CLI (recommended for persistent local setup) -aws configure - -# For production, use IAM roles attached to your EC2/ECS/Lambda resources -# No credentials needed in config files! -``` - -You can add these lines to your shell profile (e.g., `.bashrc`, `.zshrc`) or set them in your deployment environment. The gateway will automatically use these credentials if they are set. - -### JWT Authentication for gRPC Requests - -The gateway supports JWT (JSON Web Token) validation for all gRPC requests to ensure secure communication with Webex Contact Center. This feature validates tokens from Webex identity broker endpoints and verifies all required claims. - -#### Overview - -JWT authentication provides: -- **Signature Verification**: Validates tokens using RSA public keys from Webex JWKS endpoints -- **Claims Validation**: Verifies issuer, audience, subject, JWT ID, and expiration -- **Datasource Validation**: Ensures tokens are issued for the correct datasource URL and schema -- **Caching**: Public keys are cached for 60 minutes to reduce endpoint load -- **Optional Enforcement**: Can be configured to log violations without rejecting requests - -#### Configuration - -JWT validation is configured in the `jwt_validation` section of `config/config.yaml`. See the [Configuration](#configuration) section above for the complete configuration structure. - -**Key Points**: -- JWT validation is **enabled by default** (`enabled: true`) -- You **must** configure `datasource_url` or the gateway will fail to start -- Set `enabled: false` to disable JWT validation for development/testing - -#### How to Obtain Your Datasource URL - -The `datasource_url` must **EXACTLY match** (character-for-character) the URL you provide when registering your datasource via the [BYoDS (Bring Your Own Data Source)](https://developer.webex.com/webex-contact-center/docs/api/v1/data-sources) API. - -**Critical**: The JWT token from Webex Contact Center contains a `com.cisco.datasource.url` claim that must match this value exactly. Use the **exact same format** that you used in the BYoDS API registration. - -**Examples** (use whatever format YOU registered): - -```yaml -# If you registered with explicit :443 port -datasource_url: "https://your-gateway.example.com:443" - -# If you registered without port (common for standard HTTPS) -datasource_url: "https://your-gateway.example.com" - -# Ngrok URLs (check your BYoDS registration for exact format) -datasource_url: "https://abc123def456.ngrok-free.app" +git clone https://github.com/webex/webex-byova-gateway-python.git +cd webex-byova-gateway-python +python -m venv venv +source venv/bin/activate +python -m pip install -r requirements.txt +python -m grpc_tools.protoc \ + -I./proto \ + --python_out=src/generated \ + --grpc_python_out=src/generated \ + proto/*.proto ``` -**How to verify**: -1. Check your BYoDS datasource registration (via API or Control Hub) -2. Copy the EXACT URL you registered (character-for-character) -3. Paste it into `jwt_validation.datasource_url` in your config - -**Common mistakes**: -- ❌ Registered: `https://example.com` → Config: `https://example.com:443` (MISMATCH!) -- ❌ Registered: `https://example.com:443` → Config: `https://example.com` (MISMATCH!) -- ✅ Registered: `https://example.com` → Config: `https://example.com` (MATCH!) -- ✅ Registered: `https://example.com:443` → Config: `https://example.com:443` (MATCH!) - -#### Understanding the Datasource Schema UUID - -The `datasource_schema_uuid` identifies the specific schema definition used for communication between Webex Contact Center and your gateway. This UUID comes from the [Webex dataSourceSchemas repository](https://github.com/webex/dataSourceSchemas). - -**For BYOVA (Voice Virtual Agent)**: -- **Schema UUID**: `5397013b-7920-4ffc-807c-e8a3e0a18f43` -- **Schema Location**: `Services/VoiceVirtualAgent/5397013b-7920-4ffc-807c-e8a3e0a18f43/schema.json` -- **Proto Definitions**: Defined in the same directory structure -- **Stability**: This UUID should **not change** unless there is a major modification to the BYOVA schema definition by Webex - -**What is it?** -The schema UUID defines the structure of request and response payloads, protocol (gRPC), and supported app types. It ensures that both Webex Contact Center and your gateway are using the same communication protocol and message formats. - -**Do I need to change it?** -In most cases, **no**. The default value is the standard BYOVA schema UUID and will work for all standard BYOVA implementations. You would only change this if: -- Webex releases a new major version of the BYOVA schema -- You're using a different Webex Contact Center service schema (not BYOVA) - -**Reference**: [Webex dataSourceSchemas Documentation](https://github.com/webex/dataSourceSchemas) +On Windows, activate the virtual environment with `venv\Scripts\activate`. -#### Supported Webex Regions +### Configure a Local-Only Run -The gateway validates tokens from these Webex identity broker issuers: -- `https://idbrokerbts.webex.com/idb` (BTS US) -- `https://idbrokerbts-eu.webex.com/idb` (BTS EU) -- `https://idbroker.webex.com/idb` (Production US) -- `https://idbroker-eu.webex.com/idb` (Production EU) -- `https://idbroker-b-us.webex.com/idb` (B-US) -- `https://idbroker-ca.webex.com/idb` (Canada) +The checked-in configuration enables gRPC JWT validation without committing a datasource +URL, so a fresh checkout intentionally refuses to start until it is configured. -#### Token Format +For a local-only test that is not connected to Webex, set the following in +`config/config.yaml`: -Tokens are expected in the gRPC metadata `authorization` header: -``` -authorization: Bearer -``` - -#### Deployment Recommendations - -**Development**: ```yaml -jwt_validation: - enabled: false # Or enabled: true with enforce_validation: false for testing -``` +authentication: + enabled: false -**Production**: -```yaml jwt_validation: - enabled: true - enforce_validation: true - datasource_url: "https://your-production-url.com:443" + enabled: false ``` -#### Troubleshooting - -**Error: "Missing JWT token in authorization metadata"** -- Ensure Webex Contact Center is configured to send JWT tokens with gRPC requests -- Verify your datasource is properly registered with Webex Contact Center - -**Error: "JWT token signature not valid"** -- Check that public keys can be fetched from Webex identity broker -- Verify your network allows outbound HTTPS connections to Webex endpoints - -**Error: "Invalid issuer"** -- The JWT token's issuer claim must be from a valid Webex identity broker -- **Security**: Issuer is validated BEFORE fetching keys to prevent SSRF attacks -- Supported issuers: - - `https://idbrokerbts.webex.com/idb` (BTS US) - - `https://idbrokerbts-eu.webex.com/idb` (BTS EU) - - `https://idbroker.webex.com/idb` (Production US) - - `https://idbroker-eu.webex.com/idb` (Production EU) - - `https://idbroker-b-us.webex.com/idb` (B-US) - - `https://idbroker-ca.webex.com/idb` (Canada) -- Verify your datasource is properly configured in Webex Contact Center -- If you see this error with a malformed issuer URL, it may indicate a security attack attempt +Never use disabled authentication for a Webex-connected or production endpoint. For an +end-to-end test, configure the exact registered datasource URL and keep JWT enforcement +enabled. -**Error: "Datasource URL mismatch"** or "Datasource claims validation failed" -- Your `datasource_url` in config must EXACTLY match (character-for-character) the URL you registered via BYoDS API -- The JWT token contains a `com.cisco.datasource.url` claim that must match your config value exactly -- Check if you registered with or without the port (`:443`) and match it exactly -- Common issue: Config has `:443` but BYoDS registration doesn't (or vice versa) -- **To debug**: Set log level to DEBUG and check the log message showing expected vs actual URL -- **Solution**: Copy the exact URL from your BYoDS datasource registration and update your config - -**Error: "JWT token is expired"** -- This indicates Webex Contact Center sent an expired token -- Check system clock synchronization between your gateway and Webex services - -For gradual rollout, start with `enforce_validation: false` to log validation results without rejecting requests, then enable enforcement after verification. - -### Running the Server - -#### Method 1: Manual Start (Recommended for Development) +### Run ```bash -# Ensure virtual environment is activated -source venv/bin/activate - -# Start the server python main.py ``` -The server will start both: -- **gRPC Server**: `grpc://0.0.0.0:50051` -- **Web Monitoring Interface**: `http://localhost:8080` - -#### Method 2: Background Start +Then check: ```bash -# Start in background -python main.py & - -# Check if running -ps aux | grep "python main.py" - -# Stop the server -pkill -f "python main.py" -``` - -### Public URL Hosting with ngrok - -The [Bring Your Own Data Source (BYODS) framework](https://developer.webex.com/create/docs/bring-your-own-datasource) requires a publicly accessible URL for data exchange with Webex Contact Center. For development and testing, you can use ngrok to create a public URL that tunnels to your local gateway. - -#### Prerequisites - -1. **Install ngrok** - - Download from [ngrok.com](https://ngrok.com/download) - - Or install via package manager: - ```bash - # macOS with Homebrew - brew install ngrok/ngrok/ngrok - - # Or download directly from ngrok.com - ``` - -2. **Sign up for ngrok account** (free tier available) - - Create account at [ngrok.com](https://ngrok.com) - - Get your authtoken from the dashboard - -3. **Configure ngrok** - ```bash - # Add your authtoken - ngrok config add-authtoken YOUR_AUTHTOKEN - ``` - -#### Running with ngrok - -1. **Start the gateway** (in one terminal): - ```bash - # Activate virtual environment - source venv/bin/activate - - # Start the gateway - python main.py - ``` - -2. **Start ngrok tunnel** (in another terminal): - ```bash - # Create public tunnel to the gRPC server - ngrok http --upstream-protocol=http2 50051 - ``` - - **Important**: Use the `--upstream-protocol=http2` flag as gRPC requires HTTP/2 protocol. - -3. **Access your public gateway**: - - ngrok will display a public URL like: `https://abc123.ngrok.io` - - This URL can be used by external services to connect to your gateway - - The monitoring interface will still be available locally at `http://localhost:8080` - -4. **Register with Webex Data Sources API**: - - Use the ngrok URL to register your data source with the [Webex Data Sources API](https://developer.webex.com/admin/docs/api/v1/data-sources/register-a-data-source) - - This registration is required for Webex Contact Center to establish the BYODS connection - - The registered URL will be used for all data exchange between Webex and your gateway - -#### ngrok Dashboard - -- Access the ngrok web interface at `http://localhost:4040` to monitor requests -- View real-time traffic, request/response details, and connection status -- Useful for debugging external connections to your gateway - -#### Security Considerations - -- **Development Only**: ngrok is intended for development and testing -- **Temporary URLs**: Free ngrok URLs change each time you restart ngrok -- **Public Access**: Anyone with the URL can access your gateway -- **Credentials**: Never expose production credentials through ngrok - -#### Example Usage - -```bash -# Terminal 1: Start gateway -source venv/bin/activate -python main.py - -# Terminal 2: Start ngrok tunnel -ngrok http --upstream-protocol=http2 50051 - -# Output example: -# Forwarding https://abc123.ngrok.io -> http://localhost:50051 -# -# Use this URL in your Webex Contact Center configuration: -# https://abc123.ngrok.io -``` - -### Monitoring Interface - -Once the server is running, access the web monitoring interface at: - -- **Main Dashboard**: `http://localhost:8080` -- **Status API**: `http://localhost:8080/api/status` -- **Connections API**: `http://localhost:8080/api/connections` -- **Health Check**: `http://localhost:8080/health` -- **Debug Info**: `http://localhost:8080/api/debug/sessions` - -#### Dashboard Features - -- **Real-time Status**: Gateway status and metrics -- **Active Connections**: Live session tracking -- **Connection History**: Recent connection events -- **Available Agents**: List of configured virtual agents -- **Configuration**: Gateway settings and connector info - -### Testing - -```bash -# Test the monitoring interface curl http://localhost:8080/api/status - -# Test connection tracking -curl http://localhost:8080/api/connections - -# Create a test session (for development) -curl http://localhost:8080/api/test/create-session -``` - -### gRPC Service Testing - -Test the gRPC services directly using either grpcurl or the provided Python test script. - -#### Using grpcurl - -If you have grpcurl installed, you can test the gRPC services directly. Install grpcurl from the [releases page](https://github.com/fullstorydev/grpcurl/releases) for your platform. - -**Test gRPC services:** -```bash -# Test overall health -grpcurl -plaintext -import-path proto -proto health.proto localhost:50051 grpc.health.v1.Health/Check - -# Test gateway service health -grpcurl -plaintext -import-path proto -proto health.proto -d '{"service":"byova.gateway"}' localhost:50051 grpc.health.v1.Health/Check - -# Test VoiceVirtualAgent service health -grpcurl -plaintext -import-path proto -proto health.proto -d '{"service":"byova.VoiceVirtualAgentService"}' localhost:50051 grpc.health.v1.Health/Check - -# List available virtual agents -grpcurl -plaintext -import-path proto -proto voicevirtualagent.proto localhost:50051 com.cisco.wcc.ccai.media.v1.VoiceVirtualAgent/ListVirtualAgents +python test_health.py ``` -**Expected outputs:** -```json -# Health checks return: -{"status": "SERVING"} - -# Virtual agents list returns: -{ - "virtualAgents": [ - { - "virtualAgentId": "Local Audio: Local Playback", - "virtualAgentName": "Local Playback", - "isDefault": true - }, - { - "virtualAgentId": "aws_lex_connector: YourBotName", - "virtualAgentName": "YourBotName" - } - ] -} -``` +The gRPC server listens on `localhost:50051`, and the development monitoring interface +listens on `http://localhost:8080`. Press `Ctrl+C` to stop the gateway gracefully. -#### Using Python Test Script +See [Local Development](docs/LOCAL_DEVELOPMENT.md) for dashboard authentication, public +endpoint testing, logs, and troubleshooting. -Alternatively, use the provided Python test script: +## Documentation -```bash -# Run the health check test script -python test_health.py -``` - -**Expected output:** -``` -Testing gRPC Health Service: ----------------------------------------- -Overall: SERVING (1) -byova.gateway: SERVING (1) -byova.VoiceVirtualAgentService: SERVING (1) -``` +| Audience or task | Guide | +| --- | --- | +| Complete a first end-to-end AWS Lex setup (recommended) | [BYOVA with AWS Lex](https://developer.webex.com/webex-contact-center/docs/byova-and-aws-lex) | +| Evaluate BYOVA for an existing voice agent | [Customer Evaluation](docs/CUSTOMER_EVALUATION.md) | +| Validate BYOVA before choosing a voice-agent provider | [Local Audio Connector Configuration](docs/LOCAL_AUDIO_CONFIGURATION.md) | +| Install and run the sample locally | [Local Development](docs/LOCAL_DEVELOPMENT.md) | +| Configure the gateway and connectors | [Configuration Reference](config/README.md) | +| Configure runtime JWT validation | [gRPC JWT Authentication](docs/JWT_AUTHENTICATION.md) | +| Run automated and service tests | [Testing Guide](docs/TESTING.md) | +| Configure the monitoring dashboard | [Monitoring Interface](src/monitoring/README.md) | +| Add or configure connectors | [Connector Guide](src/connectors/README.md) | +| Configure AWS Lex | [AWS Lex Configuration](docs/AWS_LEX_CONFIGURATION.md) | +| Configure TLS and network security | [Security Configuration](docs/Security-Configuration.md) | +| Prepare a derivative for production | [Production Readiness](docs/PRODUCTION_READINESS.md) | -**Status codes:** -- `SERVING (1)`: Service is healthy and operational -- `NOT_SERVING (2)`: Service is unhealthy or unavailable -- `SERVICE_UNKNOWN (0)`: Service status cannot be determined +The [documentation index](docs/README.md) provides additional component references. -**Security Note:** gRPC reflection is disabled by default for security. This is why proto files are required for grpcurl commands. +## Interfaces -## API +### gRPC -### gRPC Endpoints +- `ListVirtualAgents`: Returns the configured virtual agents. +- `ProcessCallerInput`: Handles bidirectional caller audio, DTMF, and conversation events. +- `grpc.health.v1.Health/Check`: Reports service health. -- **ListVirtualAgents**: Returns available virtual agents -- **ProcessCallerInput**: Handles bidirectional streaming for voice interactions -- **Health/Check**: Standard gRPC health checking service +The protocol definitions are in `proto/` and originate from the Webex Voice Virtual Agent +schema. -### HTTP Endpoints +### HTTP Monitoring -- `GET /`: Main dashboard -- `GET /api/status`: Gateway status -- `GET /api/connections`: Connection data -- `GET /health`: Health check -- `GET /api/debug/sessions`: Debug information +- `GET /`: Development monitoring dashboard +- `GET /api/status`: Gateway and connector status +- `GET /api/connections`: Recent connection information +- `GET /health`: HTTP process health -## Features +The monitoring interface is a development and diagnostic tool. Do not expose it in +production without the controls described in the production guide. -- **gRPC Server**: Handles communication with Webex Contact Center -- **Virtual Agent Router**: Dynamically routes requests to different connector implementations -- **Local Audio Connector**: Simulates virtual agents using local audio files -- **AWS Lex Connector**: Integration with Amazon Lex v2 for production virtual agents -- **Web Monitoring Interface**: Real-time dashboard for monitoring connections and status -- **Session Management**: Tracks active sessions and connection events -- **Extensible Architecture**: Easy to add new connector implementations +## Included Connectors -## Connector Documentation +- **Local Audio**: Uses the included WAV files for local development and vendor-neutral + end-to-end validation. See [Local Audio Connector Configuration](docs/LOCAL_AUDIO_CONFIGURATION.md). +- **AWS Lex**: Connects to Amazon Lex V2 through the standard AWS SDK credential chain. -This gateway supports multiple virtual agent connectors. Each connector has its own documentation: - -- **[Connectors Overview](src/connectors/README.md)**: Complete guide to all available connectors and how to create new ones -- **[Local Audio Connector Configuration](docs/LOCAL_AUDIO_CONFIGURATION.md)**: Validate BYOVA with a Contact Center sandbox before choosing a voice-agent vendor -- **[AWS Lex Connector](src/connectors/README.md#aws-lex-connector-aws_lex_connectorpy)**: Production integration with Amazon Lex v2 -- **[Audio Files Guide](audio/README.md)**: Audio file formats, organization, and configuration +Connectors implement `IVendorConnector` and are loaded from `config/config.yaml`. See the +[Connector Guide](src/connectors/README.md) for the interface contract and extension pattern. ## Project Structure -``` +```text webex-byova-gateway-python/ -├── audio/ # Audio files for local connector -├── config/ -│ ├── config.yaml # Main configuration file -│ └── aws_lex_example.yaml # AWS Lex configuration example -├── proto/ # Protocol Buffer definitions +├── audio/ # Local connector audio files +├── config/ # Gateway and connector configuration +├── docs/ # Evaluation, security, testing, and operations guides +├── proto/ # BYOVA and health protocol definitions ├── src/ -│ ├── connectors/ # Virtual agent connector implementations -│ │ ├── i_vendor_connector.py -│ │ ├── local_audio_connector.py -│ │ ├── aws_lex_connector.py -│ │ └── README.md -│ ├── core/ # Core gateway components -│ │ ├── virtual_agent_router.py -│ │ └── wxcc_gateway_server.py -│ ├── generated/ # Generated gRPC stubs -│ │ ├── byova_common_pb2.py -│ │ ├── byova_common_pb2_grpc.py -│ │ ├── voicevirtualagent_pb2.py -│ │ └── voicevirtualagent_pb2_grpc.py -│ ├── monitoring/ # Web monitoring interface -│ │ ├── app.py -│ │ └── templates/ -│ └── utils/ # Utility modules -├── main.py # Main entry point -├── requirements.txt # Python dependencies -└── README.md +│ ├── auth/ # gRPC JWT validation +│ ├── connectors/ # Virtual-agent connectors +│ ├── core/ # Gateway server, routing, and health +│ ├── generated/ # Locally generated gRPC modules +│ ├── monitoring/ # Development monitoring interface +│ └── utils/ # Audio utilities +├── tests/ # Automated test suite +├── main.py # Application entry point +└── requirements.txt # Python dependencies ``` ## Development -### Adding New Connectors - -1. Create a new connector class in `src/connectors/` -2. Inherit from `IVendorConnector` -3. Implement required abstract methods -4. Add configuration to `config/config.yaml` -5. Restart the server - -### gRPC Stub Generation - -The protobuf definitions used in this gateway are sourced from the [Webex dataSourceSchemas repository](https://github.com/webex/dataSourceSchemas), specifically the Voice Virtual Agent schema. These definitions define the structure for BYOVA (Bring Your Own Virtual Agent) data exchange with Webex Contact Center. - -If you modify the `.proto` files, you must regenerate the Python stubs: - -```bash -# Regenerate stubs -python -m grpc_tools.protoc -I./proto --python_out=src/generated --grpc_python_out=src/generated proto/*.proto -``` - -**Note**: The generated files are automatically ignored by git (see `.gitignore`). After regenerating, the files will be available locally but won't be committed to the repository. +To add a connector: -## Troubleshooting +1. Create a connector class in `src/connectors/`. +2. Inherit from `IVendorConnector` and implement every required method. +3. Add the connector to `config/config.yaml`. +4. Add unit and integration tests. +5. Validate the full conversation lifecycle, including escalation and cleanup. -### Port Conflicts - -If port 8080 is in use: +If a proto changes, regenerate the local Python modules: ```bash -# Check what's using the port -lsof -i :8080 - -# Kill the process -kill - -# Or change the port in config/config.yaml +python -m grpc_tools.protoc \ + -I./proto \ + --python_out=src/generated \ + --grpc_python_out=src/generated \ + proto/*.proto ``` -### Virtual Environment Issues +## Support and Contributing -**Problem**: `python: command not found` or import errors +For BYOVA concepts and onboarding, see the official +[BYOVA developer guide](https://developer.webex.com/webex-contact-center/docs/bring-your-own-virtual-agent). +For repository changes, open an issue or pull request with reproduction steps and relevant +logs that do not contain credentials, caller audio, or customer data. -**Solution**: Ensure virtual environment is activated before running any Python commands: - -```bash -# Check if virtual environment is activated -echo $VIRTUAL_ENV # Should show path to venv directory - -# If not activated, activate it -source venv/bin/activate - -# Verify Python is from virtual environment -which python # Should show .../venv/bin/python - -# Recreate virtual environment if needed -rm -rf venv -python -m venv venv -source venv/bin/activate -pip install -r requirements.txt -``` - -**Important**: Always activate the virtual environment before running `python main.py` or any other Python commands. - -### Logs - -The server provides detailed logging: -- **INFO**: General operation information -- **DEBUG**: Detailed request/response tracking -- **ERROR**: Error conditions and exceptions - -Check the terminal output for real-time logs when running manually. - -## Maintainers - -[@adweeks](https://github.com/adweeks) - -## Contributing - -1. Fork the repository -2. Create a feature branch -3. Make your changes -4. Test thoroughly -5. Submit a pull request +Maintainer: [@adweeks](https://github.com/adweeks) ## License -[Cisco Sample Code License v1.1](LICENSE) © 2018 Cisco and/or its affiliates - ---- +[Cisco Sample Code License v1.1](LICENSE) © 2018 Cisco and/or its affiliates. -**Note**: This Sample Code is not supported by Cisco TAC and is not tested for quality or performance. This is intended for example purposes only and is provided by Cisco "AS IS" with all faults and without warranty or support of any kind. +This sample code is not supported by Cisco TAC and is not tested for production quality or +performance. It is provided for example purposes only, “AS IS,” with all faults and without +warranty or support of any kind. diff --git a/config/README.md b/config/README.md index fef86f2..08d4294 100644 --- a/config/README.md +++ b/config/README.md @@ -1,144 +1,80 @@ -# Configuration +# Gateway Configuration -This directory contains configuration files for the Webex Contact Center BYOVA Gateway, providing centralized management of gateway settings, connectors, and system behavior. +`config/config.yaml` is the configuration file loaded by `main.py`. This reference documents +the settings used by the current sample implementation. Connector-specific options are +documented with their connectors. -## Configuration Files +The gateway does not perform general `${ENV_VAR}` substitution inside YAML. Environment +variables are used directly by specific components, including Webex OAuth and the standard +AWS credential chain. -### `config.yaml` - -The main configuration file that defines all gateway settings: - -- **Connectors**: Vendor connector implementations and their settings -- **Gateway Settings**: Global gateway configuration and behavior -- **Monitoring**: Web interface and metrics configuration -- **Logging**: Log file settings, levels, and formatting -- **Session Management**: Timeout, cleanup, and session limits -- **Audio Processing**: Supported formats, limits, and processing options -- **Security**: Authentication, encryption, and access control settings - -## Configuration Structure - -### Gateway Settings +## Gateway Listener ```yaml -# Gateway configuration gateway: host: "0.0.0.0" port: 50051 - max_workers: 10 - timeout: 30 - enable_tls: false - cert_file: "" - key_file: "" ``` -### Connectors Section +`host` and `port` control the insecure application listener. Production deployments should +place it behind an approved TLS boundary or add an appropriate secure listener. See +[Security Configuration](../docs/Security-Configuration.md). -Each connector is defined with comprehensive settings: - -```yaml -connectors: - - name: "connector_name" # Unique identifier - type: "connector_type" # Connector type - class: "ClassName" # Python class name - module: "module.path" # Python module path - enabled: true # Enable/disable connector - config: # Connector-specific settings - key1: "value1" - key2: "value2" - api_key: "${API_KEY}" # Environment variable substitution - endpoint: "${VENDOR_ENDPOINT}" - agents: # List of agent IDs this connector provides - - "Agent 1" - - "Agent 2" - health_check: # Health check configuration - enabled: true - interval: 30 - timeout: 5 -``` - -### Monitoring Configuration - -```yaml -monitoring: - enabled: true - host: "0.0.0.0" - port: 8080 - debug: false - metrics_enabled: true - health_check_interval: 30 - cors_enabled: true - allowed_origins: - - "http://localhost:3000" - - "https://yourdomain.com" -``` +The gRPC worker count, maximum message sizes, and concurrent-stream option are currently set +in `main.py`; values elsewhere in YAML are not production capacity controls. -### Logging Configuration +## Voice Activity Detection ```yaml -logging: - level: "INFO" - format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s" - handlers: - - type: "console" - level: "INFO" - - type: "file" - filename: "logs/gateway.log" - level: "DEBUG" - max_bytes: 10485760 # 10MB - backup_count: 5 - loggers: - grpc: "WARNING" - urllib3: "WARNING" +voice_activity_detection: + threshold: 0.5 + start_debounce_ms: 96 + end_silence_ms: 1000 + fallback_sample_rate_hertz: 8000 ``` -### Session Management - -```yaml -sessions: - timeout: 300 # Session timeout in seconds - cleanup_interval: 60 # Cleanup interval in seconds - max_sessions: 1000 # Maximum concurrent sessions - max_session_duration: 3600 # Maximum session duration - enable_auto_cleanup: true # Enable automatic session cleanup -``` +These values configure the gateway's speech-boundary observer for each conversation. +`fallback_sample_rate_hertz` is used only when WxCC omits the input sample rate. Changes to +the threshold or timing values affect turn boundaries and caller experience, so validate +them with representative audio and latency tests before deployment. -## Environment Variable Support +## Connectors -Configuration supports environment variable substitution for sensitive data: +Connectors are keyed dictionaries: ```yaml -config: - api_key: "${API_KEY}" # Will be replaced with environment variable - endpoint: "${VENDOR_ENDPOINT}" - database_url: "${DATABASE_URL}" - secret_key: "${SECRET_KEY}" +connectors: + local_audio_connector: + type: "local_audio_connector" + class: "LocalAudioConnector" + module: "connectors.local_audio_connector" + config: + agent_id: "Local Playback" + audio_base_path: "audio" ``` -### Environment Variable Loading - -The gateway supports multiple ways to load environment variables: - -1. **System Environment**: Variables set in the system environment (e.g., via `export` command) -2. **Docker Environment**: Container environment variables -3. **Kubernetes Secrets**: Kubernetes secret management -4. **AWS Secrets Manager**: Production secret management (recommended for production) +The loader requires each connector to provide `class` and `module`; an omitted `config` +mapping defaults to an empty dictionary. It dynamically imports `src.`, verifies +that the class implements `IVendorConnector`, and registers the agents returned by the +connector. -**Note**: This gateway **does NOT use `.env` files**. For development, set environment variables directly using `export` commands or add them to your shell profile. For production, use a secret management service. +Available connector documentation: -## Example Connectors +- [Connector interface and development](../src/connectors/README.md) +- [Local audio configuration](../docs/LOCAL_AUDIO_CONFIGURATION.md) +- [AWS Lex configuration](../docs/AWS_LEX_CONFIGURATION.md) +- `config/aws_lex_example.yaml` ### Local Audio Connector -**Purpose**: Testing and development with local audio files +The checked-in configuration maps response types to the audio files included in `audio/`: ```yaml connectors: - - name: "my_local_test_agent" + local_audio_connector: type: "local_audio_connector" class: "LocalAudioConnector" module: "connectors.local_audio_connector" - enabled: true config: agent_id: "Local Playback" audio_base_path: "audio" @@ -148,254 +84,144 @@ connectors: goodbye: "goodbye.wav" error: "error.wav" default: "default_response.wav" - playback_settings: - volume: 1.0 - speed: 1.0 - format: "wav" ``` -### Vendor X Connector (Example) +Use `agent_id`, not an `agents` list, to change the advertised local agent name. See +[Local Audio Connector Configuration](../docs/LOCAL_AUDIO_CONFIGURATION.md) for the local +and end-to-end sandbox test paths. -**Purpose**: Integration with Vendor X platform +### AWS Credentials -```yaml -connectors: - - name: "vendor_x_connector" - type: "vendor_x" - class: "VendorXConnector" - module: "connectors.vendor_x_connector" - enabled: true - config: - api_key: "${VENDOR_X_API_KEY}" - endpoint: "${VENDOR_X_ENDPOINT}" - timeout: 30 - retry_attempts: 3 - authentication: - type: "bearer" - token: "${VENDOR_X_TOKEN}" - features: - speech_to_text: true - text_to_speech: true - natural_language: true - agents: - - "Vendor X Agent 1" - - "Vendor X Agent 2" -``` +The AWS Lex connector uses the standard AWS SDK credential chain. Prefer workload roles or +short-lived credentials. For local development, supported SDK sources include environment +variables, AWS shared configuration, and AWS SSO. -### OpenAI Connector (Example) +Do not put production access keys in `config.yaml`. -**Purpose**: AI-powered virtual agents +## Monitoring Server ```yaml -connectors: - - name: "openai_connector" - type: "openai" - class: "OpenAIConnector" - module: "connectors.openai_connector" - enabled: true - config: - api_key: "${OPENAI_API_KEY}" - model: "gpt-4" - max_tokens: 1000 - temperature: 0.7 - system_prompt: "You are a helpful virtual assistant." - features: - conversation_memory: true - context_awareness: true - multi_language: true - agents: - - "AI Assistant" - - "Customer Support Bot" +monitoring: + enabled: true + host: "0.0.0.0" + port: 8080 + debug: false ``` -## Configuration Loading - -The gateway loads configuration in this order: - -1. **Default Configuration**: Built-in defaults for all settings -2. **Config File**: `config/config.yaml` (overrides defaults) -3. **Environment Variables**: Override specific settings -4. **Command Line Arguments**: Final overrides for runtime settings - -### Configuration Validation - -Configuration is validated on startup: +`enabled`, `host`, `port`, and `debug` control the Flask monitoring server started by +`main.py`. The checked-in YAML also contains `metrics_enabled` and +`health_check_interval`, but the current sample does not expose an instrumented production +metrics endpoint or schedule health checks from those values. -- **Required Fields**: Ensure all required fields are present -- **Connector Classes**: Verify connector classes can be imported -- **File Existence**: Check that referenced files exist (audio files, certificates) -- **Network Connectivity**: Test API endpoints for remote connectors -- **Type Validation**: Validate data types and value ranges +See [Monitoring Interface](../src/monitoring/README.md). -### Configuration Hot Reloading - -The gateway supports hot reloading of certain configuration sections: +## Monitoring Dashboard Authentication ```yaml -# Enable hot reloading -config: - hot_reload: - enabled: true - watch_interval: 30 - reloadable_sections: - - "logging" - - "monitoring" - - "sessions" +authentication: + enabled: true + environment: "dev" + session: + timeout_hours: 24 + secret_key_env: "FLASK_SECRET_KEY" + webex_oauth: + scopes: "openid email profile" + state: "byova_gateway_auth" ``` -## Security Configuration +When enabled, the monitoring application reads: -### Authentication and Authorization +- `FLASK_SECRET_KEY`, or the environment variable named by `secret_key_env` +- `WEBEX_CLIENT_ID` +- `WEBEX_CLIENT_SECRET` +- `WEBEX_REDIRECT_URI` +- `AUTHORIZED_WEBEX_ORG_IDS` -```yaml -security: - authentication: - enabled: true - type: "jwt" - secret_key: "${JWT_SECRET_KEY}" - token_expiry: 3600 - authorization: - enabled: true - roles: - - "admin" - - "operator" - - "viewer" - encryption: - enabled: true - algorithm: "AES-256-GCM" - key: "${ENCRYPTION_KEY}" -``` +See [Authentication Quick Start](../AUTHENTICATION_QUICKSTART.md). This authentication is +separate from JWT validation on the gRPC data plane. -### Network Security +## gRPC JWT Validation ```yaml -network: - tls: - enabled: false - cert_file: "certs/server.crt" - key_file: "certs/server.key" - ca_file: "certs/ca.crt" - firewall: - allowed_ips: - - "192.168.1.0/24" - - "10.0.0.0/8" - rate_limiting: - enabled: true - requests_per_minute: 100 - burst_size: 20 +jwt_validation: + enabled: true + enforce_validation: true + datasource_url: "https://your-gateway.example.com:443" + datasource_schema_uuid: "5397013b-7920-4ffc-807c-e8a3e0a18f43" + cache_duration_minutes: 60 ``` -## Performance Configuration +When enabled, `datasource_url` is required and must exactly match the registered data-source +URL. The gateway will not start with an empty value. + +See [gRPC JWT Authentication](../docs/JWT_AUTHENTICATION.md) for claims, issuers, deployment +modes, and troubleshooting. -### Resource Limits +## Logging ```yaml -performance: - memory: - max_heap_size: "2G" - gc_threshold: 0.8 - cpu: - max_threads: 10 - thread_pool_size: 20 - network: - connection_timeout: 30 - read_timeout: 60 - write_timeout: 60 - caching: - enabled: true - max_size: 1000 - ttl: 3600 +logging: + gateway: + level: "INFO" + format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s" + file: "logs/gateway.log" + web: + level: "WARNING" + format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s" + file: "logs/web.log" ``` -### Monitoring and Metrics +The current logging setup uses the configured level, format, and file. Although the sample +YAML contains `max_size` and `backup_count`, `main.py` currently uses a plain `FileHandler`, +so those values do not rotate files. -```yaml -metrics: - enabled: true - prometheus: - enabled: true - port: 9090 - path: "/metrics" - health_checks: - enabled: true - interval: 30 - timeout: 5 - alerting: - enabled: true - webhook_url: "${ALERT_WEBHOOK_URL}" -``` +Production services should use structured, centralized logging as described in +[Production Readiness](../docs/PRODUCTION_READINESS.md). -## Troubleshooting +## Sample Placeholder Sections -### Common Issues +The checked-in YAML includes top-level `sessions` and `audio.supported_formats` sections. +They describe intended sample settings, but `main.py` and `WxCCGatewayServer` do not currently +enforce those values as session, concurrency, cleanup, or codec limits. Do not use them for +capacity planning or production safety controls. -1. **Missing Connector Class**: Ensure the Python class exists and is importable -2. **Invalid Configuration**: Check YAML syntax and required fields -3. **Missing Audio Files**: Verify audio files exist for local connector -4. **Network Issues**: Check API endpoints for remote connectors -5. **Permission Errors**: Verify file permissions for logs and certificates -6. **Environment Variables**: Ensure environment variables are properly set +Connector-level audio settings, such as AWS Lex `audio_logging` and `audio_buffering`, are +read by the relevant connector implementation. -### Debug Mode +## Local Development Settings -Enable debug logging to see detailed configuration loading: +For a local-only run that is not connected to Webex: ```yaml -logging: - level: "DEBUG" - handlers: - - type: "console" - level: "DEBUG" - - type: "file" - filename: "logs/config_debug.log" - level: "DEBUG" -``` +authentication: + enabled: false -### Configuration Validation - -```bash -# Validate configuration syntax -python -c " -import yaml -with open('config/config.yaml', 'r') as f: - config = yaml.safe_load(f) -print('Configuration is valid') -" - -# Check for missing environment variables -python -c " -import os -import yaml -with open('config/config.yaml', 'r') as f: - config = yaml.safe_load(f) -# Check for ${VARIABLE} patterns -" +jwt_validation: + enabled: false ``` -## Best Practices - -### Configuration Management - -- **Version Control**: Keep configuration in version control -- **Environment Separation**: Use different configs for dev/staging/prod -- **Sensitive Data**: Use environment variables for secrets -- **Documentation**: Document all configuration options -- **Validation**: Implement configuration validation +Do not use disabled authentication for a public or production endpoint. See +[Local Development](../docs/LOCAL_DEVELOPMENT.md). -### Security +## Validation and Troubleshooting -- **Secret Management**: Use proper secret management systems -- **Access Control**: Limit access to configuration files -- **Encryption**: Encrypt sensitive configuration data -- **Audit Logging**: Log configuration changes +At startup, the application validates YAML parsing, connector `class` and `module` fields, +and the required datasource URL when JWT validation is enabled. Individual connectors may +perform additional validation. -### Performance +Common checks: -- **Caching**: Cache configuration data appropriately -- **Lazy Loading**: Load configuration sections on demand -- **Validation**: Validate configuration early in startup -- **Monitoring**: Monitor configuration-related metrics +- Confirm YAML indentation and mapping structure. +- Confirm connector module paths are relative to `src/`. +- Confirm configured audio files exist under `audio/`. +- Confirm AWS credentials and region through the standard AWS SDK chain. +- Confirm the datasource URL exactly matches the registered value. +- Review `logs/gateway.log` and standard output for startup failures. -## License +## Related Documentation -This code is licensed under the [Cisco Sample Code License v1.1](../LICENSE). See the main project README for details. \ No newline at end of file +- [Local development](../docs/LOCAL_DEVELOPMENT.md) +- [Local audio configuration](../docs/LOCAL_AUDIO_CONFIGURATION.md) +- [JWT authentication](../docs/JWT_AUTHENTICATION.md) +- [Testing](../docs/TESTING.md) +- [Return to the project README](../README.md) diff --git a/docs/CUSTOMER_EVALUATION.md b/docs/CUSTOMER_EVALUATION.md new file mode 100644 index 0000000..2e89237 --- /dev/null +++ b/docs/CUSTOMER_EVALUATION.md @@ -0,0 +1,107 @@ +# Evaluating BYOVA for Your Existing Voice Agent + +This guide is for Webex Contact Center customers and implementation partners deciding +whether to connect an existing voice virtual agent through BYOVA. It explains where this +gateway fits, what each party typically owns, and what to prove before investing in +production engineering. + +This repository is functional sample code. It is not a managed connector, a supported +deployment architecture, or a Cisco-certified production capacity baseline. + +## How the Gateway Fits + +![BYOVA gateway architecture showing the runtime media path and onboarding control plane](images/byova-gateway-overview.drawio.svg) + +BYOVA lets Webex Contact Center stream caller audio and conversation events to an external +voice virtual agent through a secure, bidirectional gRPC interface. This gateway implements +the Webex-facing interface and translates between the BYOVA protocol and a +provider-specific connector. Your voice agent remains in the environment where you or your +provider operate it. + +At runtime, Webex connects to the registered gateway endpoint, the gateway validates the +signed request token, and the connector exchanges audio and events with the existing +voice-agent platform. BYOVA uses the BYODS control plane for Service App authorization and +data-source registration. + +## Is This Approach a Fit? + +Before adopting this example, confirm that: + +- Your voice-agent platform supports real-time voice interactions or exposes APIs from + which a real-time connector can be built. A text-only agent also needs an approved ASR/TTS + media layer. +- A connector can translate caller audio, responses, DTMF, conversation events, + cancellation, terminal events, and human escalation between BYOVA and your platform. +- The combined Webex Contact Center, gateway, network, and voice-agent path can meet your + caller-experience latency and audio-quality requirements. +- Your provider can support the expected concurrent sessions, regional deployment, quotas, + data residency, and production support model. +- You can operate a public TLS endpoint on an authorized domain and own its security, + monitoring, incident response, and capacity. +- Current Webex Contact Center licensing, entitlement, platform, region, language, codec, + and transcript requirements support your use case. + +Webex capabilities and commercial availability can change. Confirm current requirements in +the [BYOVA developer guide](https://developer.webex.com/webex-contact-center/docs/bring-your-own-virtual-agent), +the [Virtual Agent-Voice configuration guide](https://help.webex.com/en-us/article/n6gaghu/Configure-Virtual-Agent-Voice-in-Webex-Contact-Center), +and with your Cisco account or support team before committing to a production design. + +## Typical Responsibilities + +| Party | Typical responsibility | +| --- | --- | +| Webex Contact Center | Webex media path, BYOVA schema and interface, BYODS authorization framework, and Control Hub and Flow Designer capabilities. | +| Customer or implementation partner | Gateway connector, deployment, public endpoint, configuration, security, scaling, observability, on-call operations, and compliance. | +| Voice-agent provider | Voice-agent runtime, APIs or SDKs, quotas, latency, availability, regional support, credentials, and provider-side troubleshooting. | +| Customer administrator | Service App authorization, data-source approval, Contact Center AI configuration, and production call-flow changes. | + +Confirm the support boundary for your specific commercial agreement. The customer or +implementation partner owns production architecture, sizing, hardening, and operations for +a derivative of this sample. + +## Before You Start + +1. Confirm that BYOVA is available and entitled for the target Webex Contact Center + organization and region. +2. Obtain a sandbox or nonproduction organization for development. +3. Decide who will own the Service App, public gateway endpoint, and voice-agent connector. +4. Create and authorize the Service App, including the Voice Virtual Agent schema and the + gateway's data exchange domain. +5. Make the gateway available at a public TLS-enabled server URL, then register an `ACTIVE` + BYOVA data source using that exact URL. Use the same value for + `jwt_validation.datasource_url` in the gateway configuration. +6. Configure Contact Center AI and add the Virtual Agent V2 activity to a test flow. + +Use the current [Service App authorization steps](https://help.webex.com/default/article/5g8s6u), +[BYODS guide](https://developer.webex.com/webex-contact-center/docs/bring-your-own-data-source-cc), +and [BYOVA developer guide](https://developer.webex.com/webex-contact-center/docs/bring-your-own-virtual-agent) +for the Webex onboarding flow. + +For a complete first-time walkthrough, including these dependencies in the required order, +follow the +[BYOVA with AWS Lex setup guide](https://developer.webex.com/webex-contact-center/docs/byova-and-aws-lex). + +## Recommended Proof of Concept + +1. Follow the [Local Audio Connector Configuration](LOCAL_AUDIO_CONFIGURATION.md) guide to + validate the Webex-facing setup without a voice-agent provider. +2. Implement a connector for the existing voice-agent API or streaming interface. +3. Verify agent discovery and complete a live end-to-end test call. +4. Validate caller speech, response audio, DTMF, cancellation, normal termination, and + human-agent escalation. +5. Measure time to first virtual-agent audio, turn latency, audio quality, and connector + errors under representative traffic. +6. Test invalid authentication, voice-agent timeout, dependency failure, and cleanup. +7. Obtain business and technical acceptance before starting production engineering. + +After the proof of concept succeeds, use the +[Productization and Production Readiness Guide](PRODUCTION_READINESS.md) to plan the +engineering and operational work required for production. + +## Next Steps + +- [Set up the gateway locally](LOCAL_DEVELOPMENT.md) +- [Validate with the local audio connector](LOCAL_AUDIO_CONFIGURATION.md) +- [Configure gRPC JWT authentication](JWT_AUTHENTICATION.md) +- [Review the AWS Lex example](https://developer.webex.com/webex-contact-center/docs/byova-and-aws-lex) +- [Return to the project README](../README.md) diff --git a/docs/JWT_AUTHENTICATION.md b/docs/JWT_AUTHENTICATION.md new file mode 100644 index 0000000..a03c05b --- /dev/null +++ b/docs/JWT_AUTHENTICATION.md @@ -0,0 +1,170 @@ +# gRPC JWT Authentication + +The gateway validates signed JWTs on inbound gRPC requests from Webex Contact Center. This +protects the BYOVA data plane and is separate from the Webex OAuth login used by the optional +monitoring dashboard. + +For dashboard authentication, see +[Authentication Quick Start](../AUTHENTICATION_QUICKSTART.md) and the +[Monitoring Interface documentation](../src/monitoring/README.md). + +## What the Gateway Validates + +When validation is enabled, the gateway: + +- Reads a token from the gRPC `authorization` metadata entry. +- Accepts `Bearer ` and raw-token formats. +- Allows only the Webex identity-broker issuers listed in + `src/auth/jwt_validator.py` before fetching signing keys. +- Verifies the RS256 signature and expiration. +- Requires nonempty `aud`, `sub`, and `jti` claims. +- Requires the datasource URL and schema claims to match the configured values. +- Caches identity-broker public keys for the configured duration. + +With enforcement enabled, missing or invalid credentials are rejected before the RPC reaches +the gateway service. + +## Configuration + +Configure `jwt_validation` in `config/config.yaml`: + +```yaml +jwt_validation: + enabled: true + enforce_validation: true + datasource_url: "https://your-gateway.example.com:443" + datasource_schema_uuid: "5397013b-7920-4ffc-807c-e8a3e0a18f43" + cache_duration_minutes: 60 +``` + +The gateway fails to start when validation is enabled and `datasource_url` is empty. + +### Datasource URL + +`datasource_url` must exactly match the URL registered through the +[Webex Data Sources API](https://developer.webex.com/webex-contact-center/docs/api/v1/data-sources). +The runtime token contains that URL as a claim, and the validator performs a +character-for-character comparison. + +These values are different: + +```text +https://gateway.example.com +https://gateway.example.com:443 +``` + +Copy the registered value rather than reconstructing it. Use the same URL when a temporary +development endpoint changes. + +### Datasource Schema UUID + +The standard Voice Virtual Agent schema UUID used by this sample is: + +```text +5397013b-7920-4ffc-807c-e8a3e0a18f43 +``` + +It corresponds to the Voice Virtual Agent schema in the +[Webex dataSourceSchemas repository](https://github.com/webex/dataSourceSchemas). Change it +only when intentionally targeting a different approved schema. + +### Supported Issuers + +The current implementation accepts: + +- `https://idbrokerbts.webex.com/idb` +- `https://idbrokerbts-eu.webex.com/idb` +- `https://idbroker.webex.com/idb` +- `https://idbroker-eu.webex.com/idb` +- `https://idbroker-b-us.webex.com/idb` +- `https://idbroker-ca.webex.com/idb` + +`JWTValidator.VALID_ISSUERS` in `src/auth/jwt_validator.py` is the source of truth for the +running code. Treat issuer additions as security-sensitive code changes. + +## Deployment Modes + +### Local-Only Development + +For a local test that cannot receive a Webex token: + +```yaml +jwt_validation: + enabled: false +``` + +Do not expose that configuration to Webex or use it in production. + +### Validation Observation + +For a controlled nonproduction rollout, validation can run without rejecting invalid tokens: + +```yaml +jwt_validation: + enabled: true + enforce_validation: false + datasource_url: "https://your-test-gateway.example.com:443" +``` + +This mode logs validation failures but permits the request. Protect access to the logs, and +use this mode only for a time-bounded validation exercise. + +### Production + +```yaml +jwt_validation: + enabled: true + enforce_validation: true + datasource_url: "https://your-production-gateway.example.com:443" + datasource_schema_uuid: "5397013b-7920-4ffc-807c-e8a3e0a18f43" + cache_duration_minutes: 60 +``` + +Production deployments should also enforce TLS, restrict network paths, monitor validation +failures, and alert on identity-key refresh failures. See +[Security Configuration](Security-Configuration.md) and +[Production Readiness](PRODUCTION_READINESS.md). + +## Troubleshooting + +### Gateway Fails to Start + +If validation is enabled, configure a nonempty datasource URL. The value must be the actual +registered endpoint, not a placeholder. + +### Missing JWT Token + +- Confirm that the data source is registered and active. +- Confirm that the request reaches the gateway through the expected Webex path. +- Check for an `authorization` metadata value. +- Verify that a proxy or load balancer preserves gRPC metadata. + +### Invalid Signature or Public-Key Fetch Failure + +- Confirm outbound HTTPS access to the relevant Webex identity broker. +- Confirm system time is synchronized. +- Check the issuer and key-refresh logs. +- Do not add an issuer simply to bypass a validation failure. + +### Invalid Issuer + +Compare the token issuer with `JWTValidator.VALID_ISSUERS`. The validator checks the issuer +before making a key request to prevent arbitrary key-fetch URLs. + +### Datasource Claims Validation Failed + +- Copy the exact registered datasource URL into the configuration. +- Check whether the registered URL includes `:443` or a trailing path. +- Confirm the token schema UUID matches the configured Voice Virtual Agent schema. + +### Expired Token + +Confirm system clock synchronization. If Webex continues to send expired tokens, preserve a +tracking ID and timestamp and escalate through the appropriate Webex support channel. + +## Related Documentation + +- [BYOVA customer evaluation](CUSTOMER_EVALUATION.md) +- [Configuration reference](../config/README.md) +- [Local development](LOCAL_DEVELOPMENT.md) +- [Return to the project README](../README.md) diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md new file mode 100644 index 0000000..5243f8b --- /dev/null +++ b/docs/LOCAL_DEVELOPMENT.md @@ -0,0 +1,208 @@ +# Local Development Guide + +This guide covers local installation, development-only configuration, running the gateway, +the monitoring interface, public endpoint testing, and common local problems. + +## Prerequisites + +- Python 3.8 or later +- macOS, Linux, or Windows + +Always use a virtual environment for this project. + +These local prerequisites are sufficient only for running the code and its local connector. +An end-to-end WxCC test also requires a BYOVA-enabled organization, an authorized Service +App, a public TLS-enabled gateway URL, an `ACTIVE` data-source registration for that exact +URL, a configured gateway connector, and a Contact Center flow using Virtual Agent V2. +Use the [Local Audio Connector Configuration](LOCAL_AUDIO_CONFIGURATION.md) guide for a +vendor-neutral sandbox validation. For a complete AWS Lex integration, follow the +[BYOVA with AWS Lex guide](https://developer.webex.com/webex-contact-center/docs/byova-and-aws-lex) +before attempting an end-to-end call. + +## Install + +1. Clone the repository: + + ```bash + git clone https://github.com/webex/webex-byova-gateway-python.git + cd webex-byova-gateway-python + ``` + +2. Create and activate a virtual environment: + + ```bash + python -m venv venv + source venv/bin/activate + ``` + + On Windows: + + ```text + venv\Scripts\activate + ``` + +3. Install dependencies: + + ```bash + python -m pip install -r requirements.txt + ``` + +4. Generate the Python gRPC stubs: + + ```bash + python -m grpc_tools.protoc \ + -I./proto \ + --python_out=src/generated \ + --grpc_python_out=src/generated \ + proto/*.proto + ``` + +The generated `*_pb2.py` and `*_pb2_grpc.py` files are intentionally not committed. + +## Configure a Local-Only Run + +The checked-in configuration enables gRPC JWT validation but does not contain a datasource +URL. This is intentional for security: the gateway refuses to start with incomplete enabled +JWT configuration. + +For a local-only test that is not connected to Webex, edit `config/config.yaml` and set: + +```yaml +authentication: + enabled: false + +jwt_validation: + enabled: false +``` + +Do not use those settings for a Webex-connected or production endpoint. For end-to-end +testing, configure the registered datasource URL and keep JWT enforcement enabled as +described in [JWT Authentication](JWT_AUTHENTICATION.md). + +The default local audio files are included in `audio/`, so no additional media setup is +required for the local connector. See +[Local Audio Connector Configuration](LOCAL_AUDIO_CONFIGURATION.md) for its `agent_id`, +audio path, DTMF behavior, and end-to-end sandbox flow. + +## Run the Gateway + +With the virtual environment active: + +```bash +python main.py +``` + +The process starts: + +- The gRPC server on `localhost:50051` +- The monitoring interface on `http://localhost:8080` + +Press `Ctrl+C` to stop the gateway and allow it to clean up active conversations. + +## Monitoring Interface + +For a local run with dashboard authentication disabled, open: + +- Dashboard: `http://localhost:8080` +- Status: `http://localhost:8080/api/status` +- Connections: `http://localhost:8080/api/connections` +- HTTP health: `http://localhost:8080/health` + +For the dashboard's Webex OAuth setup and security model, see: + +- [Authentication Quick Start](../AUTHENTICATION_QUICKSTART.md) +- [Monitoring Interface](../src/monitoring/README.md) + +The dashboard is a development and diagnostic interface. Review the +[Production Readiness Guide](PRODUCTION_READINESS.md) before exposing any administrative +interface in production. + +## Test Through a Public Endpoint + +BYOVA requires a publicly reachable TLS endpoint on the domain authorized for the Service +App. Use company-owned cloud infrastructure for production and whenever company ownership, +security review, or compliance is required. + +For temporary development testing, a tunneling service may be usable if your organization +permits it. For example, with ngrok: + +```bash +ngrok config add-authtoken YOUR_AUTHTOKEN +ngrok http --upstream-protocol=http2 50051 +``` + +Use the generated HTTPS URL consistently in both the data-source registration and +`jwt_validation.datasource_url`. Free tunnel URLs may change between runs. + +Consumer tunnels are development-only: + +- Anyone with the URL can reach the exposed endpoint. +- Do not expose production credentials or caller data. +- Confirm HTTP/2 and bidirectional gRPC behavior before troubleshooting the application. +- Follow your organization's network and data-handling policies. + +See [Security Configuration](Security-Configuration.md) for a company-controlled TLS and +load-balancer starting point. + +## Troubleshooting + +### The Gateway Fails With an Empty Datasource URL + +If JWT validation is enabled, `jwt_validation.datasource_url` is required. For local-only +testing, disable JWT validation. For Webex-connected testing, configure the exact registered +URL. See [JWT Authentication](JWT_AUTHENTICATION.md). + +### Port 50051 or 8080 Is Already in Use + +Find the process using the port: + +```bash +lsof -i :50051 +lsof -i :8080 +``` + +Stop the conflicting application or change the corresponding port in +`config/config.yaml`. + +### Python or Imports Cannot Be Found + +Confirm the virtual environment is active: + +```bash +echo "$VIRTUAL_ENV" +which python +``` + +If necessary, recreate it: + +```bash +python -m venv venv +source venv/bin/activate +python -m pip install -r requirements.txt +``` + +### Generated Modules Cannot Be Imported + +Regenerate the gRPC files: + +```bash +python -m grpc_tools.protoc \ + -I./proto \ + --python_out=src/generated \ + --grpc_python_out=src/generated \ + proto/*.proto +``` + +### Review Logs + +The gateway logs to standard output and, when configured, `logs/gateway.log`. The monitoring +application uses `logs/web.log`. Adjust logging levels in `config/config.yaml`; do not enable +unsafe payload or audio logging with customer traffic. + +## Related Documentation + +- [Configuration](../config/README.md) +- [Local audio connector configuration](LOCAL_AUDIO_CONFIGURATION.md) +- [Testing](TESTING.md) +- [Connector development](../src/connectors/README.md) +- [Return to the project README](../README.md) diff --git a/docs/PRODUCTION_READINESS.md b/docs/PRODUCTION_READINESS.md new file mode 100644 index 0000000..124c68f --- /dev/null +++ b/docs/PRODUCTION_READINESS.md @@ -0,0 +1,530 @@ +# Productization and Production Readiness Guide + +## Purpose and scope + +This repository is a functional BYOVA gateway example. It demonstrates the Webex +Contact Center gRPC contract, connector routing, JWT validation, health checks, and a +development monitoring interface. It is not a turnkey production service and has not +been capacity-certified for a particular call volume. + +This guide is for engineering, platform, security, and operations teams after they have +successfully validated their BYOVA integration in a proof of concept. Customer evaluation, +compatibility questions, Webex onboarding, and the proof-of-concept path are covered in the +[Customer Evaluation Guide](CUSTOMER_EVALUATION.md). + +The sections below describe the engineering, security, reliability, and operating +capabilities that a customer or implementation partner should add before using a derivative +of this gateway in a high-volume contact center. This is a requirements and planning guide, +not a supported deployment architecture or a substitute for the responsible organization's +architecture, security, privacy, and operational reviews. + +CPU, memory, worker, stream, and session values in the sample configuration are runtime +defaults, not production sizing recommendations. Production values must be established +by representative load and failure testing. + +## Production readiness at a glance + +The production service should provide all of the following: + +- Multiple instances across independent failure zones, with no single-instance dependency. +- Capacity validated against peak concurrent calls, call-arrival bursts, and vendor latency. +- Structured logs, metrics, and distributed traces correlated by tracking identifiers. +- Service-level objectives (SLOs), actionable alerts, PagerDuty or equivalent routing, and + owned runbooks. +- Explicit timeouts, bounded retries, backpressure, circuit breakers, and graceful draining. +- Enforced authentication, encrypted transport, least-privilege access, and managed secrets. +- Privacy controls for caller data, transcripts, DTMF, tokens, and recorded audio. +- Automated builds, security scanning, staged releases, rollback, and disaster recovery. +- A staffed service ownership model with incident response and change-management processes. + +## Current example versus a production service + +| Area | Current example | Production requirement | +| --- | --- | --- | +| Metrics | Configuration includes `metrics_enabled`, and the Prometheus client is a dependency, but the gateway does not currently publish an instrumented metrics endpoint. | Export application, connector, runtime, and infrastructure metrics to the company's monitoring platform. | +| Logging | Human-readable console and local file logs. Some messages include a conversation ID. | Structured JSON logs with consistent tracking IDs, safe fields, centralized collection, retention, and access controls. | +| Tracing | No end-to-end distributed tracing. | OpenTelemetry or an equivalent standard across gRPC handling, routing, and vendor calls. | +| Alerting | No production alert routing or on-call integration. | SLO-based alerts routed to PagerDuty or the company's on-call platform with escalation policies and runbooks. | +| State | Active conversations, recent events, and dashboard history are held in process memory. | Define reconnect and failover semantics; externalize the state that must survive instance loss or use a deliberately tested affinity strategy. | +| Capacity | The gRPC thread pool and concurrent-stream settings are hard-coded. Sample session limits are not a validated capacity model. | Configurable limits established through load tests, with admission control, autoscaling, and headroom. | +| Health | gRPC health primarily reflects whether agents are registered. The HTTP endpoint is a simple process health response. | Separate startup, liveness, readiness, and dependency health; readiness must consider draining, saturation, and critical connector availability. | +| Deployment | A single Python process also starts a Flask development monitoring thread. | Independently operable workloads, production process servers, immutable artifacts, multi-zone placement, and controlled rollout. | +| Transport | The application binds an insecure gRPC port and relies on deployment infrastructure for TLS. | TLS 1.2 or later on every untrusted hop, verified HTTP/2 behavior, certificate automation, and documented trust boundaries. | +| Operations | Local dashboard and recent in-memory events aid development. | Central dashboards, SLOs, alerts, runbooks, incident command, support ownership, and audit history. | + +The sections below turn these gaps into a production program. + +## 1. Establish service ownership and reliability objectives + +Before choosing infrastructure, identify the business impact and the team that owns the +gateway in production. + +### Required ownership decisions + +- Name a service owner, engineering owner, security owner, and an operational owner with + on-call coverage aligned to the service's hours and business impact. +- Define which team owns each connector and each upstream virtual-agent dependency. +- Document the boundary between the company, Webex Contact Center, the cloud platform, + and the virtual-agent vendor. +- Define support tiers, escalation paths, maintenance windows, and change approvers. +- Create a service catalog entry containing dashboards, logs, traces, deployment links, + PagerDuty service, runbooks, dependency owners, and architecture documentation. + +### Define service-level indicators + +At minimum, measure: + +- Gateway availability: valid RPCs that receive a usable response rather than an + infrastructure or gateway error. +- Session-start success: conversations that start and reach the selected connector. +- Turn success: caller turns that produce a valid response or an intentional terminal event. +- Time to first virtual-agent audio: from caller turn completion to the first response audio. +- End-to-end turn latency: from accepted caller input to the final response event. +- Session completion quality: normal completion, human escalation, caller abandonment, + timeout, connector failure, and forced cleanup. +- Reconnection success, if reconnection is a supported behavior. + +Set SLOs and an error-budget policy for these indicators. Availability and latency targets +must reflect the contact center's business requirements and the dependencies' own SLOs. +Do not adopt generic targets without validating that the complete call path can meet them. + +## 2. Design for high availability and horizontal scale + +### Deployment topology + +- Run multiple gateway instances across at least two independent failure zones. +- Place instances behind a production load balancer or ingress that explicitly supports + long-lived bidirectional gRPC streams over HTTP/2. +- Keep application instances private where possible. Expose only the load balancer and + required administrative endpoints. +- Isolate the operational dashboard from the public gRPC data plane. Prefer a separate + administrative service protected by company SSO, role-based access, and network policy. +- Ensure a failure in the dashboard or telemetry exporter cannot terminate or starve call + processing. + +### Conversation state and routing + +The sample stores `ConversationProcessor` and connector session state in memory. A stream +continues on its current instance, but a reconnect or instance failure can lose that state. +Productization therefore requires an explicit decision: + +1. Make reconnectable state external and safely reconstruct connector sessions on another + instance; or +2. Use session affinity for reconnects, accept that instance loss terminates affected calls, + and document and test that failure behavior. + +Do not externalize raw streaming audio by default. Persist only the minimum state needed for +the chosen recovery model, protect it as customer data, and apply short, documented TTLs. +Prevent simultaneous ownership of the same conversation by using idempotency keys, leases, +or another concurrency-control mechanism. + +### Capacity model + +Model capacity from traffic measurements rather than configuration defaults: + +```text +peak concurrent sessions = peak session starts per second + x average virtual-agent session duration + x burst and safety factor +``` + +Also model the number of simultaneous turns, audio bitrate, vendor response time, TLS and JWT +cost, connection churn, reconnect storms, and telemetry volume. Test at expected peak, peak +plus headroom, and instance-loss conditions. + +Autoscaling should consider active streams, available session slots, worker/queue saturation, +memory, and connector throttling. CPU alone is not sufficient for long-lived streaming calls. +Keep reserve capacity so losing a zone or deploying a new version does not exhaust the fleet. + +### Runtime and connector concurrency + +The current synchronous gRPC server uses a thread pool, and the router can share a connector +instance across multiple agents and conversations. Before raising concurrency: + +- Audit all conversation maps, monitoring collections, audio buffers, connector clients, and + session managers for concurrent access and race conditions. +- Require connector implementations to document and test their thread-safety model. +- Keep per-conversation state isolated; protect genuinely shared state with appropriate + synchronization and avoid holding locks during network or audio operations. +- Profile blocking vendor calls and CPU-heavy audio conversion. Use bounded pools, processes, + or an asynchronous gRPC design where benchmark evidence shows they are needed. +- Run race, cancellation, and cleanup tests with many simultaneous streams. Confirm that one + slow connector call cannot consume every worker and block unrelated conversations. + +### Admission control and graceful lifecycle + +- Enforce configurable per-instance and fleet-wide concurrency limits. +- Apply per-tenant and per-connector quotas so one customer or dependency cannot exhaust the + shared fleet. +- Reject overload quickly with an intentional gRPC status instead of accepting work that + will time out later. +- Bound all internal queues and audio buffers. +- On shutdown or deployment, fail readiness first, stop accepting new calls, allow existing + streams to drain for a defined maximum period, then close remaining sessions cleanly. +- Align application drain time with load-balancer deregistration delay and orchestrator + termination grace periods. +- Test rolling deployments while the system is carrying representative calls. + +## 3. Add production metrics + +Expose metrics in Prometheus or OpenTelemetry format and send them to the company's durable +monitoring platform. Metrics must remain useful across many instances and deployments. + +### Gateway and gRPC metrics + +- Active, opening, completed, cancelled, and rejected streams. +- RPC request count and duration by method and gRPC status. +- Session starts, active sessions, duration, reconnects, and forced cleanup. +- Caller turns and response turns. +- Time to first virtual-agent audio and total turn latency. +- Bytes and audio duration received and sent. +- Invalid messages, protocol errors, stream cancellations, and deadline expirations. +- Human escalation attempts, successes, failures, and time to escalation. +- Session outcomes by a bounded outcome set. + +### Connector metrics + +- Operation count, error rate, and latency by connector and operation. +- Connection/setup failures, authentication failures, throttling, and vendor error category. +- Retry count, circuit-breaker state, timeout count, and dependency availability. +- Vendor response latency and time to first audio. +- Active vendor sessions and orphaned-session cleanup. +- Audio-buffer depth, dropped audio, and buffer underruns/overruns where applicable. + +### Runtime and infrastructure metrics + +- CPU, memory, file descriptors, threads, network throughput, and connection count. +- Worker utilization, queue depth, rejected work, and configured versus available capacity. +- Process restarts, out-of-memory kills, deployment version, and instance readiness. +- Load-balancer target health, connection errors, TLS errors, and response codes. +- External state-store latency, errors, capacity, and expiration behavior if one is used. + +### Authentication and configuration metrics + +- JWT validation success and failure by a bounded reason category. +- Identity public-key fetch failures, refresh latency, and cache age. +- Certificate expiry and rotation failures. +- Configuration load/reload failures and invalid connector definitions. + +Never put a conversation ID, tracking ID, caller identifier, organization ID, or other +unbounded value into a metric label. These create high cardinality and can expose customer +data. Use metrics for aggregation and logs or traces for individual-call investigation. + +## 4. Implement structured logging and tracking IDs + +Use structured JSON logs written to standard output and collected by the platform. Local +rotating files should not be the authoritative production log store. + +### Correlation model + +For every RPC and conversation: + +- Accept an approved inbound tracking or correlation ID from gRPC metadata when present. +- Validate its format and length. Generate a new cryptographically random ID when absent. +- Carry the ID through the gRPC interceptor, gateway server, conversation processor, + router, and connector. +- Propagate it to vendor requests using the vendor's supported request metadata or headers. +- Include OpenTelemetry `trace_id` and `span_id` when tracing is enabled. +- Return a safe tracking ID in response metadata or trailers when the protocol permits it, + so support teams can correlate both sides of a failure. + +Recommended event fields include: + +```text +timestamp, severity, service, environment, version, instance_id, +event_name, message, tracking_id, trace_id, span_id, conversation_id, +rpc_session_id, connector, virtual_agent_id, rpc_method, grpc_status, +session_outcome, duration_ms, retry_count, error_type +``` + +Conversation and organization identifiers should be pseudonymized or tokenized if operators +do not need the raw value. Use RFC 3339 UTC timestamps and consistent event names and error +categories. Log state transitions once at the correct severity rather than emitting entire +request or response objects. + +### Sensitive-data rules + +Production logs must not contain: + +- JWTs, OAuth tokens, API keys, cookies, or authorization metadata. +- Raw audio, transcripts, or prompt/response content unless a separately approved and + access-controlled diagnostic workflow requires it. +- DTMF digits, because callers may enter account or payment information. +- Full caller identifiers or unnecessary customer profile data. +- Vendor payloads that may contain personal or regulated data. + +Add automated redaction and tests for secrets and personal data. Define retention by data +class and environment, encrypt logs in transit and at rest, audit access, and provide a +documented deletion process. Debug logging must be time-bounded, authorized, and safe to +enable on a subset of instances without exposing caller content. + +## 5. Add distributed tracing + +Instrument the gateway with OpenTelemetry or the company's standard tracing framework. +Create spans for: + +- Authentication and JWT public-key lookup. +- `ListVirtualAgents` and `ProcessCallerInput` stream lifecycle. +- Conversation start, caller turn, connector routing, vendor request, response conversion, + escalation, and cleanup. +- State-store operations and retry attempts. + +Propagate W3C Trace Context where dependencies support it. Use span links or events for a +long-lived stream rather than one unbounded, high-volume span containing every audio chunk. +Sample successful traffic at a controlled rate while retaining errors and unusually slow +transactions. Apply the same sensitive-data restrictions used for logs. + +## 6. Build actionable dashboards and on-call alerting + +### Dashboards + +Maintain at least three views: + +1. **Service overview:** traffic, availability, error-budget burn, latency percentiles, + active calls, call outcomes, deployments, and dependency health. +2. **Capacity:** active versus allowed sessions, workers, queue depth, memory, network, + autoscaling state, and zone distribution. +3. **Connector detail:** request rate, errors, throttling, timeouts, latency, circuit state, + and escalation outcomes for each vendor. + +Operators must be able to filter by environment, region, zone, version, connector, RPC +method, and bounded error category. Add deployment and configuration-change annotations. + +### PagerDuty or equivalent integration + +Create a dedicated service in PagerDuty or the company's standard on-call platform, owned by +the team operating the gateway. Configure: + +- Primary and secondary on-call schedules and a management escalation path. +- Event deduplication, grouping, acknowledgement, and automatic resolution. +- Links from every page to the relevant dashboard, logs, traces, deployment, and runbook. +- A tested path for the monitoring platform and critical vendor alerts to create incidents. +- Quarterly contact and escalation-policy reviews. + +Page on user impact or imminent loss of capacity, not every internal error. Good paging +signals include: + +- Fast or slow SLO error-budget burn for gateway availability or session-start success. +- No ready instances in a region or insufficient capacity after loss of an instance or zone. +- Sustained error or timeout rate on a critical connector. +- Severe time-to-first-audio or turn-latency degradation. +- Session count near the safe limit with rejected calls or saturated workers/queues. +- A growing number of stuck or orphaned conversations. +- Widespread JWT validation or identity-key refresh failure. +- Imminent certificate expiry when automated renewal has failed. + +Use lower-severity notifications or tickets for single-instance restarts, brief dependency +errors, capacity trends, and non-urgent certificate warnings. Derive thresholds from SLOs, +capacity tests, and real baselines; avoid arbitrary static thresholds. + +Every paging alert needs a runbook covering impact, confirmation queries, dependencies, +safe mitigation, rollback, escalation, customer communication, and recovery verification. +Test alerts end to end before launch and during regular game days. + +## 7. Engineer dependency failure handling + +Every connector and network call must define: + +- Connection, request, idle-stream, and total-operation deadlines. +- Which failures are retryable and which are terminal. +- A small retry budget with exponential backoff and jitter. +- Idempotency behavior for conversation start, end, and escalation. +- Circuit-breaker thresholds and half-open recovery behavior. +- Per-connector concurrency limits and rate-limit handling. +- A safe caller experience when the vendor is unavailable, including human escalation or + controlled termination as agreed with the contact-center team. + +Retries must fit within the caller interaction deadline and must not amplify an outage. +Propagate cancellation and deadlines so abandoned calls stop consuming vendor and gateway +resources. Clean up vendor sessions on all terminal paths, including client cancellation, +instance shutdown, timeouts, and partial failures. + +## 8. Strengthen health checks + +Expose distinct checks for different consumers: + +- **Startup:** configuration is valid, required secrets are available, and connectors can + initialize. +- **Liveness:** the process is responsive and not deadlocked. Do not fail liveness solely + because a vendor is unavailable, or the orchestrator may create a restart storm. +- **Readiness:** the instance is not draining or saturated and can accept a new call. +- **Dependency health:** connector authentication, state store, identity-key service, and + other required dependencies are functioning within a recent time window. + +Avoid making every health probe perform a paid or expensive vendor transaction. Combine +passive health from actual calls with controlled synthetic checks. The load balancer should +use readiness, while operators and dashboards should see dependency detail separately. + +## 9. Harden security and privacy + +Use [Security Configuration](Security-Configuration.md) as a starting point, then complete a +formal threat model and security review. + +### Data plane + +- Enforce JWT validation in production and fail startup on unsafe or incomplete settings. +- Validate issuer, audience, expiry, datasource URL, schema UUID, and all required claims. +- Terminate TLS only at an approved trust boundary and encrypt traffic on additional + untrusted hops. Verify HTTP/2 and certificate hostname validation end to end. +- Apply request/message size limits, stream limits, rate limits, and malformed-input tests. +- Restrict network paths to expected Webex, vendor, identity, and telemetry endpoints. + +### Administrative plane + +- Put dashboards and debug endpoints behind company SSO, RBAC, MFA, and network controls. +- Remove or disable development/test endpoints in production. +- Do not expose active-session details broadly; treat them as customer operational data. +- Record administrative access and security-relevant configuration changes in an audit log. + +### Secrets and software supply chain + +- Store secrets in the platform's managed secret service, never in YAML, images, or logs. +- Use workload identity or short-lived credentials instead of static cloud access keys. +- Rotate credentials and certificates automatically and test rotation without call impact. +- Pin and scan dependencies, generate an SBOM, sign build artifacts, scan container images, + and remediate critical vulnerabilities within an agreed SLA. +- Run as a non-root user with a read-only filesystem and minimal Linux capabilities when + containerized. + +### Audio and regulated data + +Disable audio recording by default in production. If recording is required, obtain privacy +and legal approval and define consent, purpose, residency, encryption, access, retention, +deletion, and audit requirements. Store recordings outside the application container in an +approved encrypted service. Account for PCI DSS, HIPAA, GDPR, regional privacy rules, or +other obligations that apply to the contact center. + +## 10. Establish a production delivery process + +- Build immutable, versioned artifacts in CI from reviewed source. +- Run formatting, linting, type checks, unit tests, integration tests, dependency scans, + secret scans, and artifact/image scans on every change. +- Generate gRPC code deterministically and detect incompatible protocol changes. +- Validate configuration against a typed schema and reject unknown or unsafe values. +- Promote the same artifact through development, load, staging, canary, and production. +- Use canary or progressive delivery with automated health and SLO checks. +- Keep a tested one-step rollback path, including configuration rollback. +- Separate connector feature flags and emergency disable controls from code deployment. +- Require peer review and record who approved and deployed each production change. + +Deployment tests must include active streams. A successful process start or unary health +check does not prove that long-lived audio calls survive the rollout. + +## 11. Validate performance and resilience + +Create an automated load harness that behaves like real Webex traffic: long-lived +bidirectional gRPC streams, representative audio cadence and size, DTMF and event traffic, +JWT validation, connector calls, escalation, cancellation, and reconnect behavior. + +Test all of the following: + +- Expected peak, peak plus safety margin, sudden arrival bursts, and sustained soak traffic. +- One instance and one zone lost at peak traffic. +- Slow, throttled, unavailable, and partially failing connector dependencies. +- Expired/invalid JWTs and identity public-key refresh failure. +- Network latency, packet loss, disconnects, and reconnect storms. +- Rolling deployments, certificate rotation, secret rotation, and autoscaling events. +- Stuck streams, callers that never send a terminal event, and maximum session duration. +- Telemetry backend failure without impact to call handling. +- Disk, memory, file descriptor, thread, and network exhaustion. + +Measure caller-visible outcomes as well as server throughput. Confirm that the service sheds +load predictably, recovers without manual data repair, and does not leak sessions or memory +during a long soak test. + +Capacity-test reports should record artifact version, instance shape, replica count, limits, +traffic model, connector behavior, results, bottlenecks, and approved operating ceiling. +Repeat tests after changes to audio handling, connectors, concurrency, telemetry, runtime, +or infrastructure. + +## 12. Prepare incident response and disaster recovery + +Create version-controlled runbooks for at least: + +- High error rate or slow response. +- Connector outage, throttling, or credential failure. +- Capacity saturation and rejected calls. +- Stuck/orphaned sessions or memory growth. +- JWT validation or identity-key failure. +- Certificate expiry or TLS failure. +- Bad deployment or configuration change. +- Regional or state-store failure. +- Suspected data exposure or compromised credential. + +Define recovery time and recovery point objectives based on business requirements. Back up +only durable data that is actually required; ephemeral audio-stream state may not be +recoverable. Replicate configuration and required state to the recovery location, document +DNS/load-balancer failover, and test restoration and regional failover on a schedule. + +After incidents, preserve a timeline using tracking IDs, complete a blameless review, assign +corrective actions, and verify those actions through tests or game days. + +## 13. Control cost and data retention + +Forecast and monitor cost per concurrent session, call minute, and completed conversation. +Include compute, load balancing, NAT/network transfer, vendor usage, state storage, metrics, +logs, traces, and approved audio storage. Set budgets and anomaly alerts. + +Telemetry volume can be substantial for audio workloads. Use event-based logging, bounded +cardinality, trace sampling, and retention tiers. Cost controls must never silently remove +the minimum data required to detect incidents or investigate customer impact. + +## Recommended implementation sequence + +### Phase 1: Define the production contract + +- Confirm the proof-of-concept results and documented Webex, customer, and provider + responsibility boundaries. +- Assign owners and dependency boundaries. +- Define session/reconnect/failover semantics. +- Define SLIs, SLOs, error budgets, data classifications, and retention. +- Produce a threat model and target deployment architecture. + +### Phase 2: Make the service observable and bounded + +- Add tracking-ID propagation, structured safe logging, metrics, and traces. +- Add configurable concurrency limits, bounded buffers, deadlines, and admission control. +- Split startup, liveness, readiness, and dependency health. +- Create dashboards and capacity baselines. + +### Phase 3: Add resilience and secure delivery + +- Deploy across failure zones with drain-aware rolling updates. +- Implement the chosen session-state model, connector isolation, retries, and circuit breakers. +- Harden authentication, TLS, secrets, admin access, and the software supply chain. +- Build CI/CD, canary, rollback, and configuration validation. + +### Phase 4: Operationalize + +- Create the PagerDuty or equivalent on-call service, alert policies, escalation paths, and + runbooks. +- Run peak, soak, dependency-failure, and zone-failure tests. +- Train on-call responders and conduct game days. +- Complete security, privacy, architecture, and business launch reviews. + +## Production launch checklist + +The service is not ready for production until the customer or implementation partner can +answer **yes** to every applicable item: + +- [ ] The BYOVA proof of concept is complete and its functional, caller-experience, and + support-boundary results are accepted. +- [ ] A named team owns the service and provides the required on-call coverage. +- [ ] SLIs, SLOs, error budgets, and dependency objectives are approved. +- [ ] Representative peak, burst, soak, and failure tests establish a safe capacity limit. +- [ ] The fleet survives an instance and zone loss while carrying peak traffic. +- [ ] Concurrency limits, backpressure, bounded buffers, deadlines, and graceful draining work. +- [ ] Reconnect and instance-loss behavior are documented and tested. +- [ ] Metrics, structured logs, tracking IDs, and traces cover the full request path. +- [ ] Dashboards and PagerDuty or equivalent alerts have been tested end to end. +- [ ] Every paging alert links to an owned and exercised runbook. +- [ ] Readiness reflects draining and capacity; dependency failures are visible separately. +- [ ] JWT validation and TLS are enforced and certificate/key rotation has been tested. +- [ ] Secrets use managed storage and short-lived/workload credentials where possible. +- [ ] Debug/test endpoints and production audio logging are disabled or separately approved. +- [ ] Privacy, security, compliance, retention, and data-residency reviews are complete. +- [ ] CI/CD produces immutable scanned artifacts with canary and rollback support. +- [ ] Vendor quotas, throttling behavior, outage handling, and support escalation are documented. +- [ ] Disaster recovery meets approved recovery objectives and has been exercised. +- [ ] Cost budgets, anomaly detection, and telemetry retention are in place. +- [ ] Launch approval and residual risks are recorded by the accountable owners. diff --git a/docs/README.md b/docs/README.md index 9c791d0..2293d8d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,120 +1,59 @@ # Webex Contact Center BYOVA Gateway Documentation -Welcome to the comprehensive documentation for the Webex Contact Center BYOVA (Bring Your Own Virtual Agent) Gateway. This gateway enables seamless integration between Webex Contact Center and various virtual agent providers, including AWS Lex. +Use this index to find the guide for your current stage. The gateway is functional sample +code, not a managed connector or a production-ready service. -## 📚 Setup Guides +## Evaluate and Onboard -### Start Without a Voice-Agent Vendor -- **[Local Audio Connector Configuration](LOCAL_AUDIO_CONFIGURATION.md)** - Validate the gateway and a Webex Contact Center sandbox with bundled audio before choosing a provider +- [Customer Evaluation](CUSTOMER_EVALUATION.md): Determine whether BYOVA and this gateway fit + an existing voice-agent platform, understand responsibilities, and plan a proof of concept. +- [Official BYOVA Developer Guide](https://developer.webex.com/webex-contact-center/docs/bring-your-own-virtual-agent): + Current Webex concepts, Service App, data-source, and onboarding guidance. +- [BYOVA with AWS Lex](https://developer.webex.com/webex-contact-center/docs/byova-and-aws-lex): + Complete Webex Contact Center and AWS Lex walkthrough. -### Complete Integration Guide -- **[BYOVA with AWS Lex Setup Guide](https://developer.webex.com/webex-contact-center/docs/byova-and-aws-lex)** - Step-by-step guide for setting up voice AI with Webex Contact Center and AWS Lex +## Develop and Test -This comprehensive guide covers: -- Setting up a Webex Contact Center sandbox -- Configuring BYOVA and BYODS (Bring Your Own Data Source) -- Creating and configuring AWS Lex bots -- Deploying and configuring the BYOVA Gateway -- Testing your voice AI integration end-to-end +- [Local Audio Connector Configuration](LOCAL_AUDIO_CONFIGURATION.md): Validate the gateway + and a Webex Contact Center sandbox before selecting a voice-agent provider. +- [Local Development](LOCAL_DEVELOPMENT.md): Install, configure a local-only run, start the + gateway, use the monitoring interface, and troubleshoot development issues. +- [Configuration Reference](../config/README.md): Settings read by the current gateway and + connectors, including known sample-only placeholders. +- [Testing Guide](TESTING.md): Automated tests, HTTP smoke tests, gRPC health checks, and + end-to-end validation. +- [Connector Guide](../src/connectors/README.md): Connector interface, available connectors, + and extension pattern. +- [Monitoring Interface](../src/monitoring/README.md): Dashboard behavior, Webex OAuth, APIs, + and security considerations. -## 🚀 Quick Start +## Authenticate and Secure -For a quick test of the gateway with local audio: +- [gRPC JWT Authentication](JWT_AUTHENTICATION.md): Runtime Webex token validation, + datasource claims, deployment modes, and troubleshooting. +- [Monitoring Authentication Quick Start](../AUTHENTICATION_QUICKSTART.md): Configure Webex + OAuth for the development dashboard. +- [Security Configuration](Security-Configuration.md): TLS and load-balancer setup guidance. -1. **Clone and Setup** - ```bash - git clone https://github.com/webex/webex-byova-gateway-python.git - cd webex-byova-gateway-python - python -m venv venv - source venv/bin/activate - pip install -r requirements.txt - ``` +## Integrate Providers -2. **Generate gRPC Stubs** - ```bash - python -m grpc_tools.protoc -I./proto --python_out=src/generated --grpc_python_out=src/generated proto/*.proto - ``` +- [AWS Lex Configuration](AWS_LEX_CONFIGURATION.md): AWS credentials and Lex connector + settings. +- [Audio Files](../audio/README.md): Local audio formats and sample media. +- [Protocol Definitions](../proto/README.md): BYOVA and gRPC schema information. -3. **Start the Gateway** - ```bash - python main.py - ``` +## Prepare for Production -4. **Access Monitoring Interface** - - Open http://localhost:8080 in your browser +- [Productization and Production Readiness](PRODUCTION_READINESS.md): High availability, + capacity, observability, alerting, security, testing, incident response, and launch gates. -## 🏗️ Architecture +## Repository Entry Points -The BYOVA Gateway follows a modular architecture: +- [Project README](../README.md): Overview and quick start. +- [Core Gateway](../src/core/README.md): Core server and routing components. +- [Utilities](../src/utils/README.md): Audio buffer, conversion, recording, and logging helpers. +- [Test Suite Notes](../tests/README.md): Detailed test organization and markers. -- **gRPC Server**: Handles communication with Webex Contact Center -- **Virtual Agent Router**: Routes requests to appropriate connector implementations -- **Connectors**: Support for various virtual agent platforms - - Local Audio Connector (for testing) - - AWS Lex Connector (for production) -- **Web Monitoring Interface**: Real-time dashboard for monitoring and debugging +## License -## 🔧 Configuration - -The gateway is configured via `config/config.yaml`. Key configuration areas: - -- **Gateway Settings**: Host, port, and basic configuration -- **Connectors**: Virtual agent connector configurations -- **Monitoring**: Web interface settings -- **Logging**: Log levels and file management -- **Sessions**: Session management and cleanup - -## 📖 API Reference - -### gRPC Endpoints -- **ListVirtualAgents**: Returns available virtual agents -- **ProcessCallerInput**: Handles bidirectional streaming for voice interactions - -### HTTP Endpoints -- `GET /`: Main dashboard -- `GET /api/status`: Gateway status -- `GET /api/connections`: Connection data -- `GET /health`: Health check -- `GET /api/debug/sessions`: Debug information - -## 🔌 Connectors - -### Local Audio Connector -- **Purpose**: Testing and development with pre-recorded audio files -- **Configuration**: Audio file mapping and agent definitions -- **Use Case**: Initial testing and validation - -### AWS Lex Connector -- **Purpose**: Production integration with Amazon Lex v2 -- **Features**: Real-time voice AI, intent recognition, slot filling -- **Configuration**: AWS credentials, bot settings, audio processing - -## 🛠️ Development - -### Adding New Connectors -1. Create a new connector class in `src/connectors/` -2. Inherit from `IVendorConnector` -3. Implement required abstract methods -4. Add configuration to `config/config.yaml` -5. Restart the server - -### Testing -- Use the local audio connector for initial testing -- Monitor real-time data via the web interface -- Check logs for conversation flow and error conditions - -## 📞 Support - -For questions about BYOVA integration: -- Check the troubleshooting section in the setup guide -- Review the gateway logs and monitoring interface -- Consult the AWS Lex and Webex Contact Center documentation -- Reach out to the developer community for assistance - -## 📄 License - -[Cisco Sample Code License v1.1](LICENSE) © 2018 Cisco and/or its affiliates - ---- - -**Note**: This Sample Code is not supported by Cisco TAC and is not tested for quality or performance. This is intended for example purposes only and is provided by Cisco "AS IS" with all faults and without warranty or support of any kind. +[Cisco Sample Code License v1.1](../LICENSE) © 2018 Cisco and/or its affiliates. diff --git a/docs/TESTING.md b/docs/TESTING.md new file mode 100644 index 0000000..6edfdb4 --- /dev/null +++ b/docs/TESTING.md @@ -0,0 +1,165 @@ +# Testing Guide + +This guide covers the automated test suite and local smoke tests for the HTTP monitoring and +gRPC services. + +## Prerequisites + +Activate the project virtual environment and install dependencies: + +```bash +source venv/bin/activate +python -m pip install -r requirements.txt +``` + +Generate the gRPC stubs before tests or smoke checks that import generated modules: + +```bash +python -m grpc_tools.protoc \ + -I./proto \ + --python_out=src/generated \ + --grpc_python_out=src/generated \ + proto/*.proto +``` + +## Automated Tests + +Run the full suite with the repository test runner: + +```bash +python run_tests.py +``` + +Or invoke pytest directly: + +```bash +python -m pytest tests/ +``` + +Run a single file or test: + +```bash +python run_tests.py tests/test_jwt_validation.py +python run_tests.py tests/test_wxcc_gateway_server.py::TestConversationProcessor +``` + +List collected tests: + +```bash +python run_tests.py --list +``` + +The default suite uses mocks for external services. Tests marked `integration`, `aws`, or +`slow` may have additional requirements; inspect the selected test before running it against +real services. + +## Start a Local Test Server + +For local-only smoke tests, disable dashboard authentication and gRPC JWT validation as +described in [Local Development](LOCAL_DEVELOPMENT.md), then run: + +```bash +python main.py +``` + +Do not use disabled authentication for a public or production endpoint. + +## HTTP Smoke Tests + +With the gateway running: + +```bash +curl http://localhost:8080/api/status +curl http://localhost:8080/api/connections +curl http://localhost:8080/health +``` + +For dashboard behavior and OAuth testing, see the +[Monitoring Interface documentation](../src/monitoring/README.md). + +## gRPC Health Checks + +Use the included Python client: + +```bash +python test_health.py +``` + +Expected services include: + +- Overall gateway health +- `byova.gateway` +- `byova.VoiceVirtualAgentService` + +Health status values are `SERVING`, `NOT_SERVING`, or `SERVICE_UNKNOWN`. + +## Test With grpcurl + +The server does not enable gRPC reflection, so provide the local proto files. + +Overall health: + +```bash +grpcurl -plaintext \ + -import-path proto \ + -proto health.proto \ + localhost:50051 \ + grpc.health.v1.Health/Check +``` + +Gateway service health: + +```bash +grpcurl -plaintext \ + -import-path proto \ + -proto health.proto \ + -d '{"service":"byova.gateway"}' \ + localhost:50051 \ + grpc.health.v1.Health/Check +``` + +List the configured virtual agents: + +```bash +grpcurl -plaintext \ + -import-path proto \ + -proto voicevirtualagent.proto \ + -d '{"customerOrgId":"local-test"}' \ + localhost:50051 \ + com.cisco.wcc.ccai.media.v1.VoiceVirtualAgent/ListVirtualAgents +``` + +When JWT validation is enabled, add the valid runtime token as request metadata rather than +disabling enforcement: + +```text +-H 'authorization: Bearer ' +``` + +## End-to-End Validation + +A first vendor-neutral sandbox call can use the +[Local Audio Connector Configuration](LOCAL_AUDIO_CONFIGURATION.md) guide. It validates +agent discovery, prompt playback, DTMF transfer, and conversation termination without an +external voice-agent account. + +A production-candidate connector needs more than unit and health tests. Validate: + +- Agent discovery and conversation start +- Caller audio and response audio in both directions +- DTMF and input events +- Human-agent escalation and transcript behavior +- Normal termination, cancellation, timeout, and reconnect behavior +- Invalid authentication and dependency failure +- Caller-visible latency and audio quality under representative concurrency + +Use [Production Readiness](PRODUCTION_READINESS.md) for load, resilience, security, and +operational launch criteria. + +## Related Documentation + +- [Detailed test-suite notes](../tests/README.md) +- [Local development](LOCAL_DEVELOPMENT.md) +- [Local audio connector configuration](LOCAL_AUDIO_CONFIGURATION.md) +- [JWT authentication](JWT_AUTHENTICATION.md) +- [Return to the project README](../README.md) diff --git a/docs/images/byova-gateway-overview.drawio.svg b/docs/images/byova-gateway-overview.drawio.svg new file mode 100644 index 0000000..fc439bd --- /dev/null +++ b/docs/images/byova-gateway-overview.drawio.svg @@ -0,0 +1,4 @@ + + + +
Runtime voice path
Caller
Voice interaction
Webex Contact Center
Flow Designer / Virtual Agent V2
BYOVA Gateway
Customer or partner hosted
Existing Voice Agent
ASR / NLU / TTS and business logic
Voice call
Bidirectional gRPC
audio + events
Connector / provider API
Onboarding and control plane
Customer / partner
Administrator
Authorized Service App
Scopes and approved domain
BYOVA data source
Gateway URL and schema
Contact Center AI / Flow Designer
Virtual Agent V2 activity
Creates + authorizes
Registers
Configures
Registered endpoint
The customer or implementation partner operates the gateway and its connector to the existing voice-agent platform.
Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index d70c1c7..915c278 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,12 +9,7 @@ Welcome to the documentation for the Webex Contact Center BYOVA (Bring Your Own ## 🚀 Quick Start -If you have a Webex Contact Center sandbox but have not chosen a voice-agent -provider, start with the bundled local audio connector: - -**[📖 Local Audio Connector Configuration](LOCAL_AUDIO_CONFIGURATION.md)** - -For an Amazon Lex integration, use the comprehensive setup guide: +Get up and running in minutes with our comprehensive setup guide: **[📖 Complete Setup Guide](https://developer.webex.com/webex-contact-center/docs/byova-and-aws-lex)** @@ -36,14 +31,19 @@ A fully functional voice AI system where customers can: - **gRPC Integration**: Seamless communication with Webex Contact Center - **Modular Architecture**: Easy to extend with new virtual agent providers - **Real-time Monitoring**: Web dashboard for debugging and monitoring -- **Multiple Connectors**: Support for local audio testing and AWS Lex production +- **Multiple Connectors**: Support for local audio testing and AWS Lex integration - **Comprehensive Logging**: Detailed logs for troubleshooting and analysis ## 📚 Documentation -- **[Local Audio Connector Configuration](LOCAL_AUDIO_CONFIGURATION.md)** - Vendor-neutral first test with a Contact Center sandbox +- **[Customer Evaluation](CUSTOMER_EVALUATION.md)** - Determine whether BYOVA fits an existing voice-agent platform and plan a proof of concept +- **[Local Audio Connector Configuration](LOCAL_AUDIO_CONFIGURATION.md)** - Validate BYOVA with a Contact Center sandbox before choosing a voice-agent provider +- **[Local Development](LOCAL_DEVELOPMENT.md)** - Install, run, and troubleshoot the sample locally +- **[JWT Authentication](JWT_AUTHENTICATION.md)** - Configure Webex runtime token validation +- **[Testing](TESTING.md)** - Run automated, HTTP, gRPC, and end-to-end tests - **[Setup Guide](https://developer.webex.com/webex-contact-center/docs/byova-and-aws-lex)** - Complete step-by-step setup -- **[API Reference](api/)** - Detailed API documentation +- **[Productization and Production Readiness Guide](PRODUCTION_READINESS.md)** - Requirements for operating a derivative of this sample at high call volume +- **[Protocol Definitions](https://github.com/webex/webex-byova-gateway-python/tree/main/proto)** - BYOVA and health protocol source files - **[GitHub Repository](https://github.com/webex/webex-byova-gateway-python)** - Source code and issues ## 🛠️ Development @@ -65,6 +65,4 @@ For questions about BYOVA integration: --- -**Not sure which voice-agent provider to use?** [Begin with the Local Audio Connector](LOCAL_AUDIO_CONFIGURATION.md). - -**Using Amazon Lex?** [Follow the Complete Setup Guide](https://developer.webex.com/webex-contact-center/docs/byova-and-aws-lex). +**Ready to get started?** [Begin with the Complete Setup Guide](https://developer.webex.com/webex-contact-center/docs/byova-and-aws-lex) diff --git a/src/monitoring/README.md b/src/monitoring/README.md index 0be4951..042a797 100644 --- a/src/monitoring/README.md +++ b/src/monitoring/README.md @@ -261,9 +261,6 @@ When disabled, the dashboard is accessible without login. **Never disable authen - `GET /api/connections` - Active sessions and connection history - `GET /api/debug/sessions` - Detailed session debugging information -### Testing and Development -- `GET /api/test/create-session` - Create test session for UI testing - ## Dashboard Components ### Status Overview @@ -477,4 +474,4 @@ python main.py 2>&1 | grep "monitoring" ## License -This code is licensed under the [Cisco Sample Code License v1.1](../LICENSE). See the main project README for details. \ No newline at end of file +This code is licensed under the [Cisco Sample Code License v1.1](../../LICENSE). See the main project README for details.