1.1 Waka Company : L'Offre de Sous-Traitance IA

Modèle de Service

Types d'Opérations Sous-Traitées

1.2 L'Ambition : Déploiement en 30 Minutes

Parcours de Déploiement Express

Les Clés du Déploiement Rapide

1.3 Vision Technique : Les 3 Piliers

Pour atteindre cette promesse de déploiement rapide tout en garantissant une qualité d'interaction indiscernable d'un agent humain, Waka Voice repose sur trois piliers techniques fondamentaux.

Pilier 1 : Naturalité des Conversations

• Latence ultra-faible (<300ms) : Architecture WebSocket bidirectionnelle garantissant des temps de réponse imperceptibles
• Barge-in (interruption) : L'utilisateur peut interrompre l'agent à tout moment, comme dans une vraie conversation
• VAD sémantique : Détection intelligente de fin de phrase, même après une pause de réflexion
• Voix expressives : Voix Azure Neural avec émotions, intonations et styles adaptés au contexte

Pilier 2 : Puissance Agentique (Actions Réelles)

• Système de Tools extensible : 4 types (API REST, MCP, Python, OpenAPI) pour intégrer tout système client
• Raisonnement contextuel : GPT-5.2, Claude Opus 4.5, Grok 3 pour décisions intelligentes
• Chaînage d'actions : Vérification éligibilité → Calcul → Prise engagement → Confirmation, en une seule conversation

Pilier 3 : Multimodalité Intégrée

1.4 Fonctionnalités Détaillées

Waka Voice intègre un ensemble complet de fonctionnalités conçues pour couvrir l'ensemble du cycle de vie des agents conversationnels, de la création au déploiement en passant par l'analyse et l'optimisation.

Création d'agents

• Interface unifiée de création : Un wizard en 5 étapes guide l'utilisateur à travers le choix du type d'agent (voix/avatar/texte), la sélection du modèle IA, la configuration de la voix, l'assignation des tools et la rédaction des instructions.
• Prompt Builder intelligent : 4 méthodes de génération de prompts (templates métier, construction par phases, import existant, génération IA) garantissent des instructions optimales quelle que soit l'expertise de l'utilisateur.
• Bibliothèque de templates : Des templates pré-configurés pour les cas d'usage courants (recouvrement, support client, prise de RDV, enquêtes satisfaction) accélèrent le déploiement.
• Versioning et rollback : Chaque modification crée une version, permettant de revenir à une configuration précédente en cas de problème.

Gestion des voix

La voix est l'élément le plus critique pour la perception de naturalité. Waka Voice offre trois niveaux de personnalisation :

• Voix Azure Standard : Plus de 600 voix couvrant toutes les langues majeures. Qualité professionnelle suffisante pour la plupart des cas d'usage, avec un excellent rapport qualité/coût.
• Voix HD Neural : Voix premium avec expressions émotionnelles, styles de parole (joyeux, triste, professionnel) et qualité audio supérieure. Recommandées pour les interactions à forte valeur ajoutée.
• Voix Personnalisées : Création de voix uniques à partir d'enregistrements. Permet de reproduire la voix d'un porte-parole, créer une identité sonore de marque, ou offrir une voix familière aux utilisateurs.

Capacités agentiques (Tools)

Le système de Tools est ce qui transforme un simple chatbot en agent véritablement autonome. Chaque type de tool répond à des besoins spécifiques :

1.5 Public Cible et Cas d'Usage

Profils utilisateurs

Waka Voice s'adresse à trois profils principaux, chacun avec des besoins et des niveaux d'expertise différents :

Cas d'usage principaux

1.6 Stratégie Technique : Fondations

1.6.1 Pourquoi Azure comme Fondation ?

Le choix d'Azure comme plateforme cloud principale n'est pas anodin. Il résulte d'une analyse approfondie des alternatives (AWS, GCP, solutions on-premise) et de critères précis.

Critères de sélection

Comparaison avec les alternatives

1.6.2 Pourquoi Flask et Python ?

Le choix de Flask comme framework backend, associé à Python 3.13+, répond à des critères de productivité, de flexibilité et d'écosystème.

Arguments en faveur de Flask

• Légèreté et flexibilité : Contrairement à Django qui impose une structure, Flask permet une architecture sur mesure adaptée à nos besoins spécifiques (Blueprints modulaires, WebSocket via flask-sock, pas d'ORM imposé).
• Écosystème Python IA : Python domine l'écosystème IA/ML. Nos intégrations avec Azure Cognitive Services, OpenAI, et les bibliothèques de traitement audio bénéficient d'un support de première classe.
• Productivité de développement : Syntaxe claire, typage optionnel (utilisé via type hints), debugging facilité, hot-reload en développement. Temps de mise sur le marché réduit.
• Support WebSocket natif : flask-sock offre une intégration WebSocket élégante sans nécessiter de serveur séparé (vs Node.js + Socket.io).

Alternatives considérées et rejetées

1.6.3 Pourquoi Cosmos DB ?

Le choix de Cosmos DB comme base de données principale est motivé par les exigences spécifiques des agents conversationnels : données semi-structurées, latence faible, scalabilité globale.

Caractéristiques décisives

Modélisation des données

Notre modélisation suit le pattern "one-to-few" recommandé pour Cosmos DB : les documents sont auto-suffisants et contiennent toutes les données nécessaires pour éviter les jointures coûteuses.

// Exemple : Document Agent complet (pas de références externes)
{
  "id": "agent-uuid-12345",
  "partitionKey": "agent-uuid-12345",  // Partition = ID pour distribution optimale
  "type": "VoiceAgent",
  "metadata": {
    "name": "Agent Recouvrement Premium",
    "reference": "Agent-000042",
    "status": "active",
    "createdAt": "2025-12-29T10:00:00Z",
    "updatedAt": "2025-12-29T15:30:00Z",
    "createdBy": "user-uuid-xxx"
  },
  "configuration": {
    "model": {
      "id": "gpt-realtime",
      "family": "F1",
      "temperature": 0.7,
      "maxTokens": 2000
    },
    "voice": {
      "type": "azure_tts",
      "id": "fr-FR-DeniseNeural",
      "locale": "fr-FR"
    },
    "vad": {
      "type": "azure_semantic_vad",
      "threshold": 0.3,
      "silenceDurationMs": 300
    }
  },
  "instructions": "Tu es un agent de recouvrement professionnel...",
  "tools": [
    // Tools embarqués, pas de référence
    {
      "name": "check_client_status",
      "type": "api",
      "endpoint": "https://crm.example.com/api/clients/{id}/status"
    }
  ],
  "analytics": {
    "totalCalls": 1523,
    "avgDuration": 187,
    "successRate": 0.72
  }
}

1.6.4 Architecture Temps Réel : WebSocket Bidirectionnel

La conversation vocale en temps réel est le défi technique central de Waka Voice. Notre architecture de proxy WebSocket bidirectionnel est le résultat de nombreuses itérations pour atteindre les objectifs de latence et de fiabilité.

Pourquoi un proxy et pas une connexion directe ?

Une approche naïve connecterait directement le navigateur à Azure Voice Live API. Nous avons opté pour un proxy intermédiaire pour plusieurs raisons critiques :

• Sécurité des credentials : Les clés API Azure ne doivent jamais être exposées côté client. Le proxy garde les secrets côté serveur et authentifie chaque connexion.
• Exécution des Tools : Quand l'agent IA décide d'appeler un tool, cette exécution doit se faire côté serveur (appels API, accès BDD, code Python). Le proxy intercepte les tool_calls et les exécute avant de renvoyer le résultat.
• Logging et analytics : Toutes les transcriptions passent par le proxy, permettant un logging centralisé, l'analyse de sentiment en temps réel, et l'alimentation des dashboards sans impact sur la latence client.
• Gestion des sessions : Le proxy maintient l'état de chaque session (transcriptions, résultats de tools, métriques) et persiste dans Cosmos DB en fin de conversation avec une seule écriture optimisée.
• Résilience : Le proxy peut gérer les reconnexions, timeouts, et erreurs Azure de manière transparente pour le client, améliorant l'expérience utilisateur.

Flux de données détaillé

Optimisations de latence

Chaque milliseconde compte dans une conversation vocale. Voici les optimisations implémentées pour minimiser la latence :

Stack Technique RAG

Pourquoi le RAG est-il essentiel ?

Architecture Globale du Module RAG

Le module RAG de Waka Voice s'appuie sur une architecture robuste intégrant plusieurs services Azure pour offrir une recherche sémantique performante et scalable :

Les 3 Sources d'Ingestion

Le module RAG supporte trois méthodes d'ingestion de données, chacune optimisée pour différents cas d'usage. Sélectionnez la source adaptée à vos besoins :

Source 1 : Intégration SharePoint

Connexion directe à vos bibliothèques SharePoint via Microsoft Graph API. L'indexation parcourt récursivement tous les dossiers et sous-dossiers.

# Exemple appel API SharePoint Indexation
POST /api/kickoff_indexation
Content-Type: application/json

{
    "libraryId": "b!abc123def456...",
    "libraryName": "Documentation RH",
    "folderId": null,
    "folderName": "",
    "project_name": "ressources_humaines"
}

# Réponse
{
    "status": "started",
    "operation_id": "op_xyz789",
    "status_endpoint": "/api/indexation_status/op_xyz789"
}

Source 2 : Web Crawler

Crawler web asynchrone haute performance pour indexer des sites entiers. Supporte deux modes : Fast (aiohttp) et JavaScript (Playwright).

Source 3 : Upload Direct

Upload manuel de fichiers via l'interface web. Idéal pour des documents spécifiques ou des mises à jour ponctuelles de la base de connaissances.

# Endpoint: POST /api/kickoff_indexation
{
    "libraryId": "b!abc123...",
    "libraryName": "Documentation RH",
    "project_id": "projet_rh",
    "project_name": "Ressources Humaines"
}

# Endpoint: POST /crawl/start-crawl
{
    "url": "https://docs.example.com",
    "max_pages": 500,
    "max_depth": 5,
    "use_javascript": false,
    "use_sitemap": true
}

# Endpoint: POST /api/upload-to-blob
# Content-Type: multipart/form-data
- files: [fichier1.pdf, fichier2.docx]
- library_id: "uploads"
- project_name: "Mon Projet"

Pipeline d'Indexation

Chaque document passe par un pipeline d'indexation sophistiqué en 6 étapes :

Étape 1 : Extraction de texte

L'extraction intelligente détecte automatiquement le type de fichier et utilise la méthode appropriée :

Étape 2 : Chunking intelligent

Le texte extrait est découpé en chunks de taille optimale pour la recherche vectorielle. L'algorithme respecte les frontières de phrases :

# Paramètres de chunking (utils/indexation.py)
def split_text(summary=None, text="", max_chars=800, overlap=100):
    """
    Découpe le texte en chunks respectant les frontières de phrases.

    Args:
        max_chars: Taille cible par chunk (800 caractères)
        overlap: Chevauchement entre chunks (100 caractères)

    Algorithme:
    1. Split par regex sur terminateurs de phrase (. ! ?)
    2. Accumulation jusqu'à max_chars
    3. Overlap des dernières phrases pour continuité
    4. Chaque chunk commence ET finit sur une phrase complète
    """
    sentences = re.split(r'(?<=[.!?])\s+', text)
    # ... algorithme de chunking avec overlap
    return pages  # [{page_number, chunk, summary}]

Étape 3 : Résumé par GPT-5-mini

Chaque document reçoit un résumé généré par Azure OpenAI GPT-5-mini, attaché à tous ses chunks pour enrichir la recherche :

# Génération de résumé (utils/indexation.py)
def summarize_text(text):
    """
    Génère un résumé concis via Azure OpenAI GPT-5-mini.

    Prompt:
    - Capturer les points clés
    - 2-5 phrases maximum
    - Style professionnel
    """
    prompt = """Tu es un expert en synthèse de documents.
Génère un résumé concis et informatif en français.
- Points clés essentiels
- 2 à 5 phrases
- Style professionnel"""

    # Appel Azure OpenAI avec max_completion_tokens: 5000
    return summary.strip()

Étape 4 : Extraction d'entités

Azure Text Analytics extrait automatiquement les entités nommées de chaque chunk :

• Person : Noms de personnes mentionnées
• Organization : Entreprises, institutions
• Location : Lieux géographiques
• DateTime : Dates et heures
• Email, PhoneNumber, URL : Coordonnées
• Skill, Product, Event : Concepts métier
• Key Phrases : Termes importants du chunk

Étape 5 : Génération d'embeddings

Chaque chunk est converti en vecteur de 1536 dimensions via Azure OpenAI :

# Génération d'embeddings (utils/indexation.py)
def generate_embeddings_for_chunks(json_data, batch_size=50):
    """
    Génère les embeddings pour un batch de chunks.

    Modèle: text-embedding-3-small (1536 dimensions)
    Batch: 50 chunks par requête (optimisation coûts)
    Rate limit: 2 secondes entre batches
    """
    for batch in batches:
        response = requests.post(
            f"{endpoint}/openai/deployments/{deployment}/embeddings",
            json={"input": [chunk['chunk'] for chunk in batch]}
        )
        for chunk, embedding in zip(batch, response['data']):
            chunk['embedding'] = embedding['embedding']  # 1536 floats

Étape 6 : Stockage multi-bases

Les données sont stockées de manière optimale dans trois systèmes :

Recherche Vectorielle

La recherche RAG utilise une approche en deux étapes pour garantir pertinence et précision :

Étape 1 : Génération de l'intent de recherche

# api_rag_search.py - generate_search_intent()
def generate_search_intent(last_message: str, history: List[Dict]) -> Dict:
    """
    Transforme le message utilisateur + historique en intent optimisé.

    1. Formate l'historique de conversation
    2. Prompt GPT-4 pour extraire l'intent précis
    3. Génère l'embedding de l'intent

    Exemple:
    User: "Quels sont les délais pour les congés ?"
    History: [{"role": "user", "content": "Je travaille aux RH"}]

    → Intent: "vacation leave request deadlines HR department policy"
    """
    prompt = f"""Based on this conversation context:
History: {history_text}
Last message: {last_message}

Formulate a precise search intent for Azure AI Search.
Return only the search intent string in English."""

    # Génération intent via GPT-4
    search_intent = client.chat.completions.create(...).choices[0].message.content

    # Génération embedding
    embedding = embedding_client.embeddings.create(
        model="text-embedding-3-small",
        input=search_intent
    ).data[0].embedding

    return {"search_intent": search_intent, "embedding": embedding}

Étape 2 : Recherche vectorielle avec filtres

# Recherche dans Azure AI Search
def vector_search_with_filter(embedding: List[float], project_name: str, top_k: int = 10):
    """
    Recherche vectorielle avec filtrage par projet.

    Utilise la similarité cosinus pour trouver les chunks
    les plus proches sémantiquement de la requête.
    """
    search_results = search_client.search(
        search_text="",  # Pas de recherche textuelle
        vector_queries=[{
            "vector": embedding,
            "fields": "embedding",
            "k": top_k,
            "kind": "vector",
            "exhaustive": True  # Recherche exhaustive pour précision
        }],
        filter=f"project_name eq '{project_name}'",  # Filtrage par projet
        select=["chunk", "url_document_source", "key_phrases"]
    )
    return results

Intégration avec les Agents

Le module RAG s'intègre nativement avec les agents Waka Voice via un Tool dédié :

# utils/tools/rag_vector_search.py
RAG_VECTOR_SEARCH_TOOL = {
    "type": "function",
    "function": {
        "name": "search_knowledge_base",
        "description": """Recherche dans la base de connaissances interne.

Utilise ce tool pour:
- Trouver des informations sur les procédures internes
- Rechercher des documents de l'entreprise
- Obtenir des réponses sur les politiques et règles
- Consulter la documentation technique ou RH

Retourne les passages les plus pertinents avec leur source.""",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "La requête de recherche en langage naturel"
                },
                "max_results": {
                    "type": "integer",
                    "description": "Nombre max de résultats (défaut: 5, max: 10)",
                    "default": 5
                },
                "min_score": {
                    "type": "number",
                    "description": "Score minimum de pertinence (0-1)",
                    "default": 0.5
                }
            },
            "required": ["query"]
        }
    }
}

Interfaces RAG

Le module RAG dispose de plusieurs interfaces accessibles via le préfixe /rag :

Gestion des Sessions RAG

Les conversations RAG sont persistées dans Cosmos DB avec un schéma riche permettant l'analyse et le suivi de la satisfaction :

# configuration/sessions/rag/manager.py
class RagSessionManager:
    """
    Gestionnaire des sessions RAG Chat.
    Container: ConversationHistory (ConversationsDB)

    Schéma du document:
    {
        "id": "conv_abc123",
        "user_email": "user@domain.com",
        "display_name": "John Doe",
        "history": [
            {"role": "user", "content": "...", "timestamp": "..."},
            {"role": "assistant", "content": "...", "timestamp": "..."}
        ],
        "start_datetime": "2025-12-22T12:00:00Z",
        "end_datetime": "",
        "duration": "0:00:00",
        "summary": "",
        "satisfaction_measure": {
            "response_confidence": {"positive": 0.85, "negative": 0.15},
            "user_messages_average": {"positive": 0.78, "negative": 0.22}
        },
        "status": "active"
    }
    """

    def create(self, session_id, user_email, display_name, initial_message=None):
        """Crée une nouvelle session RAG."""

    def add_message(self, session_id, role, content):
        """Ajoute un message à l'historique."""

    def close(self, session_id, summary, satisfaction):
        """Clôture la session avec métriques."""

Métriques et Monitoring

Le module RAG expose plusieurs métriques pour le suivi et l'optimisation :

Bonnes Pratiques RAG

API Reference RAG

3.1 Vue d'ensemble architecturale

L'architecture se décompose en quatre couches principales, chacune avec des responsabilités bien définies et des interfaces claires :

3.2 Structure des Blueprints

Les Blueprints Flask permettent d'organiser le code en modules indépendants avec leurs propres routes, templates et logique métier. Voici le détail de chaque Blueprint :

Principe de responsabilité unique

Chaque Blueprint suit le principe SRP (Single Responsibility Principle). Par exemple, voice_live_proxy ne gère que la communication WebSocket temps réel, tandis que la persistance est déléguée aux Cosmos Managers. Cette séparation permet :

• Testabilité : Chaque composant peut être testé isolément avec des mocks
• Évolutivité : Modifier le stockage n'impacte pas la logique WebSocket
• Lisibilité : Un développeur trouve rapidement le code pertinent
• Parallélisation : Plusieurs développeurs travaillent sans conflits

3.3 Configuration et Managers

La couche configuration/ contient les gestionnaires de données (Managers) qui abstraient l'accès à Cosmos DB. Cette abstraction offre plusieurs avantages :

# Exemple : cosmos_agent_manager.py

class CosmosAgentManager:
    """
    Gestionnaire CRUD pour les agents voix.

    Responsabilités:
    - Abstraction des opérations Cosmos DB
    - Validation des données entrantes
    - Génération des références uniques
    - Gestion des timestamps
    """

    def __init__(self):
        self.container = get_agents_container()

    def create(self, config: dict) -> str:
        """
        Crée un nouvel agent avec validation et enrichissement.

        Args:
            config: Configuration de l'agent (nom, modèle, voix, tools, instructions)

        Returns:
            agent_id: UUID du nouvel agent

        Raises:
            ValidationError: Si la configuration est invalide
        """
        # Validation
        self._validate_config(config)

        # Enrichissement
        agent_id = str(uuid.uuid4())
        now = datetime.now(timezone.utc).isoformat()

        document = {
            "id": agent_id,
            "agent_id": agent_id,
            "agent_reference": self._generate_reference(),
            "created_at": now,
            "updated_at": now,
            "status": "active",
            **config
        }

        # Persistance
        self.container.create_item(body=document)

        return agent_id

    def get(self, agent_id: str) -> Optional[dict]:
        """Récupère un agent par son ID."""
        try:
            return self.container.read_item(
                item=agent_id,
                partition_key=agent_id
            )
        except exceptions.CosmosResourceNotFoundError:
            return None

    def update(self, agent_id: str, updates: dict) -> bool:
        """Met à jour partiellement un agent."""
        agent = self.get(agent_id)
        if not agent:
            return False

        agent.update(updates)
        agent["updated_at"] = datetime.now(timezone.utc).isoformat()

        self.container.replace_item(item=agent_id, body=agent)
        return True

    def delete(self, agent_id: str) -> bool:
        """Supprime un agent (soft delete recommandé en production)."""
        try:
            self.container.delete_item(item=agent_id, partition_key=agent_id)
            return True
        except exceptions.CosmosResourceNotFoundError:
            return False

    def list_all(self, status: str = None) -> List[dict]:
        """Liste tous les agents avec filtre optionnel."""
        query = "SELECT * FROM c"
        if status:
            query += f" WHERE c.status = '{status}'"
        query += " ORDER BY c.created_at DESC"

        return list(self.container.query_items(
            query=query,
            enable_cross_partition_query=True
        ))

3.4 Stack Technique Détaillée

Voici l'ensemble des technologies utilisées avec leur justification :

Backend

Azure Services

Frontend

4.1 Approche Hybride : Cosmos DB + Blob Storage

4.1.1 Philosophie de l'Architecture

4.1.2 Comparaison et Avantages

4.1.3 Vue d'Ensemble des Bases

4.2 Database 1 : ConversationsDB (Principal)

4.2.1 Container : AgentConfigurations

{
  "id": "uuid",
  "agent_id": "uuid",
  "agent_reference": "Agent-XXXXXX",
  "agent_type": "voice_agent",
  "config_type": "azure_speech",
  "model_id": "gpt-4o-realtime",
  "model_name": "GPT-4o Realtime",
  "model_family": "F1_Realtime",
  "speech_endpoint": "https://eastus2.api.cognitive.microsoft.com/",
  "speech_region": "eastus2",
  "agent_name": "Assistant Commercial",
  "role": "commercial",
  "voice_config": {
    "voice": "fr-FR-DeniseNeural",
    "style": "friendly"
  },
  "azure_config": {
    "modalities": ["text", "audio"],
    "temperature": 0.8,
    "max_response_output_tokens": 4096,
    "turn_detection": {
      "type": "server_vad",
      "threshold": 0.5,
      "silence_duration_ms": 500
    },
    "input_audio_transcription": { "model": "whisper-1" },
    "tools": ["search_web", "send_email"],
    "instructions": "Tu es un assistant commercial..."
  },
  "tools": ["tool_id_1", "tool_id_2"],
  "current_step": 4,
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:45:00Z"
}

4.2.2 Container : AvatarConfigurations

{
  "id": "uuid",
  "agent_id": "uuid",
  "agent_reference": "Avatar-XXXXXX",
  "agent_type": "azure_avatar",
  "avatar_type": "photo",
  "azure_config": {
    "avatar": {
      "character": "lisa",
      "style": "casual-sitting",
      "photoAvatarBaseModel": "vasa-1",
      "video": {
        "bitrate": 2000000,
        "codec": "h264",
        "resolution": { "width": 1920, "height": 1080 }
      }
    },
    "modalities": ["text", "audio"],
    "temperature": 0.7
  },
  "background_url": "https://...blob.../background/office.jpg",
  "status": "active"
}

4.2.3 Container : TextAgentConfigurations

{
  "id": "uuid",
  "agent_id": "uuid",
  "agent_reference": "TextAgent-XXXXXX",
  "agent_type": "text_agent",
  "config_type": "azure_inference",
  "model_id": "gpt-5.2-chat",
  "model_name": "GPT-5.2",
  "model_provider": "OpenAI",
  "language": "fr-FR",
  "tools": ["end_text_conversation", "search_knowledge"],
  "tools_definitions": [
    {
      "type": "function",
      "function": {
        "name": "search_knowledge",
        "description": "Recherche dans la base de connaissances",
        "parameters": { ... }
      }
    }
  ],
  "instructions": "Tu es un assistant expert...",
  "temperature": 0.7,
  "max_response_tokens": 4096,
  "status": "active",
  "created_at": "2024-02-01T09:00:00Z"
}

4.2.4 Container : VoiceSessions

{
  "id": "session_uuid",
  "call_id": "call_uuid",
  "session_id": "session_uuid",
  "session_type": "voice_live",
  "agent_id": "agent_uuid",
  "agent_type": "Agent Voice",
  "model_id": "gpt-4o-realtime",
  "family": "F1_Realtime",
  "tarif_base": "pro",
  "azure_config": { ... },
  "history": [
    { "role": "user", "content": "Bonjour", "timestamp": "..." },
    { "role": "assistant", "content": "Bonjour ! Comment puis-je vous aider ?", "timestamp": "..." }
  ],
  "usage": {
    "input_token_details": { "text_tokens": 150, "audio_tokens": 2400 },
    "output_token_details": { "text_tokens": 200, "audio_tokens": 3200 }
  },
  "cost": {
    "total_cost": 0.045,
    "cost_per_minute": 0.015
  },
  "duration_minutes": 3.5,
  "status": "completed",
  "summary": "Discussion sur les tarifs et disponibilités",
  "sentiment": "positive",
  "created_at": "2024-01-20T14:30:00Z",
  "end_datetime": "2024-01-20T14:33:30Z"
}

4.2.5 Container : Tools

{
  "id": "uuid",
  "tool_id": "uuid",
  "name": "search_web",
  "display_name": "Recherche Web",
  "category": "general",
  "tool_type": "api_rest",
  "definition": {
    "type": "function",
    "function": {
      "name": "search_web",
      "description": "Effectue une recherche sur le web",
      "parameters": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "description": "Requête de recherche" }
        },
        "required": ["query"]
      }
    }
  },
  "execution": {
    "type": "http",
    "method": "GET",
    "endpoint": "https://api.bing.microsoft.com/v7.0/search",
    "headers": { "Ocp-Apim-Subscription-Key": "{{BING_API_KEY}}" }
  },
  "status": "active",
  "is_system": false,
  "version": 1,
  "created_at": "2024-01-10T08:00:00Z"
}

4.2.6 Container : CallHistory

{
  "id": "call_uuid",
  "call_id": "call_uuid",
  "session_id": "call_uuid",
  "session_type": "voice_live",
  "agent_id": "agent_uuid",
  "campaign_id": "campaign_uuid",
  "customer_data": {
    "name": "Jean Dupont",
    "phone": "+33612345678",
    "company": "Acme Inc"
  },
  "current_step": "closing",
  "conversation_history": [ ... ],
  "brain_history": [ ... ],
  "tools_executed": [
    { "name": "check_availability", "result": "success", "timestamp": "..." }
  ],
  "tokens": {
    "input_text": 450,
    "input_audio": 5600,
    "output_text": 380,
    "output_audio": 7200
  },
  "status": "completed",
  "outcome": "ptp",
  "created_at": "2024-01-22T10:15:00Z"
}

4.2.7 Container : campagnes-appels

{
  "id": "campaign_uuid",
  "campaign_id": "campaign_uuid",
  "campaign_reference": "campagne_XXXXX",
  "campaign_name": "Recouvrement Q1 2024",
  "campaign_type": "recouvrement",
  "agent_id": "agent_uuid",
  "agent_reference": "Agent-XXXXXX",
  "start_date": "2024-01-15",
  "end_date": "2024-03-31",
  "selected_tools": ["check_payment_status", "schedule_callback"],
  "selected_statuses": ["impayé", "relance"],
  "clients": ["client_id_1", "client_id_2"],
  "total_clients": 250,
  "stats": {
    "total_calls": 180,
    "successful_calls": 145,
    "ptp_count": 89,
    "callback_scheduled": 32
  },
  "status": "active",
  "created_at": "2024-01-10T09:00:00Z"
}

4.2.8 Container : ConversationHistory

{
  "id": "conv_abc123",
  "user_email": "user@domain.com",
  "display_name": "Jean Dupont",
  "history": [
    { "role": "user", "content": "Quelle est la politique de remboursement ?" },
    { "role": "assistant", "content": "Selon notre documentation, les remboursements sont possibles..." }
  ],
  "start_datetime": "2024-01-25T14:00:00Z",
  "end_datetime": "2024-01-25T14:15:00Z",
  "duration": "0:15:00",
  "summary": "Questions sur la politique de remboursement",
  "satisfaction_measure": {
    "rating": 4,
    "feedback": "Réponse claire et rapide"
  },
  "status": "completed"
}

4.2.9 Containers Personal Voice

4.2.10 Autres Containers ConversationsDB

4.3 Database 2 : RAG_base (Fonctionnalité RAG)

4.3.1 Container : database (Chunks)

{
  "id": "chunk_uuid",
  "document_id": "doc_uuid",
  "project_id": "project_uuid",
  "project_name": "Base Connaissances RH",
  "content": "Le processus d'intégration des nouveaux employés comprend...",
  "chunk_index": 5,
  "total_chunks": 24,
  "blob_url": "https://wakastorage.blob.../documents/politique_rh.pdf",
  "source_filename": "politique_rh.pdf",
  "source_type": "upload",
  "embedding": [0.0234, -0.0156, 0.0891, ...],
  "metadata": {
    "page_number": 3,
    "section": "Intégration",
    "language": "fr"
  },
  "summary": "Résumé du processus d'intégration...",
  "entities": ["RH", "intégration", "onboarding"],
  "created_at": "2024-01-18T11:30:00Z"
}

4.3.2 Container : Libraries_Tracking

{
  "id": "tracking_uuid",
  "site_id": "sharepoint_site_id",
  "library_id": "library_id",
  "library_name": "Documents RH",
  "last_sync": "2024-01-25T02:00:00Z",
  "documents_indexed": 156,
  "chunks_created": 2340,
  "sync_status": "completed",
  "errors": []
}

4.3.3 Container : Logs_RAG

4.4 Azure Blob Storage : Containers

4.5 Diagramme d'Interrelations

4.6 Flux de Données Principaux

4.6.1 Flux 1 : Session Voice/Avatar

4.6.2 Flux 2 : Indexation RAG

4.6.3 Flux 3 : Personal Voice

4.7 Pattern de Persistance Optimisé

# Pattern de persistance (voice_live_proxy.py)
class VoiceLiveSession:
    def __init__(self, ...):
        # Phase 1: Lancement - 1 read config, 1 create session
        self.cached_azure_config = agent_config.get('azure_config')
        self._create_conversation_document()  # 1 write

    def _accumulate_transcript(self, role, content):
        # Phase 2: Pendant - 0 appels Cosmos
        self.transcripts.append({
            "role": role,
            "content": content,
            "timestamp": datetime.utcnow().isoformat()
        })  # Mémoire uniquement

    def close(self):
        # Phase 3: Fin - 1 update final
        manager.update(self.session_id, {
            "history": self.transcripts,
            "usage": self.accumulated_tokens,
            "outcome": self.end_outcome,
            "end_datetime": datetime.utcnow().isoformat()
        })  # 1 write

4.8 Bonnes Pratiques de Partition Key

5.1 Architecture du Module

5.1.1 Stack Technique

5.1.2 Flux de Données Global

5.2 Le Workflow en 4 Étapes

5.2.1 Étape 1 : Sélection du Projet

L'utilisateur choisit un projet Azure existant ou en crée un nouveau. Chaque projet peut contenir plusieurs voix personnalisées.

5.2.2 Étape 2 : Enregistrement du Consentement

Cette étape est obligatoire légalement. L'utilisateur doit lire à haute voix un texte de consentement officiel qui autorise Azure à créer une voix synthétique.

Algorithme de Validation

La validation utilise l'algorithme de distance de Levenshtein pour comparer le texte transcrit avec le texte attendu :

# Extrait de personal_voice_routes.py - Validation Levenshtein
def calculate_similarity_score(text1: str, text2: str) -> float:
    """Calcule le score de similarité entre deux textes (0-100%)"""
    # Normalisation
    t1 = text1.lower().strip()
    t2 = text2.lower().strip()

    # Distance de Levenshtein
    distance = levenshtein_distance(t1, t2)
    max_len = max(len(t1), len(t2))

    if max_len == 0:
        return 100.0

    # Score = 100 - (distance/max_len * 100)
    return max(0, 100 - (distance / max_len * 100))

5.2.3 Étape 3 : Enregistrement des 3 Échantillons Vocaux

L'utilisateur enregistre 3 échantillons audio en lisant des phrases prédéfinies. Chaque échantillon doit durer entre 5 et 90 secondes et atteindre un score de validation ≥ 80%.

Configuration des Échantillons

5.2.4 Étape 4 : Synthèse et Galerie

Une fois les 3 échantillons validés, le système appelle l'Azure Custom Neural Voice API pour créer la voix personnalisée. Un Speaker Profile ID unique est généré.

5.3 API REST - Endpoints

Le module Personal Voice expose les endpoints suivants via le Blueprint Flask personal_voice_bp :

5.3.1 Exemple d'Appel API - Validation Audio

// Requête POST /personal-voice/api/validate-audio
{
    "audio_data": "data:audio/wav;base64,UklGRiQAAABXQV...",
    "expected_text": "I John Doe am aware that recordings...",
    "audio_type": "consent"  // ou "sample"
}

// Réponse
{
    "success": true,
    "transcription": "I John Doe am aware that recordings...",
    "validation_score": 87.5,
    "is_valid": true,
    "message": "Audio validé avec un score de 87.5%"
}

5.4 Structure de Données Cosmos DB

5.4.1 Collection : personal_voices

{
    "id": "pv_abc123def456",
    "type": "personal_voice",
    "project_id": "proj_xyz789",
    "user_id": "user_12345",
    "voice_name": "Marie - Marketing",
    "speaker_profile_id": "spk_azure_profile_id",
    "locale": "fr-FR",
    "status": "active",  // draft, processing, active, failed
    "consent": {
        "blob_url": "https://blob.azure/.../consent_abc123.wav",
        "validation_score": 85.2,
        "recorded_at": "2025-12-15T10:30:00Z"
    },
    "samples": [
        {
            "sample_id": "smp_001",
            "blob_url": "https://blob.azure/.../sample1_abc123.wav",
            "validation_score": 87.5,
            "duration_seconds": 12.4,
            "recorded_at": "2025-12-15T10:32:00Z"
        },
        {
            "sample_id": "smp_002",
            "blob_url": "https://blob.azure/.../sample2_abc123.wav",
            "validation_score": 92.1,
            "duration_seconds": 15.2,
            "recorded_at": "2025-12-15T10:34:00Z"
        },
        {
            "sample_id": "smp_003",
            "blob_url": "https://blob.azure/.../sample3_abc123.wav",
            "validation_score": 88.9,
            "duration_seconds": 14.1,
            "recorded_at": "2025-12-15T10:36:00Z"
        }
    ],
    "azure_metadata": {
        "custom_voice_endpoint": "https://westeurope.api.cognitive.microsoft.com/...",
        "deployment_id": "dep_xxx",
        "model_version": "2024-01"
    },
    "created_at": "2025-12-15T10:30:00Z",
    "updated_at": "2025-12-15T10:40:00Z"
}

5.5 Intégration avec les Agents

Une fois créée, la voix personnelle peut être assignée à n'importe quel agent Voice ou agent Avatar dans Waka Voice.

5.5.1 Configuration Agent avec Personal Voice

// Configuration de l'agent dans Cosmos DB
{
    "agent_id": "agent_voice_001",
    "type": "voice",
    "azure_config": {
        "voice_type": "personal",  // au lieu de "standard"
        "speaker_profile_id": "spk_azure_profile_id",
        "locale": "fr-FR",
        "style": "neutral",
        "rate": "1.0",
        "pitch": "0%"
    }
}

// SSML généré automatiquement
<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis">
    <voice name="PersonalVoiceModel">
        <mstts:ttsembedding speakerProfileId="spk_azure_profile_id"/>
        Bonjour, comment puis-je vous aider aujourd'hui ?
    </voice>
</speak>

5.6 Bonnes Pratiques

6.1 Architecture du Système de Tools

6.1.1 Stack Technique

6.1.2 Flux de Données Global

6.2 Les 4 Types de Tools

6.2.1 Type API REST

Appels HTTP vers des services externes avec configuration complète de l'authentification et du mapping des paramètres.

// Exemple de configuration API REST
{
    "name": "create_client",
    "type": "api",
    "execution": {
        "type": "http",
        "endpoint": "https://api.waka.com/v1/clients",
        "method": "POST",
        "headers": {
            "Content-Type": "application/json",
            "Accept": "application/json"
        },
        "auth_type": "bearer",
        "auth_config": {
            "value": "${env.WAKA_API_TOKEN}"
        },
        "params_mapping": {
            "first_name": {"in": "body", "name": "firstName"},
            "last_name": {"in": "body", "name": "lastName"},
            "phone": {"in": "body", "name": "phoneNumber"}
        }
    }
}

6.2.2 Type MCP Server

Connexion au Model Context Protocol pour intégrer des serveurs d'outils externes. Trois transports supportés :

// Exemple MCP STDIO (serveur local)
{
    "name": "filesystem_tools",
    "type": "mcp_server",
    "execution": {
        "type": "mcp",
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@anthropic/mcp-server-filesystem", "/home/user/documents"],
        "env": {
            "NODE_OPTIONS": "--max-old-space-size=4096"
        }
    }
}

// Exemple MCP HTTP (Azure AI Foundry)
{
    "name": "azure_ai_tools",
    "type": "mcp_server",
    "execution": {
        "type": "mcp",
        "transport": "http",
        "server_url": "https://my-foundry.azure.com/mcp",
        "server_label": "Azure AI Foundry",
        "allowed_tools": ["search_documents", "analyze_image"],
        "auth_type": "bearer",
        "auth_config": {"value": "${env.AZURE_AI_KEY}"},
        "require_approval": "never"
    }
}

6.2.3 Type Code Python

Exécution de code Python dans un environnement sandboxé avec RestrictedPython. Timeout de 30 secondes.

// Exemple Tool Python
{
    "name": "calculate_interest",
    "type": "code",
    "execution_python": {
        "type": "python",
        "code": "def execute(params):\n    principal = params.get('principal', 0)\n    rate = params.get('rate', 0.05)\n    years = params.get('years', 1)\n    interest = principal * rate * years\n    return {\n        'principal': principal,\n        'rate': rate,\n        'years': years,\n        'interest': round(interest, 2),\n        'total': round(principal + interest, 2)\n    }",
        "inputs": [
            {"name": "principal", "type": "number", "required": true, "description": "Montant principal"},
            {"name": "rate", "type": "number", "required": false, "description": "Taux d'intérêt (défaut: 5%)"},
            {"name": "years", "type": "integer", "required": false, "description": "Nombre d'années"}
        ],
        "outputs": ["principal", "rate", "years", "interest", "total"]
    }
}

6.2.4 Import OpenAPI / YAML

Import automatique de spécifications OpenAPI 3.x / Swagger 2.x avec Pipeline V2 en 3 étapes et validation intelligente via Claude Opus 4.5.

Pipeline V2 - Vue d'ensemble

Détail du flux SSE (Server-Sent Events)

Les 3 Étapes en détail

Fichiers clés du Pipeline

6.3 Catégories de Tools

Les tools sont organisés en 23 catégories dont 13 catégories WAKA spécifiques à la microfinance :

6.4 API REST - Endpoints

Le module Tools expose les endpoints suivants via le Blueprint Flask tools_bp :

6.5 Structure de Données Cosmos DB

6.5.1 Container : Tools

{
    "id": "tool_abc123def456",
    "tool_id": "tool_abc123def456",
    "name": "create_client",
    "display_name": "Créer un Client",
    "category": "waka_clients",  // Partition Key
    "tags": ["waka", "clients", "api"],
    "status": "active",  // active | inactive
    "is_system": false,
    "version": 2,
    "definition": {
        "type": "function",
        "function": {
            "name": "create_client",
            "description": "Crée un nouveau client dans le système WAKA",
            "parameters": {
                "type": "object",
                "properties": {
                    "first_name": {"type": "string", "description": "Prénom du client"},
                    "last_name": {"type": "string", "description": "Nom de famille"},
                    "phone": {"type": "string", "description": "Numéro de téléphone"}
                },
                "required": ["first_name", "last_name", "phone"]
            }
        }
    },
    "execution": {
        "type": "http",
        "endpoint": "https://api.waka.com/v1/clients",
        "method": "POST",
        "headers": {"Content-Type": "application/json"},
        "auth_type": "bearer",
        "auth_config": {"value": "${env.WAKA_API_TOKEN}"},
        "params_mapping": {
            "first_name": {"in": "body", "name": "firstName"},
            "last_name": {"in": "body", "name": "lastName"},
            "phone": {"in": "body", "name": "phoneNumber"}
        }
    },
    "openapi_source": {
        "path": "/clients",
        "method": "POST",
        "operation_id": "createClient"
    },
    "created_at": "2025-12-15T10:30:00Z",
    "updated_at": "2025-12-20T14:45:00Z",
    "created_by": "admin"
}

6.5.2 Container : ImportJobs

{
    "id": "job_xyz789",
    "status": "processing",  // pending | processing | completed | failed
    "total": 42,
    "processed": 25,
    "success": 23,
    "errors": 2,
    "created_at": "2025-12-20T14:00:00Z",
    "updated_at": "2025-12-20T14:02:30Z",
    "config": {
        "category": "custom",
        "prefix": "myapi_",
        "base_url": "https://api.example.com"
    },
    "results": [
        {"name": "get_users", "status": "created"},
        {"name": "create_user", "status": "created"}
    ],
    "error_details": [
        {"endpoint": "/admin/dangerous", "error": "Endpoint filtered"}
    ]
}

6.6 Exécution des Tools

L'exécution des tools est orchestrée par le module tools/__init__.py qui fournit les fonctions centrales :

# Fonction principale d'exécution (tools/__init__.py)
def execute_tool(tool_name, arguments):
    """
    Exécute un outil spécifique avec les arguments fournis.

    Args:
        tool_name: Nom de l'outil à exécuter
        arguments: Dictionnaire des arguments pour l'outil

    Returns:
        dict: Résultat de l'exécution de l'outil
    """
    # Mapping des noms vers les modules
    tool_map = {
        "search_web": tool_search_web,
        "send_email": tool_email,
        "get_weather_forecast": tool_weather,
        "end_conversation": tool_end_conversation,
        "conversation_brain": tool_conversation_brain,
        # ... 30+ tools prédéfinis
    }

    if tool_name in tool_map:
        return tool_map[tool_name].execute(arguments)

    # Fallback: chercher dans Cosmos DB (tools dynamiques)
    return execute_dynamic_tool(tool_name, arguments)

6.7 Galerie des Tools

6.8 Tools Prédéfinis (30+)

Waka Voice inclut plus de 30 tools prédéfinis prêts à l'emploi :

6.9 Création d'Outil RAG

Lorsqu'un projet RAG est créé, un outil de recherche RAG est automatiquement généré. Cet outil permet à l'assistant IA d'interroger la base de connaissances du projet via le mécanisme de function calling d'Azure OpenAI.

6.9.1 Vue d'ensemble du processus

6.9.2 Étapes détaillées

6.9.3 Structure du Tool créé

Le tool généré suit le format Azure OpenAI Function Calling :

{
    "name": "rag_search_mon_projet",
    "display_name": "Recherche RAG - Mon Projet",
    "category": "rag_search",
    "status": "active",
    "tags": ["rag", "search", "vector", "mon projet"],
    "is_system": false,

    "definition": {
        "type": "function",
        "function": {
            "name": "rag_search_mon_projet",
            "description": "Recherche dans la base de connaissances 'Mon Projet'...",
            "parameters": {
                "type": "object",
                "properties": {
                    "search_query": {
                        "type": "string",
                        "description": "Intention de recherche générée par l'assistant"
                    }
                },
                "required": ["search_query"]
            }
        }
    },

    "execution": {
        "type": "http",
        "method": "POST",
        "endpoint": "https://domain.com/api/rag-tool/Mon%20Projet/fast-search",
        "headers": { "Content-Type": "application/json" },
        "body_template": {
            "search_query": "{{search_query}}",
            "max_results": 5
        }
    },

    "metadata": {
        "project_id": "uuid-du-projet",
        "project_name": "Mon Projet",
        "auto_generated": true
    }
}

6.9.4 Diagramme de flux complet

6.9.5 Utilisation du Tool par l'Assistant

Une fois le projet créé et des documents indexés, l'assistant peut utiliser le tool :

6.9.6 Points clés

6.9.7 Fichiers sources

7.1 Architecture Globale

Caractéristiques Principales

7.2 Configuration des Modèles

# configuration/cosmos_text_agent_manager.py

TEXT_MODELS = {
    "gpt-5.2-chat": {
        "display_name": "GPT-5.2 Chat",
        "provider": "azure",
        "endpoint_env": "AZURE_OPENAI_ENDPOINT",
        "api_key_env": "AZURE_OPENAI_API_KEY",
        "api_version": "2025-10-01",
        "supports_vision": True,
        "supports_tools": True,
        "max_tokens": 128000
    },
    "claude-opus-4-5": {
        "display_name": "Claude Opus 4.5",
        "provider": "azure-ai-foundry",
        "endpoint_env": "AZURE_AI_FOUNDRY_ENDPOINT",
        "api_key_env": "AZURE_AI_FOUNDRY_API_KEY",
        "supports_vision": True,
        "supports_tools": True,
        "max_tokens": 200000
    }
}

7.3 Architecture du Blueprint

# Blueprints/text_agents_routes.py
text_agents_bp = Blueprint('text_agents', __name__, url_prefix='/text-agents')

7.4 API de Chat Streaming

POST /text-agents/api/<agent_id>/chat/stream
Content-Type: application/json

{
    "message": "Bonjour, comment puis-je vous aider ?",
    "session_id": "sess-uuid-optional",
    "attachments": [
        {"type": "image", "data": "base64_encoded_data", "mime_type": "image/png"}
    ],
    "metadata": {"user_id": "user-123", "source": "website"}
}

Réponse SSE

event: message
data: {"type": "content", "content": "Bonjour"}

event: message
data: {"type": "tool_call", "tool": "search_database", "arguments": {...}}

event: message
data: {"type": "tool_result", "tool": "search_database", "result": {...}}

event: message
data: {"type": "done", "usage": {"prompt_tokens": 150, "completion_tokens": 45}}

Implémentation Serveur

@text_agents_bp.route('/api/<agent_id>/chat/stream', methods=['POST'])
def chat_stream_api(agent_id):
    data = request.get_json()
    message = data.get('message', '')
    session_id = data.get('session_id')

    agent = cosmos_text_agent_manager.get_agent(agent_id)
    if not agent:
        return jsonify({"error": "Agent not found"}), 404

    session = get_or_create_session(agent_id, session_id)

    def generate():
        messages = build_messages(agent, session, message, data.get('attachments', []))
        for chunk in stream_completion(agent, messages):
            if chunk.get('type') == 'tool_call':
                result = execute_dynamic_tool(chunk['tool'], chunk['arguments'])
                yield f"data: {json.dumps({'type': 'tool_result', 'result': result})}\n\n"
            else:
                yield f"data: {json.dumps(chunk)}\n\n"
        yield f"data: {json.dumps({'type': 'done'})}\n\n"

    return Response(stream_with_context(generate()), mimetype='text/event-stream',
        headers={'Cache-Control': 'no-cache', 'Connection': 'keep-alive'})

7.5 Système de Tools

Configuration Tool HTTP

{
    "id": "tool-uuid-1",
    "name": "search_products",
    "description": "Recherche des produits dans le catalogue",
    "type": "http",
    "http_config": {
        "method": "GET",
        "url": "https://api.example.com/products",
        "headers": {"Authorization": "Bearer ${API_KEY}"},
        "query_params": {"q": "${query}", "limit": "${limit:10}"}
    },
    "parameters": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "Terme de recherche"},
            "limit": {"type": "integer", "default": 10}
        },
        "required": ["query"]
    }
}

Configuration Tool MCP

{
    "id": "tool-uuid-3",
    "name": "mcp_filesystem",
    "description": "Accès au système de fichiers via MCP",
    "type": "mcp",
    "mcp_config": {
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@anthropic/mcp-server-filesystem", "/path/to/allowed"],
        "timeout": 30000
    }
}

Exécution Dynamique

def execute_dynamic_tool(tool_config: dict, arguments: dict) -> dict:
    tool_type = tool_config.get('type', 'http')

    if tool_type == 'http':
        return execute_http_tool(tool_config, arguments)
    elif tool_type == 'python_module':
        return execute_python_module_tool(tool_config, arguments)
    elif tool_type == 'mcp':
        return execute_mcp_tool(tool_config, arguments)
    else:
        return {"error": f"Unknown tool type: {tool_type}"}

7.6 Gestion des Sessions

{
    "id": "sess-uuid-123",
    "agent_id": "agent-uuid-456",
    "created_at": "2025-12-30T10:00:00Z",
    "messages": [
        {"role": "system", "content": "Tu es un assistant..."},
        {"role": "user", "content": "Bonjour", "timestamp": "2025-12-30T10:00:00Z"},
        {"role": "assistant", "content": "Bonjour ! Comment puis-je vous aider ?"}
    ],
    "metadata": {"user_id": "user-123", "source": "website"},
    "token_usage": {"prompt_tokens": 1500, "completion_tokens": 450}
}

API de Session

# Récupérer une session
GET /text-agents/api/<agent_id>/session?session_id=<id>

# Créer une nouvelle session
POST /text-agents/api/<agent_id>/session
{"metadata": {"user_id": "user-123"}}

# Supprimer une session
DELETE /text-agents/api/<agent_id>/session/<session_id>

7.7 Schéma de Données Agent

{
    "id": "agent-uuid-789",
    "name": "Assistant Commercial",
    "description": "Agent spécialisé dans les ventes",
    "model": "gpt-5.2-chat",
    "system_prompt": "Tu es un assistant commercial expert...",
    "temperature": 0.7,
    "max_tokens": 4096,
    "tools": [...],
    "default_tools_enabled": true,
    "welcome_message": "Bonjour ! Je suis votre assistant commercial.",
    "suggested_prompts": ["Quels sont vos produits phares ?", "Comment commander ?"],
    "appearance": {
        "primary_color": "#007bff",
        "avatar_url": "/static/avatars/commercial.png"
    },
    "settings": {
        "session_timeout_minutes": 30,
        "max_messages_per_session": 100,
        "save_sessions": true
    }
}

7.8 Intégration et Embedding

Intégration iframe

<iframe
    src="https://wakavoice.example.com/text-agents/agent-uuid/embed"
    width="400" height="600" frameborder="0"
    style="border-radius: 12px; box-shadow: 0 4px 12px rgba(0,0,0,0.15);">
</iframe>

Widget JavaScript

<script src="https://wakavoice.example.com/static/js/text-agent-widget.js"></script>
<script>
    WakaTextAgent.init({
        agentId: 'agent-uuid-789',
        position: 'bottom-right',
        primaryColor: '#007bff',
        welcomeMessage: 'Bonjour ! Comment puis-je vous aider ?',
        onMessage: function(message) { console.log('Message:', message); }
    });
</script>

API du Widget

WakaTextAgent.open();        // Ouvrir
WakaTextAgent.close();       // Fermer
WakaTextAgent.sendMessage("Je cherche un produit");
WakaTextAgent.resetSession();
WakaTextAgent.on('message', (data) => console.log(data));
WakaTextAgent.on('toolCall', (data) => console.log(data.tool));

7.9 Interface Utilisateur

7.10 Flux de Conversation

7.11 Métriques et Monitoring

# Santé du service
GET /text-agents/health
Response: {"status": "healthy", "model_status": {...}}

# Métriques Prometheus
GET /text-agents/metrics

8.1 Vue d'Ensemble et Architecture

Caractéristiques Principales

8.2 Les Modèles Voice Live

8.3 Turn Detection (VAD Sémantique)

{
    "turn_detection": {
        "type": "azure_semantic_vad",
        "threshold": 0.3,
        "silence_duration_ms": 300,
        "create_response": true,
        "end_of_utterance_detection": {
            "model": "semantic_detection_v1_multilingual"
        }
    }
}

8.4 Barge-in (Interruption)

Le barge-in permet à l'utilisateur d'interrompre l'agent pendant qu'il parle. L'audio de l'agent est immédiatement coupé et la transcription de l'utilisateur est traitée.

{
    "turn_detection": {
        "type": "azure_semantic_vad",
        "interrupt_response": true,
        "threshold": 0.5
    }
}

8.5 Architecture du Blueprint

Fichiers Principaux

Endpoints Principaux

8.6 Connexion WebSocket

Flux de Messages

Types de Messages Azure Realtime

8.7 Système de Tools

Outils Disponibles (31 total)

Format de Définition d'un Tool

# tools/weather.py

def get_tool_definition() -> dict:
    return {
        'type': 'function',
        'function': {
            'name': 'get_weather_forecast',
            'description': 'Récupère les prévisions météo',
            'parameters': {
                'type': 'object',
                'properties': {
                    'city': {'type': 'string', 'description': 'Nom de la ville'},
                    'days': {'type': 'integer', 'description': 'Jours (1-7)', 'default': 3}
                },
                'required': ['city']
            }
        }
    }

async def execute(args: dict) -> dict:
    city = args.get('city')
    response = await weather_api.get_forecast(city, args.get('days', 3))
    return {'city': city, 'forecast': response.data}

8.8 Gestion des Sessions

Schéma de Session Cosmos DB

{
    "id": "sess-uuid-123",
    "call_id": "call-uuid-456",
    "agent_id": "agent-uuid-789",
    "status": "completed",
    "started_at": "2025-12-30T10:00:00Z",
    "ended_at": "2025-12-30T10:05:30Z",
    "duration_minutes": 5.5,
    "model": "gpt-realtime",
    "voice": "fr-FR-DeniseNeural",
    "tokens": {
        "input_token_details": {"text_tokens": 450, "audio_tokens": 12500},
        "output_token_details": {"text_tokens": 380, "audio_tokens": 8700}
    },
    "cost": {
        "input_text": 0.0025,
        "input_audio": 0.2125,
        "output_text": 0.0084,
        "output_audio": 0.4785,
        "total": 0.7019
    },
    "conversation": [...],
    "message_count": 12,
    "tools_executed": 2,
    "summary": "L'utilisateur a recherché un vol Paris-Lyon...",
    "sentiment": "positive",
    "sentiment_score": 0.85
}

8.9 Types de Voix Supportés

8.10 Flux de Création d'un Agent

8.11 Timeouts et Métriques

Métriques Collectées par Session

Variables d'Environnement Requises

# Azure Voice Live
VOICE_LIVE_KEY=<api-key>
VOICE_LIVE_NAME=<resource-name>
VOICE_LIVE_ENDPOINT=<endpoint>
VOICE_LIVE_ENDPOINT_TYPE=cognitiveservices

# Fallback (ancien format)
AZURE_SPEECH_KEY=<key>
AZURE_SPEECH_NAME=<name>
AZURE_SPEECH_ENDPOINT=<endpoint>

# Cosmos DB
COSMOS_URI=<uri>
COSMOS_KEY=<key>
COSMOS_DATABASE_NAME=ConversationsDB

9.1 Vue d'Ensemble et Architecture

Caractéristiques Principales

9.2 Types d'Avatars

Avatar Vidéo Azure (6 personnages)

Personnages 3D pré-rendus avec styles variés, rendu via WebRTC en haute résolution.

Configuration Vidéo Avatar

{
    "avatar": {
        "character": "lisa",
        "style": "casual-sitting",
        "customized": false,
        "video": {
            "resolution": {"width": 1920, "height": 1080},
            "bitrate": 2000000,
            "crop": {
                "top_left": [560, 0],
                "bottom_right": [1360, 1080]
            },
            "background": {"color": "#FFFFFF"}
        },
        "ice_servers": [
            {"urls": ["stun:stun.l.google.com:19302"]}
        ]
    }
}

Avatar Photo VASA-1 (30 personnages)

Anime une photo portrait pour créer un avatar parlant réaliste avec micro-expressions.

Configuration Photo Avatar

{
    "avatar": {
        "type": "photo-avatar",
        "model": "vasa-1",
        "character": "isabella",
        "photoAvatarBaseModel": "isabella",
        "video": {
            "resolution": {"width": 512, "height": 512},
            "bitrate": 2000000
        }
    }
}

9.3 Architecture du Blueprint

Fichiers Principaux

Endpoints Principaux

9.4 Flux de Création d'un Agent Avatar

Étape 1: Sélection du Modèle

• Choisir parmi: gpt-realtime, gpt-realtime-mini
• Créer document Cosmos avec status="draft"
• Configurer les endpoints Speech Azure

Étape 2: Configuration Voix

• Sélectionner langue et locale (fr-FR, en-US, etc.)
• Choisir la voix Azure Neural
• Configurer température et vitesse

Étape 3: Sélection Avatar

• Vidéo: Choisir personnage + style (1920x1080)
• Photo: Choisir portrait VASA-1 (512x512)
• Configurer fond et crop (vidéo uniquement)

Étape 4: Configuration Outils

• Multi-sélection parmi les outils disponibles
• Maximum 8 outils par agent
• Support HTTP endpoints + Python handlers

Étape 5: Prompt Système

• Écrire instructions personnalisées
• Option: Générer avec IA (GPT)
• Valider et publier (status="active")

9.5 Connexion WebSocket et WebRTC

Flux de Messages

Types de Messages WebSocket

9.6 Classe AvatarLiveSession

# Blueprints/avatar_live_proxy.py

class AvatarLiveSession:
    """Gère une session avatar bidirectionnelle."""

    def __init__(self, agent_config: dict, client_ws, session_id: str):
        self.agent_config = agent_config
        self.client_ws = client_ws
        self.session_id = session_id
        self.azure_ws = None

        # État de la session
        self.is_speaking = False           # Avatar en train de parler
        self.is_response_active = False    # Réponse en cours
        self.interruptions = 0             # Compteur barge-in
        self.tools_executed = 0            # Compteur tools

        # Transcriptions
        self.transcripts = []
        self.total_tokens = {"input": 0, "output": 0}

    async def connect_to_azure(self) -> bool:
        """Connexion à Azure Voice Live API."""
        url = self._build_websocket_url()
        headers = {"api-key": self.speech_key}
        self.azure_ws = await websockets.connect(url, extra_headers=headers)
        return True

    async def send_session_update(self):
        """Envoie la configuration à Azure."""
        # Normalise la config selon le type d'avatar
        if self._is_photo_avatar():
            self._normalize_photo_avatar_config()
        else:
            self._normalize_video_avatar_config()

        await self.azure_ws.send(json.dumps({
            'type': 'session.update',
            'session': self.cached_azure_config
        }))

    async def handle_azure_message(self, message: dict):
        """Traite les messages Azure."""
        msg_type = message.get('type')

        if msg_type == 'response.function_call_arguments.done':
            # Exécuter le tool
            result = await self._execute_tool(
                message.get('call_id'),
                message.get('name'),
                message.get('arguments')
            )
            # Renvoyer le résultat
            await self._submit_tool_result(message.get('call_id'), result)

        elif msg_type == 'response.done':
            # Capturer les tokens
            usage = message.get('response', {}).get('usage', {})
            self.total_tokens['input'] += usage.get('input_tokens', 0)
            self.total_tokens['output'] += usage.get('output_tokens', 0)

    async def handle_barge_in(self):
        """Gère l'interruption utilisateur."""
        if self.is_speaking and self.is_response_active:
            self.interruptions += 1
            await self.azure_ws.send(json.dumps({'type': 'response.cancel'}))
            self.is_speaking = False
            self.is_response_active = False

9.7 Configuration Azure Complète

{
    "modalities": ["text", "audio"],
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000,
    "output_audio_timestamp_types": ["word"],

    "input_audio_echo_cancellation": {
        "type": "server_echo_cancellation"
    },
    "input_audio_noise_reduction": {
        "type": "azure_deep_noise_suppression"
    },

    "voice": {
        "name": "fr-FR-DeniseNeural",
        "type": "azure-standard",
        "temperature": 0.8,
        "rate": "1.0"
    },

    "avatar": {
        "character": "lisa",
        "style": "casual-sitting",
        "video": {
            "resolution": {"width": 1920, "height": 1080},
            "bitrate": 2000000,
            "crop": {"top_left": [560, 0], "bottom_right": [1360, 1080]},
            "background": {"color": "#FFFFFF"}
        },
        "ice_servers": [
            {"urls": ["stun:stun.l.google.com:19302"]}
        ]
    },

    "turn_detection": {
        "type": "azure_semantic_vad_multilingual",
        "threshold": 0.5,
        "silence_duration_ms": 500,
        "speech_duration_ms": 150,
        "create_response": true,
        "interrupt_response": true,
        "end_of_utterance_detection": {
            "model": "semantic_detection_v1_multilingual",
            "threshold_level": "low"
        }
    },

    "input_audio_transcription": {
        "model": "whisper-1",
        "language": "fr-FR"
    },

    "tools": [...],
    "instructions": "Tu es Sophie, assistante virtuelle..."
}

9.8 Gestion des Sessions

Schéma de Session Cosmos DB

{
    "id": "session_uuid",
    "call_id": "call_uuid",
    "agent_id": "agent_uuid",
    "agent_type": "Agent Avatar",
    "model_id": "gpt-realtime-preview",
    "status": "completed",

    "created_at": "2025-12-30T10:00:00Z",
    "updated_at": "2025-12-30T10:05:30Z",

    "history": [
        {"role": "user", "content": "Bonjour", "timestamp": "..."},
        {"role": "assistant", "content": "Bonjour !", "timestamp": "..."}
    ],

    "usage": {
        "input_tokens": 250,
        "output_tokens": 450,
        "total_tokens": 700
    },

    "metrics": {
        "duration_seconds": 330,
        "interruptions": 2,
        "tools_executed": 1,
        "final_transcript_count": 6
    }
}

9.9 Timeouts et Keep-Alive

9.10 Variables d'Environnement

# Azure Voice Live (Avatar)
VOICE_LIVE_ENDPOINT=https://westus2.api.cognitive.microsoft.com/
VOICE_LIVE_KEY=<api-key>
VOICE_LIVE_REGION=westus2

# Azure OpenAI
AZURE_OPENAI_ENDPOINT=https://...
AZURE_OPENAI_KEY=<key>

# Cosmos DB
COSMOS_URI=https://...
COSMOS_KEY=<key>
COSMOS_DATABASE_NAME=ConversationsDB

10.1 iframe

<iframe src="https://wakavoice.com/embed/agent/{id}" allow="microphone"></iframe>

10.2 Widget JavaScript

<script src="https://wakavoice.com/widget.js"></script>
<script>WakaVoice.init({agentId: 'xxx', position: 'bottom-right'});</script>

11.1 Configuration Azure Web App

11.2 Sessions Simultanées par Canal

Chaque type de canal a des caractéristiques de consommation différentes :

11.3 Projection 8h/jour (Horaires Bureau)

11.4 Projection 24h/jour (Simulation Maximale)

11.5 Impact du Paramètre MAX_SESSION

Le paramètre MAX_SESSION_PERCENTAGE impacte directement la capacité :

12.1 Comment naviguer dans l'application

12.2 Écran "Accueil" - Le tableau de bord

Description de l'écran

L'écran d'accueil est votre tableau de bord central. Il vous montre en un coup d'œil tout ce qui se passe sur votre plateforme : combien de conversations sont en cours, combien d'argent vous avez généré, et comment se portent vos agents.

Ce que vous voyez sur cet écran :

Fonctionnalités pas-à-pas

En cas de problème

12.3 Écran "Upload de Documents" (Waka AXIOM)

Description de l'écran

Cet écran vous permet d'ajouter des documents à votre base de connaissances. Ces documents seront ensuite utilisés par vos agents pour répondre aux questions des utilisateurs en s'appuyant sur leur contenu.

Ce que vous voyez sur cet écran :

Fonctionnalités pas-à-pas

En cas de problème

12.4 Écran "Crawler Web" (Waka AXIOM)

Description de l'écran

Cet écran vous permet d'indexer le contenu d'un site web. Le système va parcourir les pages du site et en extraire le texte pour que vos agents puissent répondre à des questions sur ce contenu.

Ce que vous voyez sur cet écran :

Fonctionnalités pas-à-pas

En cas de problème

12.5 Écran "Base de Connaissances" (Waka AXIOM)

Description de l'écran

Cet écran vous montre tout le contenu que vous avez ajouté (documents et sites web). Vous pouvez voir, rechercher et supprimer vos sources d'information.

Ce que vous voyez sur cet écran :

Fonctionnalités pas-à-pas

12.6 Écran "Chat" (Waka AXIOM)

Description de l'écran

C'est une interface de conversation textuelle qui répond à vos questions en utilisant votre base de connaissances. Pratique pour tester si vos documents sont bien indexés ou pour trouver rapidement une information.

Ce que vous voyez sur cet écran :

Fonctionnalités pas-à-pas

En cas de problème

12.7 Écran "Créer un Agent"

Description de l'écran

C'est l'écran le plus important ! Il vous guide en 5 étapes pour créer votre agent conversationnel. Un agent est un assistant virtuel qui pourra discuter avec vos utilisateurs par la voix, le texte ou via un avatar vidéo.

Ce que vous voyez sur cet écran :

Création pas-à-pas (les 5 étapes)

En cas de problème

12.8 Écran "Galerie des Agents"

Description de l'écran

Cet écran affiche tous vos agents sous forme de cartes. C'est votre "tableau de bord des agents" où vous pouvez les voir, les tester, les modifier ou les supprimer.

Ce que vous voyez sur cet écran :

Fonctionnalités pas-à-pas

12.9 Écran "Session Voix" (Tester un agent)

Description de l'écran

C'est l'écran où vous discutez vocalement avec votre agent. Vous parlez dans votre micro, l'agent répond à l'oral, et vous voyez la transcription de la conversation en temps réel.

Ce que vous voyez sur cet écran :

Fonctionnalités pas-à-pas

En cas de problème

12.10 Écran "Galerie des Tools"

Description de l'écran

Cet écran liste tous les outils disponibles pour vos agents. Vous y trouvez les outils système (pré-intégrés) et vos outils personnalisés.

Ce que vous voyez sur cet écran :

Fonctionnalités pas-à-pas

12.11 Écrans "Dashboards" (Qualité & Production)

Description des écrans

Ces tableaux de bord vous donnent des statistiques détaillées sur l'activité de votre plateforme.

Fonctionnalités pas-à-pas

12.12 Récapitulatif : Où trouver quoi ?

12.2 Accueil - Dashboard Principal

Route : / | Accès : Cliquer sur "Accueil" ou le logo Waka

Description

Le dashboard principal est la page d'accueil de Waka Voice. Il affiche les métriques temps réel de toutes les conversations et agents, permettant de visualiser l'activité de la plateforme en un coup d'œil.

Fonctionnalités

• Rafraîchir - Bouton pour actualiser les métriques manuellement
• Configurer taux - Modifier le taux de facturation (€/min)
• Auto-refresh - Actualisation automatique toutes les 15 minutes

Troubleshooting

12.3 Menu Waka AXIOM (RAG)

Module de gestion de la base de connaissances pour le RAG (Retrieval-Augmented Generation).

12.3.1 Upload de Documents

Route : /rag/upload | Accès : Waka AXIOM → Ajouter Documents

Description

Interface pour téléverser des fichiers depuis votre ordinateur vers la base de connaissances. Les documents sont automatiquement découpés en chunks et indexés dans Azure AI Search.

Fonctionnalités

• Zone Drag & Drop - Glisser-déposer des fichiers
• Bouton Parcourir - Sélectionner des fichiers manuellement
• Formats Supportés - PDF, DOCX, TXT, XLSX, PPTX, HTML, MD
• Barre de Progression - Suivi de l'indexation en temps réel
• Sélection Projet - Choisir le projet RAG cible

Troubleshooting

12.3.2 Crawler Web

Route : /rag/crawl | Accès : Waka AXIOM → Ajouter Sites Web

Description

Outil de crawling pour indexer le contenu de sites web. Le crawler parcourt les pages à partir d'une URL de départ et extrait le texte pour l'indexation.

Fonctionnalités

• URL de départ - URL du site à indexer
• Profondeur - Nombre de niveaux de liens à suivre (1-5)
• Limite pages - Nombre maximum de pages à crawler
• Filtres - Patterns d'URL à inclure/exclure
• Progression - Suivi en temps réel du crawl

Troubleshooting

12.3.3 Intégration SharePoint

Route : /rag/sharepoint | Accès : Waka AXIOM → Connecter SharePoint

Description

Connexion directe à Microsoft SharePoint pour synchroniser les bibliothèques de documents avec la base de connaissances.

Fonctionnalités

1. Authentification - Se connecter avec compte Microsoft 365
2. Navigation - Parcourir les bibliothèques SharePoint
3. Sélection - Cocher les dossiers à indexer
4. Synchronisation - Lancer l'import automatique
5. Planification - Configurer la synchro périodique

Troubleshooting

12.3.4 Base de Connaissances

Route : /rag/knowledge | Accès : Waka AXIOM → Base de Connaissances

Description

Vue d'ensemble de tous les documents et sources indexés dans le projet RAG actif. Permet de gérer, rechercher et supprimer des contenus.

Fonctionnalités

• Liste des sources - Tous les documents/sites indexés avec métadonnées
• Recherche - Rechercher par nom ou contenu
• Statistiques - Nombre de chunks, tokens, taille totale
• Actions - Supprimer, Ré-indexer, Voir détails
• Filtres - Par type (document, web, SharePoint)

Troubleshooting

12.3.5 Chat RAG

Route : /rag/chat-enhanced | Accès : Waka AXIOM → Chat

Description

Interface de chat conversationnel pour interroger la base de connaissances. Les réponses sont augmentées par les documents indexés avec citations des sources.

Fonctionnalités

• Recherche sémantique - Trouve les passages pertinents
• Citations - Sources des réponses avec liens
• Historique - Conversations sauvegardées
• Upload fichiers - Analyse ponctuelle d'un document
• Export - Télécharger la conversation

Troubleshooting

12.3.6 Suppression de Données

Route : /rag/deletion | Accès : Waka AXIOM → Supprimer Sources

Description

Interface sécurisée pour supprimer des sources de la base de connaissances. La suppression est définitive et retire les chunks de l'index Azure Search.

Fonctionnalités

• Sélection multiple - Cocher plusieurs sources
• Confirmation - Double validation avant suppression
• Historique - Journal des suppressions

Troubleshooting

12.3.7 Historique des Conversations RAG

Route : /rag/conversations | Accès : Waka AXIOM → Historique

Description

Historique de toutes les conversations effectuées dans le Chat RAG, avec possibilité de reprendre une conversation ou d'exporter les échanges.

Fonctionnalités

• Liste chronologique - Conversations par date
• Recherche - Trouver par mots-clés
• Reprendre - Continuer une conversation
• Exporter - Télécharger en JSON/TXT
• Supprimer - Effacer une conversation

Troubleshooting

12.4 Menu Création

12.4.1 Créer un Agent (Unifié)

Route : /agents/unified/create | Accès : Création → Créer un Agent

Description

Interface unifiée en 5 étapes pour créer tous types d'agents conversationnels : Voix, Texte ou Avatar. L'assistant guide l'utilisateur à travers la sélection du modèle, de la voix, des outils et des instructions.

Fonctionnalités

Étape 1 - Sélection du Modèle :

Étape 2 - Configuration Voix : Sélection en cascade Langue → Locale → Genre → Type → Voix

Étape 3 - Sélection des Tools : Multi-sélection parmi 30+ outils (max 8 par agent)

Étape 4 - Instructions : Prompt système avec génération IA disponible

Étape 5 - Publication : Nom de l'agent et activation

Troubleshooting

12.4.2 Créer une Voix Personnelle

Route : /creer-une-voix | Accès : Création → Voix Personnelle

Description

Interface pour cloner une voix à partir d'échantillons audio. La voix personnelle peut ensuite être utilisée par les agents pour parler avec votre voix ou celle d'un collaborateur.

Fonctionnalités

• Enregistrer - Utiliser le microphone pour capturer des échantillons
• Uploader - Importer des fichiers audio existants (WAV, MP3)
• Durée requise - Minimum 30 secondes d'audio clair
• Nom et langue - Identifier la voix
• Génération - Traitement Azure (~5-10 minutes)

Troubleshooting

12.4.3 Créer une Campagne

Route : /campaigns/create/step1 | Accès : Création → Nouvelle Campagne

Description

Assistant en 3 étapes pour configurer et lancer des campagnes d'appels sortants automatisés avec un agent voix.

Fonctionnalités

• Étape 1 - Sélection de l'agent parmi les agents publiés
• Étape 2 - Import CSV/Excel (Nom, Téléphone, Email...) avec validation
• Étape 3 - Configuration : nom, plage horaire, appels simultanés
• Lancement - Démarrage immédiat ou planifié

Troubleshooting

12.4.4 Créer un Tool

Route : /tools/add | Accès : Création → Nouveau Tool

Description

Interface pour créer des outils personnalisés que les agents peuvent utiliser pendant les conversations. Trois méthodes de création disponibles.

Fonctionnalités

Troubleshooting

12.5 Menu Galeries

12.5.1 Galerie Agents Voix

Route : /agents/gallery | Accès : Galeries → Agents → Voix

Description

Vue d'ensemble de tous les agents voix créés, avec filtres, recherche et actions rapides. Affiche les agents en grille de cartes avec leurs informations clés.

Fonctionnalités

• Statistiques - Total, Actifs, Brouillons en haut de page
• Grille de cartes - Une carte par agent avec : Badge statut, Référence, Nom, Modèle, Voix, Tools
• Filtres - Par modèle, statut, date de création
• Recherche - Par nom d'agent
• Actions - Tester, Modifier, Dupliquer, Supprimer

Troubleshooting

12.5.2 Galerie Agents Texte

Route : /text-agents/gallery | Accès : Galeries → Agents → Texte

Description

Galerie des agents conversationnels 100% texte (chatbots). Même structure que la galerie Voix avec des fonctionnalités adaptées au texte.

Fonctionnalités

• Cartes agents - Nom, modèle LLM, nombre de tools
• Test chat - Interface de chat intégrée
• Embed - Code iframe pour intégration web
• Statistiques - Messages, utilisateurs, satisfaction

Troubleshooting

12.5.3 Galerie Agents Avatar

Route : /azure-avatar/gallery | Accès : Galeries → Agents → Avatar

Description

Galerie des agents avec avatar vidéo animé. Utilise Azure Avatar Service pour le rendu vidéo temps réel avec lip-sync.

Fonctionnalités

• Avatars vidéo - 6 personnages Azure (Lisa, Harry, etc.)
• Avatars photo - VASA-1/VASA-2 (30 personnages)
• Preview - Aperçu vidéo avant test
• Session vidéo - Test avec WebRTC

Troubleshooting

12.5.4 Historique des Sessions Voix

Route : /agents/voice-history | Accès : Galeries → Historique

Description

Journal de toutes les sessions voix effectuées avec les agents. Permet de consulter les transcriptions, analyser les sentiments et exporter les données.

Fonctionnalités

• Filtres - Date, Agent, Statut, Durée, Sentiment
• Détails session - Date/Heure, Durée, Agent, Transcription
• Analyse - Sentiment, Tokens consommés, Coût
• Export - CSV, JSON
• Rejouer - Écouter l'audio (si enregistré)

Troubleshooting

12.5.5 Galerie des Campagnes

Route : /agents/campaigns/gallery | Accès : Galeries → Campagnes

Description

Vue d'ensemble de toutes les campagnes d'appels sortants créées, avec leur statut et progression.

Fonctionnalités

• Carte campagne - Nom, Agent, Statut (En cours/Terminée/Pausée)
• Progression - Barre X/Y appels effectués
• Taux de succès - Pourcentage de réussite
• Actions - Voir détails, Pause/Reprendre, Exporter

Troubleshooting

12.5.6 Galerie des Voix Personnelles

Route : /creer-une-voix/gallery | Accès : Galeries → Voix

Description

Liste de toutes les voix personnelles créées via le clonage vocal. Permet d'écouter, gérer et assigner les voix aux agents.

Fonctionnalités

• Carte voix - Nom, Langue, Date création
• Écouter - Aperçu audio de la voix
• Utiliser - Assigner à un agent
• Supprimer - Retirer la voix (irréversible)

Troubleshooting

12.5.7 Galerie des Tools

Route : /tools/ | Accès : Galeries → Tools

Description

Catalogue de tous les outils disponibles pour les agents : outils système pré-intégrés et outils personnalisés créés par l'utilisateur.

Fonctionnalités

• Filtres - Par catégorie, type (système/custom)
• Recherche - Par nom ou description
• Détails - Voir la configuration complète
• Actions - Modifier, Dupliquer, Supprimer (custom uniquement)

Troubleshooting

12.6 Menu Dashboards & Reporting

12.6.1 Dashboard Qualité

Route : /quality | Accès : Dashboards → Qualité

Description

Tableau de bord dédié à l'analyse qualitative des conversations. Affiche les métriques de sentiment, performance et satisfaction client.

Fonctionnalités

• Analyse Sentiment - Distribution positif/neutre/négatif avec graphiques
• Tendances - Évolution dans le temps (jour/semaine/mois)
• Performance par Agent - Comparaison entre agents
• Durée moyenne - Statistiques des interactions
• Taux d'interruption - Fréquence des barge-in
• Export - Télécharger les rapports

Troubleshooting

12.6.2 Dashboard Production

Route : /production/ | Accès : Dashboards → Production

Description

Tableau de bord business affichant les métriques de volume, revenus, coûts et rentabilité de la plateforme.

Fonctionnalités

• Volume d'appels - Par jour/semaine/mois avec graphiques
• Revenus générés - Facturation client calculée
• Coûts Azure - Consommation ressources (OpenAI, Speech, Search)
• Marge brute - Revenus - Coûts en temps réel
• Coût par minute - Évolution et tendances
• Comparaison - Période actuelle vs précédente

Troubleshooting

12.7 Interfaces de Session

12.7.1 Session Voix

Route : /agents/<agent_id>/session | Accès : Galerie Agents → Bouton "Tester"

Description

Interface de test en temps réel pour converser vocalement avec un agent. Utilise WebSocket pour la communication bidirectionnelle audio.

Fonctionnalités

• Header - Nom agent, statut connexion, bouton retour
• Zone conversation - Transcription utilisateur et agent
• Indicateurs - Qui parle, tools exécutés
• Contrôles - Boutons Start/Stop/Mute
• Waveform - Visualisation audio en temps réel

Indicateurs de Statut :

Troubleshooting

12.7.2 Session Avatar

Route : /azure-avatar/session/<agent_id> | Accès : Galerie Avatar → Bouton "Tester"

Description

Interface de session avec avatar vidéo animé. Combine la voix avec un rendu vidéo temps réel synchronisé sur les lèvres.

Fonctionnalités

• Zone vidéo - Affichage de l'avatar animé (720p/1080p)
• Lip-sync - Synchronisation des lèvres avec l'audio
• WebRTC - Streaming vidéo temps réel
• Contrôles - Start/Stop, Plein écran
• Transcription - Sous-titres en temps réel

Troubleshooting

12.7.3 Session Chat Texte

Route : /text-agents/chat/<agent_id> | Accès : Galerie Texte → Bouton "Tester"

Description

Interface de chat textuel avec un agent. Utilise SSE (Server-Sent Events) pour le streaming des réponses.

Fonctionnalités

• Zone de chat - Messages avec markdown supporté
• Streaming - Réponse affichée mot par mot
• Attachments - Upload de fichiers pour analyse
• Historique - Conversation sauvegardée
• Export - Télécharger la conversation

Troubleshooting

12.8 Raccourcis et Navigation Rapide

Tableau Récapitulatif des Routes

13.1 Stack Technique

13.2 Arborescence du Projet

wakavoice/
├── app.py                          # Point d'entrée Flask
├── requirements.txt                # Dépendances Python
├── .env                            # Variables d'environnement
│
├── Blueprints/                     # Routes Flask (Blueprints)
│   ├── __init__.py
│   ├── agents_config_routes.py     # CRUD agents voix (~122k)
│   ├── unified_agent_routes.py     # Création unifiée agents (~106k)
│   ├── text_agents_routes.py       # Agents texte + chat SSE (~178k)
│   ├── avatar_routes.py            # Agents avatar (~69k)
│   ├── avatar_live_proxy.py        # WebSocket proxy avatar (~78k)
│   ├── voice_live_proxy.py         # WebSocket proxy voix (~101k)
│   ├── campaign_routes.py          # Campagnes d'appels (~29k)
│   ├── conversation_history_routes.py  # Historique sessions (~34k)
│   ├── crawl_routes.py             # Crawler web RAG (~22k)
│   ├── personal_voice_routes.py    # Clonage vocal (~87k)
│   ├── prompt_builder_routes.py    # Générateur prompts (~31k)
│   ├── quality_dashboard_routes.py # Dashboard qualité (~50k)
│   ├── production_dashboard_routes.py  # Dashboard business (~28k)
│   ├── project_routes.py           # Projets RAG (~12k)
│   ├── api_document_upload.py      # Upload documents RAG (~75k)
│   ├── api_process_message_stream.py   # Chat RAG SSE (~57k)
│   ├── api_rag_search.py           # Recherche sémantique (~10k)
│   ├── api_kickoff_indexation.py   # Indexation documents (~34k)
│   └── tools/                      # Routes gestion tools
│       └── tools_routes.py         # CRUD tools dynamiques
│
├── configuration/                  # Managers Cosmos DB
│   ├── cosmos_config.py            # Client Cosmos principal (~102k)
│   ├── cosmos_agent_manager.py     # CRUD agents voix (~28k)
│   ├── cosmos_text_agent_manager.py    # CRUD agents texte (~36k)
│   ├── cosmos_unified_manager.py   # Manager unifié (~30k)
│   ├── cosmos_azure_avatar_manager_v2.py   # Agents avatar (~31k)
│   ├── cosmos_tools_manager.py     # CRUD tools (~30k)
│   ├── cosmos_session_manager.py   # Sessions voix (~14k)
│   ├── cosmos_campaign_manager.py  # Campagnes (~13k)
│   ├── cosmos_project_manager.py   # Projets RAG (~8k)
│   ├── unified_session_manager.py  # Gestion sessions (~18k)
│   ├── unified_session_closure.py  # Clôture sessions + résumé AI + sentiment (~23k)
│   ├── voice_live_config.py        # Config Azure Realtime (~18k)
│   ├── voice_live_session_builder.py   # Builder sessions (~19k)
│   ├── cost_calculator.py          # Calcul coûts Azure (~9k)
│   ├── sentiment_analysis.py       # Analyse sentiment (~9k)
│   ├── model_mapping.py            # Mapping modèles (~4k)
│   └── personal_voice_storage.py   # Stockage voix perso (~15k)
│
├── tools/                          # Outils système (built-in)
│   ├── __init__.py                 # Registry des tools (~14k)
│   ├── tool_weather.py             # Météo (~5k)
│   ├── tool_calculator.py          # Calculatrice (~3k)
│   ├── tool_email.py               # Envoi email (~11k)
│   ├── tool_translator.py          # Traduction (~8k)
│   ├── tool_search_web.py          # Recherche web (~6k)
│   ├── tool_places.py              # Google Places (~8k)
│   ├── tool_flight_search.py       # Recherche vols (~16k)
│   ├── tool_hotel_search.py        # Recherche hôtels (~16k)
│   ├── tool_knowledge_base.py      # RAG search (~7k)
│   ├── tool_end_conversation.py    # Fin conversation (~7k)
│   ├── tool_prayer_times.py        # Horaires prières (~8k)
│   ├── tool_pharmacy_locator.py    # Pharmacies (~10k)
│   ├── tool_tax_calculator.py      # Calcul impôts (~13k)
│   ├── tool_news.py                # Actualités (~8k)
│   ├── tool_currency.py            # Conversion devises (~7k)
│   ├── tool_cv.py                  # Analyse CV (~25k)
│   └── ... (30+ tools)
│
├── utils/                          # Utilitaires
│   ├── indexation.py               # Indexation Azure Search (~75k)
│   ├── chat.py                     # Helpers chat (~19k)
│   ├── prompt_generator.py         # Génération prompts IA (~12k)
│   ├── session_watchdog.py         # Monitoring sessions (~13k)
│   ├── lead_capture.py             # Capture leads (~17k)
│   └── tools/                      # Exécuteurs tools
│       └── dynamic_tool_executor.py    # Exécution tools dynamiques
│
├── templates/                      # Templates Jinja2
│   ├── base.html                   # Layout principal
│   ├── agents/                     # Pages agents voix
│   ├── text_agents/                # Pages agents texte
│   ├── azure-avatar/               # Pages avatar
│   ├── unified/                    # Création unifiée
│   ├── campaigns/                  # Pages campagnes
│   ├── RAG/                        # Pages RAG/AXIOM
│   ├── tools/                      # Pages tools
│   ├── personal_voice/             # Clonage vocal
│   ├── prompt_builder/             # Prompt builder
│   └── errors/                     # Pages erreur
│
├── static/                         # Assets statiques
│   ├── css/                        # Feuilles de style
│   ├── js/                         # JavaScript client
│   │   ├── voice_live_session.js   # Client WebSocket voix (~55k)
│   │   ├── voice_session.js        # Session voix legacy (~63k)
│   │   ├── agent_voice_session.js  # Session voix agent avec AudioSession (~29k)
│   │   ├── avatar_immersive.js     # Client avatar WebRTC (~64k)
│   │   ├── personal_voice.js       # Clonage vocal UI (~76k)
│   │   ├── prompt_builder.js       # Prompt builder UI (~37k)
│   │   ├── flow_builder.js         # Flow builder (~34k)
│   │   ├── crawl.js                # Crawler UI (~23k)
│   │   ├── upload_file.js          # Upload documents (~22k)
│   │   └── tools/                  # JS gestion tools
│   ├── images/                     # Images, logos
│   ├── fonts/                      # Polices
│   └── data/                       # Données statiques
│
├── translations/                   # Internationalisation
│   ├── fr/                         # Français
│   ├── en/                         # English
│   └── es/                         # Español
│
├── scripts/                        # Scripts utilitaires
│   └── doc_generator/              # Génération documentation
│
└── docs/                           # Documentation
    └── WAKAVOICE_DOCUMENTATION_COMPLETE.html

13.3 Infrastructure Cloud Azure

13.4 Services Azure Utilisés

13.5 Containers Cosmos DB

13.6 Flux de Données

13.6.1 Session Voix Temps Réel

13.6.2 Indexation RAG

13.7 Variables d'Environnement

# ===== Azure OpenAI =====
AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com/
AZURE_OPENAI_KEY=<api-key>
AZURE_OPENAI_API_VERSION=2025-10-01

# ===== Azure Speech Services =====
AZURE_SPEECH_KEY=<api-key>
AZURE_SPEECH_REGION=westeurope

# ===== Azure Voice Live (Realtime API) =====
VOICE_LIVE_ENDPOINT=https://<resource>.openai.azure.com/
VOICE_LIVE_KEY=<api-key>
VOICE_LIVE_REGION=swedencentral

# ===== Azure Avatar Service =====
AZURE_AVATAR_ENDPOINT=https://westus2.api.cognitive.microsoft.com/
AZURE_AVATAR_KEY=<api-key>
AZURE_AVATAR_REGION=westus2

# ===== Azure Cosmos DB =====
COSMOS_URI=https://<account>.documents.azure.com:443/
COSMOS_KEY=<primary-key>
COSMOS_DATABASE_NAME=ConversationsDB

# ===== Azure AI Search =====
AZURE_SEARCH_ENDPOINT=https://<service>.search.windows.net
AZURE_SEARCH_KEY=<admin-key>
AZURE_SEARCH_INDEX=rag-index

# ===== Azure Blob Storage =====
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;...
AZURE_STORAGE_CONTAINER=documents

# ===== Azure Communication Services (Email) =====
AZURE_COMMUNICATION_EMAIL_CONNECTION_STRING=endpoint=https://<resource>.communication.azure.com/;accesskey=<key>
AZURE_COMMUNICATION_EMAIL_SENDER=DoNotReply@<domain>.azurecomm.net

# ===== Azure OpenAI Summary (Génération résumés) =====
AZURE_OPENAI_SUMMARY_ENDPOINT=https://<resource>.openai.azure.com/
AZURE_OPENAI_SUMMARY_KEY=<api-key>
AZURE_OPENAI_SUMMARY_DEPLOYMENT=gpt-5-mini
AZURE_OPENAI_SUMMARY_API_VERSION=2025-01-01-preview

# ===== Azure Text Analytics (Analyse sentiment) =====
TEXT_ANALYTICS_ENDPOINT=https://<resource>.cognitiveservices.azure.com/
TEXT_ANALYTICS_KEY=<api-key>

# ===== Application =====
FLASK_SECRET_KEY=<random-secret>
FLASK_ENV=production

13.8 Déploiement

13.8.1 Prérequis

• Python 3.11+
• Compte Azure avec les services activés
• Azure CLI installé

13.8.2 Installation Locale

# Cloner le repository
git clone https://github.com/your-org/wakavoice.git
cd wakavoice

# Créer environnement virtuel
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

# Installer dépendances
pip install -r requirements.txt

# Configurer variables d'environnement
cp .env.example .env
# Éditer .env avec vos clés Azure

# Lancer l'application
flask run --host=0.0.0.0 --port=5000

13.8.3 Déploiement Azure App Service

# Login Azure
az login

# Créer resource group
az group create --name rg-wakavoice --location francecentral

# Créer App Service Plan
az appservice plan create \
    --name plan-wakavoice \
    --resource-group rg-wakavoice \
    --sku P1V3 \
    --is-linux

# Créer Web App
az webapp create \
    --name wakavoice-app \
    --resource-group rg-wakavoice \
    --plan plan-wakavoice \
    --runtime "PYTHON:3.11"

# Configurer variables d'environnement
az webapp config appsettings set \
    --name wakavoice-app \
    --resource-group rg-wakavoice \
    --settings @appsettings.json

# Déployer le code
az webapp deployment source config-local-git \
    --name wakavoice-app \
    --resource-group rg-wakavoice

git remote add azure <git-url>
git push azure master

13.9 Télécharger le Code Source

14.1 Flux Complet Session Avatar (WebRTC + ICE)

Ce diagramme illustre le flux complet d'établissement d'une session avatar avec négociation WebRTC, signaling ICE et streaming vidéo/audio.

Composants ICE/TURN

14.2 Pipeline RAG Détaillé (Chunking → Embedding → Search)

Architecture complète du système RAG (Retrieval-Augmented Generation) depuis l'ingestion des documents jusqu'à la génération de réponses.

Paramètres de Chunking

14.3 Architecture Multi-Tenant

Waka Voice supporte une architecture multi-tenant où chaque organisation dispose de ses propres agents, données et configurations isolées.

Stratégie d'Isolation

Schéma Cosmos DB Multi-Tenant

{
    "id": "agent-uuid-123",
    "tenant_id": "tenant_a",           // Partition Key
    "type": "VoiceAgent",
    "name": "Agent Commercial",
    "created_by": "user@tenant-a.com",
    "config": {
        "model_id": "gpt-4o-realtime",
        "voice": "fr-FR-DeniseNeural",
        "tools": ["weather", "email"]
    },
    "_tenant_isolated": true,          // Flag isolation
    "_ts": 1703980800
}

15.1 Vue d'Ensemble des Ressources

15.2 Ressources de Calcul

15.3 Ressources IA & Cognitive

15.4 Ressources de Donnees

15.5 Ressources Reseau & Securite

15.6 Recapitulatif des Couts par Ressource

16.1 Modeles Texte (Chat/LLM)

16.1.1 Famille F3 - GPT-5 (Derniere Generation)

16.1.2 Famille F2 - GPT-4.x (Generation Precedente)

16.1.3 Modeles Alternatifs (Azure AI Foundry)

16.2 Azure Voice Live API

16.2.1 Famille F1 - Audio Natif (Realtime)

Les modeles F1 traitent l'audio nativement sans pipeline STT/TTS separe :

16.2.2 Famille F2 - TTS Real-time (GPT-4.x)

Les modeles F2 utilisent le mode TTS Real-time via Azure Speech Services :

16.2.3 Famille F3 - TTS Real-time (GPT-5)

Les modeles F3 (derniere generation) utilisent egalement le mode TTS Real-time :

16.2.4 Comparaison des Modes Audio

16.2.5 Voix Natives OpenAI (F1 uniquement)

Les modeles F1 incluent des voix synthetiques natives de haute qualite :

16.2.6 Tiers de Tarification Voice Live